From 5bea92194f2afa6efd54972395943f77635e8373 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Fri, 9 Feb 2024 14:50:20 -0600 Subject: [PATCH 1/2] Document using default OS account with WAM --- sdk/identity/Azure.Identity.Broker/README.md | 61 ++++++++----------- .../tests/Azure.Identity.Broker.Tests.csproj | 7 ++- .../tests/samples/ReadmeSnippets.cs | 20 +++++- 3 files changed, 48 insertions(+), 40 deletions(-) diff --git a/sdk/identity/Azure.Identity.Broker/README.md b/sdk/identity/Azure.Identity.Broker/README.md index 6c064a9759720..dea8736a861ee 100644 --- a/sdk/identity/Azure.Identity.Broker/README.md +++ b/sdk/identity/Azure.Identity.Broker/README.md @@ -1,6 +1,6 @@ # Azure Identity Brokered Authentication client library for .NET -The library extends the Azure.Identity library to provide authentication broker support. It includes the necessary dependencies and provides the `InteractiveBrowserCredentialBrokerOptions` class. This options class can be used to create an `InteractiveBrowserCredential` capable of using the system authentication broker in lieu of an embedded web view or the system browser. +The library extends the `Azure.Identity` library to provide authentication broker support. It includes the necessary dependencies and provides the `InteractiveBrowserCredentialBrokerOptions` class. This options class can be used to create an `InteractiveBrowserCredential` capable of using the system authentication broker in lieu of an embedded web view or the system browser. [Source code][source] | [Package (NuGet)][package] | [API reference documentation][identity_api_docs] | [Microsoft Entra ID documentation][entraid_doc] @@ -10,18 +10,19 @@ The library extends the Azure.Identity library to provide authentication broker Install the Azure Identity client library for .NET with [NuGet][nuget]: -```PowerShell +```dotnetcli dotnet add package Azure.Identity.Broker ``` ### Prerequisites -* The [Azure.Identity][azure_identity] library is a dependency of Azure.Identity.Broker. + +The [Azure.Identity][azure_identity] library is a dependency of `Azure.Identity.Broker`. ### Authenticate the client ## Key concepts -This package enables authentication broker support via `InteractiveBrowserCredentialBrokerOptions`, in combination with `InteractiveBrowserCredential` in the `Azure.Identity` package. +This package enables authentication broker support via [InteractiveBrowserCredentialBrokerOptions](https://learn.microsoft.com/dotnet/api/azure.identity.broker.interactivebrowsercredentialbrokeroptions), in combination with `InteractiveBrowserCredential` in the `Azure.Identity` package. ### Parent window handles @@ -41,7 +42,7 @@ ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id} ## Examples -### Configuring the `InteractiveBrowserCredential` to use the system authentication broker +### Configure the `InteractiveBrowserCredential` to use the system authentication broker This example demonstrates configuring the `InteractiveBrowserCredential` with the specialized options type `InteractiveBrowserCredentialBrokerOptions` to enable brokered authentication. @@ -49,17 +50,29 @@ This example demonstrates configuring the `InteractiveBrowserCredential` with th IntPtr parentWindowHandle = GetForegroundWindow(); // Create an interactive browser credential which will use the system authentication broker -var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle)); +var credential = new InteractiveBrowserCredential( + new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle)); // Use the credential to authenticate a secret client var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential); ``` +To bypass the account selection dialog and use the account currently signed in to the operating system, set the [InteractiveBrowserCredentialBrokerOptions.UseOperatingSystemAccount](https://learn.microsoft.com/dotnet/api/azure.identity.broker.interactivebrowsercredentialbrokeroptions.useoperatingsystemaccount) property: + +```C# Snippet:ConfigureInteractiveBrowserToUseDefaultOsAccount +var credential = new InteractiveBrowserCredential( + new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle) + { + UseOperatingSystemAccount = true, + }); +``` + ## Troubleshooting See the [troubleshooting guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/TROUBLESHOOTING.md) for details on how to diagnose various failure scenarios. -### Error Handling +### Error handling + Errors arising from authentication can be raised on any service client method which makes a request to the service. This is because the first time the token is requested from the credential is on the first call to the service, and any subsequent calls might need to refresh the token. In order to distinguish these failures from failures in the service client Azure Identity classes raise the `AuthenticationFailedException` with details to the source of the error in the exception message as well as possibly the error message. Depending on the application these errors may or may not be recoverable. ``` c# @@ -109,10 +122,12 @@ DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions() > CAUTION: Requests and responses in the Azure Identity library contain sensitive information. Precaution must be taken to protect logs when customizing the output to avoid compromising account security. ### Thread safety + We guarantee that all credential instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)). This ensures that the recommendation of reusing credential instances is always safe, even across threads. ### Additional concepts + [Client options](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#configuring-service-clients-using-clientoptions) | [Accessing the response](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/README.md#accessing-http-response-details-using-responset) | [Diagnostics](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/core/Azure.Core/samples/Diagnostics.md) | @@ -126,9 +141,9 @@ This ensures that the recommendation of reusing credential instances is always s Many of the client libraries listed [here](https://azure.github.io/azure-sdk/releases/latest/dotnet.html) support authenticating with `TokenCredential` and the Azure Identity library. There you will also find links where you can learn more about their use, including additional documentation and samples. -### Known Issues +### Known issues -This library does not currently support scenarios relating to the [AAD B2C](https://docs.microsoft.com/azure/active-directory-b2c/overview) service. +This library does not currently support scenarios relating to the [AAD B2C](https://learn.microsoft.com/azure/active-directory-b2c/overview) service. Currently open issues for the Azure.Identity library can be found [here](https://github.com/Azure/azure-sdk-for-net/issues?q=is%3Aissue+is%3Aopen+label%3AAzure.Identity). @@ -140,41 +155,15 @@ When you submit a pull request, a CLA-bot will automatically determine whether y This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact opencode@microsoft.com with any additional questions or comments. -[azure_cli]: https://docs.microsoft.com/cli/azure -[azure_powerShell]: https://docs.microsoft.com/powershell/azure [azure_sub]: https://azure.microsoft.com/free/dotnet/ [azure_identity]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity/README.md [source]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity.Broker/src [package]: https://www.nuget.org/packages/Azure.Identity.Broker [entraid_doc]: https://learn.microsoft.com/entra/identity/ [entraid_err_doc]: https://learn.microsoft.com/entra/identity-platform/reference-error-codes -[certificates_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Certificates [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ [code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/ [nuget]: https://www.nuget.org/ -[keys_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Keys -[secrets_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Secrets -[blobs_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/storage/Azure.Storage.Blobs -[queues_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/storage/Azure.Storage.Queues -[eventhubs_client_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/eventhub/Azure.Messaging.EventHubs -[azure_core_library]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/core/Azure.Core -[identity_api_docs]: https://docs.microsoft.com/dotnet/api/azure.identity?view=azure-dotnet -[vs_login_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-net/main/sdk/identity/Azure.Identity/images/VsLoginDialog.png -[azure_cli_login_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-net/main/sdk/identity/Azure.Identity/images/AzureCliLogin.png -[azure_cli_login_device_code_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-net/main/sdk/identity/Azure.Identity/images/AzureCliLoginDeviceCode.png -[ref_DefaultAzureCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet -[ref_ChainedTokenCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.chainedtokencredential?view=azure-dotnet -[ref_EnvironmentCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.environmentcredential?view=azure-dotnet -[ref_ManagedIdentityCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.managedidentitycredential?view=azure-dotnet -[ref_ClientSecretCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.clientsecretcredential?view=azure-dotnet -[ref_ClientCertificateCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.clientcertificatecredential?view=azure-dotnet -[ref_InteractiveBrowserCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.interactivebrowsercredential?view=azure-dotnet -[ref_DeviceCodeCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.devicecodecredential?view=azure-dotnet -[ref_UsernamePasswordCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.usernamepasswordcredential?view=azure-dotnet -[ref_AuthorizationCodeCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.authorizationcodecredential?view=azure-dotnet -[ref_AzureCliCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.azureclicredential?view=azure-dotnet -[ref_AzurePowerShellCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/src/AzurePowerShellCredential.cs -[ref_VisualStudioCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.visualstudiocredential?view=azure-dotnet -[ref_VisualStudioCodeCredential]: https://docs.microsoft.com/dotnet/api/azure.identity.visualstudiocodecredential?view=azure-dotnet +[identity_api_docs]: https://learn.microsoft.com/dotnet/api/azure.identity?view=azure-dotnet ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fidentity%2FAzure.Identity%2FREADME.png) diff --git a/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj b/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj index 103bb6bce5e18..832ac31779623 100644 --- a/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj +++ b/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj @@ -23,9 +23,10 @@ - - - + + + + diff --git a/sdk/identity/Azure.Identity.Broker/tests/samples/ReadmeSnippets.cs b/sdk/identity/Azure.Identity.Broker/tests/samples/ReadmeSnippets.cs index e7869cdc9e03b..217016a8f8e8c 100644 --- a/sdk/identity/Azure.Identity.Broker/tests/samples/ReadmeSnippets.cs +++ b/sdk/identity/Azure.Identity.Broker/tests/samples/ReadmeSnippets.cs @@ -21,11 +21,29 @@ public void ConfigureInteractiveBrowserToUseBroker() IntPtr parentWindowHandle = GetForegroundWindow(); // Create an interactive browser credential which will use the system authentication broker - var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle)); + var credential = new InteractiveBrowserCredential( + new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle)); // Use the credential to authenticate a secret client var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential); #endregion } + + [Test] + public void ConfigureInteractiveBrowserToUseDefaultOsAccount() + { + IntPtr parentWindowHandle = GetForegroundWindow(); + + #region Snippet:ConfigureInteractiveBrowserToUseDefaultOsAccount + var credential = new InteractiveBrowserCredential( + new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle) + { + UseOperatingSystemAccount = true, + }); + #endregion + + // Use the credential to authenticate a secret client + var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential); + } } } From d90e7705846b9ab282ee0aa4e2ceca13f1a4d5c0 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Fri, 9 Feb 2024 16:05:09 -0600 Subject: [PATCH 2/2] Exclude samples folder from project, as it was before --- .../tests/Azure.Identity.Broker.Tests.csproj | 1 - 1 file changed, 1 deletion(-) diff --git a/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj b/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj index 832ac31779623..7a1d6f3bdae88 100644 --- a/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj +++ b/sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj @@ -26,7 +26,6 @@ -