Skip to content

Commit

Permalink
Document using default OS account with WAM (#41877)
Browse files Browse the repository at this point in the history 
* Document using default OS account with WAM

* Exclude samples folder from project, as it was before
  • Loading branch information
@scottaddie
scottaddie authored Feb 9, 2024
1 parent fef0ef3 commit 4adc603
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 40 deletions.
61 changes: 25 additions & 36 deletions sdk/identity/Azure.Identity.Broker/README.md
View file
Original file line number Diff line number Diff line change
@@ -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]

Expand All @@ -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

Expand All @@ -41,25 +42,37 @@ 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.

```C# Snippet: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);
```

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#
Expand Down Expand Up @@ -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) |
Expand All @@ -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).

Expand All @@ -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 [email protected] with any additional questions or comments.

<!-- LINKS -->
[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)
6 changes: 3 additions & 3 deletions sdk/identity/Azure.Identity.Broker/tests/Azure.Identity.Broker.Tests.csproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@
</ItemGroup>
<ItemGroup>
<Compile Include="$(AzureCoreSharedSources)ForwardsClientCallsAttribute.cs" LinkBase="Shared" />
<Compile Include="*.cs" Exclude="*Manual*.cs"/>
<Compile Include="ManualInteractiveBrowserCredentialBrokerTests.cs" Condition="$([MSBuild]::IsOsPlatform('Windows'))"/>
<Compile Include="ManualSharedTokenCacheCredentialBrokerTests.cs" Condition="$([MSBuild]::IsOsPlatform('Windows'))"/>
<Compile Include="*.cs" Exclude="*Manual*.cs" />
<Compile Include="ManualInteractiveBrowserCredentialBrokerTests.cs" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
<Compile Include="ManualSharedTokenCacheCredentialBrokerTests.cs" Condition="$([MSBuild]::IsOsPlatform('Windows'))" />
</ItemGroup>

</Project>
20 changes: 19 additions & 1 deletion sdk/identity/Azure.Identity.Broker/tests/samples/ReadmeSnippets.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
}
}

0 comments on commit 4adc603

Please sign in to comment.