diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 4dab0986ea5b6..82357ba234178 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -71,6 +71,7 @@ "dotnetcli", "dtmf", "eastus", + "entra", "epsg", "expando", "fhir", diff --git a/sdk/identity/Azure.Identity.BrokeredAuthentication/README.md b/sdk/identity/Azure.Identity.BrokeredAuthentication/README.md index 643b5d77d7d21..9239f9514ff13 100644 --- a/sdk/identity/Azure.Identity.BrokeredAuthentication/README.md +++ b/sdk/identity/Azure.Identity.BrokeredAuthentication/README.md @@ -1,7 +1,7 @@ # 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 the system browser when available. + 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 the system browser when available. - [Source code][source] | [Package (nuget)][package] | [API reference documentation][identity_api_docs] | [Azure Active Directory documentation][aad_doc] + [Source code][source] | [Package (nuget)][package] | [API reference documentation][identity_api_docs] | [Microsoft Entra ID documentation][aad_doc] ## Getting started @@ -60,7 +60,7 @@ catch (AuthenticationFailedException e) } ``` -For more details on dealing with errors arising from failed requests to Azure Active Directory, or managed identity endpoints please refer to the Azure Active Directory [documentation on authorization error codes][aad_err_doc]. +For more details on dealing with errors arising from failed requests to Microsoft Entra ID, or managed identity endpoints please refer to the Microsoft Entra ID [documentation on authorization error codes][aad_err_doc]. ### Logging diff --git a/sdk/identity/Azure.Identity/CHANGELOG.md b/sdk/identity/Azure.Identity/CHANGELOG.md index 3979a75b0b42b..f1d2199a1e8b9 100644 --- a/sdk/identity/Azure.Identity/CHANGELOG.md +++ b/sdk/identity/Azure.Identity/CHANGELOG.md @@ -78,7 +78,7 @@ ## 1.8.2 (2023-02-08) ### Bugs Fixed -- Fixed error message parsing in `AzurePowerShellCredential` which would misinterpret AAD errors with the need to install PowerShell. [#31998](https://github.com/Azure/azure-sdk-for-net/issues/31998) +- Fixed error message parsing in `AzurePowerShellCredential` which would misinterpret Microsoft Entra ID errors with the need to install PowerShell. [#31998](https://github.com/Azure/azure-sdk-for-net/issues/31998) - Fix regional endpoint validation error when using `ManagedIdentityCredential`. [#32498])(https://github.com/Azure/azure-sdk-for-net/issues/32498) ## 1.8.1 (2023-01-13) @@ -89,7 +89,7 @@ ## 1.8.0 (2022-11-08) ### Bugs Fixed -- Fixed error message parsing in `AzureCliCredential` which would misinterpret AAD errors with the need to login with `az login`. [#26894](https://github.com/Azure/azure-sdk-for-net/issues/26894), [#29109](https://github.com/Azure/azure-sdk-for-net/issues/29109) +- Fixed error message parsing in `AzureCliCredential` which would misinterpret Microsoft Entra ID errors with the need to login with `az login`. [#26894](https://github.com/Azure/azure-sdk-for-net/issues/26894), [#29109](https://github.com/Azure/azure-sdk-for-net/issues/29109) - `ManagedIdentityCredential` will no longer fail when a response received from the endpoint is invalid JSON. It now treats this scenario as if the credential is unavailable. [#30467](https://github.com/Azure/azure-sdk-for-net/issues/30467), [#32061](https://github.com/Azure/azure-sdk-for-net/issues/32061) ## 1.9.0-beta.1 (2022-10-13) @@ -216,7 +216,7 @@ Thank you to our developer community members who helped to make Azure Identity b ### Features Added - `DefaultAzureCredentialOptions` now has a `InteractiveBrowserClientId` property which allows passing a ClientId value to the `InteractiveBrowserCredential` when constructing a `DefaultAzureCredential`. -- Implement `OnBehalfOfCredential` which enables authentication to Azure Active Directory using an On-Behalf-Of flow. +- Implement `OnBehalfOfCredential` which enables authentication to Microsoft Entra ID using an On-Behalf-Of flow. - Added support to `ManagedIdentityCredential` for Azure hosts using federated token exchange for managed identity. ### Bugs Fixed @@ -226,7 +226,7 @@ Thank you to our developer community members who helped to make Azure Identity b ### Other Changes - Updated credentials using `MsalConfidentialClient` to include MSAL log output in logs -- Added additional logging to `AzureCliCredential`, `AzurePowerShellCredential`, `VisualStudioCrednetial`, and `VisualStudioCodeCredential` when `IsPIILoggingEnabled` is set to true. +- Added additional logging to `AzureCliCredential`, `AzurePowerShellCredential`, `VisualStudioCredential`, and `VisualStudioCodeCredential` when `IsPIILoggingEnabled` is set to true. ## 1.5.0-beta.3 (2021-08-10) @@ -270,7 +270,7 @@ Thank you to our developer community members who helped to make Azure Identity b - Added support to `ManagedIdentityCredential` for Bridge to Kubernetes local development authentication. - TenantId values returned from service challenge responses can now be used to request tokens from the correct tenantId. To support this feature, there is a new `AllowMultiTenantAuthentication` option on `TokenCredentialOptions`. - By default, `AllowMultiTenantAuthentication` is false. When this option property is false and the tenant Id configured in the credential options differs from the tenant Id set in the `TokenRequestContext` sent to a credential, an `AuthorizationFailedException` will be thrown. This is potentially breaking change as it could be a different exception than what was thrown previously. This exception behavior can be overridden by either setting an `AppContext` switch named "Azure.Identity.EnableLegacyTenantSelection" to `true` or by setting the environment variable "AZURE_IDENTITY_ENABLE_LEGACY_TENANT_SELECTION" to "true". Note: AppContext switches can also be configured via configuration like below: -- Added `OnBehalfOfFlowCredential` which enables support for AAD On-Behalf-Of (OBO) flow. See the [Azure Active Directory documentation](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) to learn more about OBO flow scenarios. +- Added `OnBehalfOfFlowCredential` which enables support for Microsoft Entra On-Behalf-Of (OBO) flow. See the [Microsoft Entra ID documentation](https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) to learn more about OBO flow scenarios. ```xml @@ -290,7 +290,7 @@ Thank you to our developer community members who helped to make Azure Identity b ### New Features - By default, the MSAL Public Client Client Capabilities are populated with "CP1" to enable support for [Continuous Access Evaluation (CAE)](https://docs.microsoft.com/azure/active-directory/develop/app-resilience-continuous-access-evaluation). -This indicates to AAD that your application is CAE ready and can handle the CAE claim challenge. This capability can be disabled, if necessary, by either setting an `AppContext` switch named "Azure.Identity.DisableCP1" to `true` or by setting the environment variable; +This indicates to Microsoft Entra ID that your application is CAE ready and can handle the CAE claim challenge. This capability can be disabled, if necessary, by either setting an `AppContext` switch named "Azure.Identity.DisableCP1" to `true` or by setting the environment variable; "AZURE_IDENTITY_DISABLE_CP1" to "true". Note: AppContext switches can also be configured via configuration like below: ```xml diff --git a/sdk/identity/Azure.Identity/README.md b/sdk/identity/Azure.Identity/README.md index ea4aa4bdd14d1..f01f3b2222c56 100644 --- a/sdk/identity/Azure.Identity/README.md +++ b/sdk/identity/Azure.Identity/README.md @@ -1,8 +1,8 @@ # Azure Identity client library for .NET -The Azure Identity library provides [Azure Active Directory (Azure AD)](https://learn.microsoft.com/azure/active-directory/fundamentals/active-directory-whatis) token authentication support across the Azure SDK. It provides a set of [`TokenCredential`](https://learn.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) implementations which can be used to construct Azure SDK clients which support Azure AD token authentication. +The Azure Identity library provides [Microsoft Entra ID](https://learn.microsoft.com/azure/active-directory/fundamentals/active-directory-whatis) ([formerly Azure Active Directory](https://learn.microsoft.com/azure/active-directory/fundamentals/new-name)) token authentication support across the Azure SDK. It provides a set of [`TokenCredential`](https://learn.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) implementations which can be used to construct Azure SDK clients which support Microsoft Entra token authentication. - [Source code][source] | [Package (NuGet)][package] | [API reference documentation][identity_api_docs] | [Azure AD documentation][aad_doc] + [Source code][source] | [Package (NuGet)][package] | [API reference documentation][identity_api_docs] | [Microsoft Entra ID documentation][aad_doc] ## Getting started @@ -25,9 +25,9 @@ When debugging and executing code locally it is typical for a developer to use t #### Authenticate via Visual Studio -Developers using Visual Studio 2017 or later can authenticate an Azure AD account through the IDE. Applications using the `DefaultAzureCredential` or the `VisualStudioCredential` can then use this account to authenticate calls in their application when running locally. +Developers using Visual Studio 2017 or later can authenticate a Microsoft Entra account through the IDE. Applications using the `DefaultAzureCredential` or the `VisualStudioCredential` can then use this account to authenticate calls in their application when running locally. -To authenticate in Visual Studio, select the **Tools** > **Options** menu to launch the Options dialog. Then navigate to the `Azure Service Authentication` options to sign in with your Azure AD account. +To authenticate in Visual Studio, select the **Tools** > **Options** menu to launch the Options dialog. Then navigate to the `Azure Service Authentication` options to sign in with your Microsoft Entra account. ![Visual Studio Account Selection][vs_login_image] @@ -71,7 +71,7 @@ For systems without a default web browser, the `Connect-AzAccount` command will A credential is a class which contains or can obtain the data needed for a service client to authenticate requests. Service clients across the Azure SDK accept credentials when they're constructed. Service clients use those credentials to authenticate requests to the service. -The Azure Identity library focuses on OAuth authentication with Azure AD, and it offers a variety of credential classes capable of acquiring an Azure AD token to authenticate service requests. All of the credential classes in this library are implementations of the `TokenCredential` abstract class in [Azure.Core][azure_core_library], and any of them can be used to construct service clients capable of authenticating with a `TokenCredential`. +The Azure Identity library focuses on OAuth authentication with Microsoft Entra ID, and it offers a variety of credential classes capable of acquiring a Microsoft Entra token to authenticate service requests. All of the credential classes in this library are implementations of the `TokenCredential` abstract class in [Azure.Core][azure_core_library], and any of them can be used to construct service clients capable of authenticating with a `TokenCredential`. See [Credential Classes](#credential-classes) for a complete listing of available credential types. @@ -182,7 +182,7 @@ var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), crede ## Cloud configuration -Credentials default to authenticating to the Azure AD endpoint for the Azure public cloud. To access resources in other clouds, such as Azure Government or a private cloud, configure credentials with the `AuthorityHost` argument. [AzureAuthorityHosts](https://learn.microsoft.com/dotnet/api/azure.identity.azureauthorityhosts?view=azure-dotnet) defines authorities for well-known clouds: +Credentials default to authenticating to the Microsoft Entra endpoint for the Azure public cloud. To access resources in other clouds, such as Azure Government or a private cloud, configure credentials with the `AuthorityHost` argument. [AzureAuthorityHosts](https://learn.microsoft.com/dotnet/api/azure.identity.azureauthorityhosts?view=azure-dotnet) defines authorities for well-known clouds: ```C# Snippet:AuthenticatingWithAuthorityHost var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { AuthorityHost = AzureAuthorityHosts.AzureGovernment }); @@ -200,7 +200,7 @@ Not all credentials require this configuration. Credentials which authenticate t |[`ChainedTokenCredential`][ref_ChainedTokenCredential]|Allows users to define custom authentication flows composing multiple credentials. |[`EnvironmentCredential`][ref_EnvironmentCredential]|Authenticates a service principal or user via credential information specified in environment variables. |[`ManagedIdentityCredential`][ref_ManagedIdentityCredential]|Authenticates the managed identity of an Azure resource. -|[`WorkloadIdentityCredential`][ref_WorkloadIdentityCredential]|Supports [Azure AD workload identity](https://learn.microsoft.com/azure/aks/workload-identity-overview) on Kubernetes. +|[`WorkloadIdentityCredential`][ref_WorkloadIdentityCredential]|Supports [Microsoft Entra Workload ID](https://learn.microsoft.com/azure/aks/workload-identity-overview) on Kubernetes. ### Authenticate service principals @@ -240,16 +240,16 @@ Not all credentials require this configuration. Credentials which authenticate t |Variable name|Value |-|- -|`AZURE_CLIENT_ID`|ID of an Azure AD application -|`AZURE_TENANT_ID`|ID of the application's Azure AD tenant +|`AZURE_CLIENT_ID`|ID of a Microsoft Entra application +|`AZURE_TENANT_ID`|ID of the application's Microsoft Entra tenant |`AZURE_CLIENT_SECRET`|one of the application's client secrets #### Service principal with certificate |variable name|Value |-|- -|`AZURE_CLIENT_ID`|ID of an Azure AD application -|`AZURE_TENANT_ID`|ID of the application's Azure AD tenant +|`AZURE_CLIENT_ID`|ID of a Microsoft Entra application +|`AZURE_TENANT_ID`|ID of the application's Microsoft Entra tenant |`AZURE_CLIENT_CERTIFICATE_PATH`|path to a PFX or PEM-encoded certificate file including private key |`AZURE_CLIENT_CERTIFICATE_PASSWORD`|(optional) the password protecting the certificate file (currently only supported for PFX (PKCS12) certificates) |`AZURE_CLIENT_SEND_CERTIFICATE_CHAIN`|(optional) send certificate chain in x5c header to support subject name / issuer based authentication @@ -258,8 +258,8 @@ Not all credentials require this configuration. Credentials which authenticate t |Variable name|Value |-|- -|`AZURE_CLIENT_ID`|ID of an Azure AD application -|`AZURE_TENANT_ID`|ID of the application's Azure AD tenant +|`AZURE_CLIENT_ID`|ID of a Microsoft Entra application +|`AZURE_TENANT_ID`|ID of the application's Microsoft Entra tenant |`AZURE_USERNAME`|a username (usually an email address) |`AZURE_PASSWORD`|that user's password @@ -277,7 +277,7 @@ Token caching is a feature provided by the Azure Identity library that allows ap * Cache tokens in memory (default) or on disk (opt-in). * Improve resilience and performance. -* Reduce the number of requests made to Azure Active Directory (Azure AD) to obtain access tokens. +* Reduce the number of requests made to Microsoft Entra ID to obtain access tokens. The Azure Identity library offers both in-memory and persistent disk caching. For more details, see the [token caching documentation](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md) @@ -306,7 +306,7 @@ catch (AuthenticationFailedException e) } ``` -For more information on dealing with errors arising from failed requests to Azure AD or managed identity endpoints, see the Azure AD [documentation on authorization error codes][aad_err_doc]. +For more information on dealing with errors arising from failed requests to Microsoft Entra ID or managed identity endpoints, see the Microsoft Entra ID [documentation on authorization error codes][aad_err_doc]. ### Logging diff --git a/sdk/identity/Azure.Identity/TROUBLESHOOTING.md b/sdk/identity/Azure.Identity/TROUBLESHOOTING.md index d127b396981c3..d8441ac5d9bdc 100644 --- a/sdk/identity/Azure.Identity/TROUBLESHOOTING.md +++ b/sdk/identity/Azure.Identity/TROUBLESHOOTING.md @@ -1,4 +1,4 @@ -# Troubleshoot Azure Identity authentication issues +# Troubleshoot Azure Identity authentication issues This troubleshooting guide covers failure investigation techniques, common errors for the credential types in the Azure Identity library for .NET, and mitigation steps to resolve these errors. @@ -67,7 +67,7 @@ Calls to service clients resulting in `RequestFailedException` with a `StatusCod ## Find relevant information in exception messages -`AuthenticationFailedException` is thrown when unexpected errors occurred while a credential is authenticating. This can include errors received from requests to the Azure AD STS and often contains information helpful to diagnosis. Consider the following `AuthenticationFailedException` message. +`AuthenticationFailedException` is thrown when unexpected errors occurred while a credential is authenticating. This can include errors received from requests to the Microsoft Entra STS and often contains information helpful to diagnosis. Consider the following `AuthenticationFailedException` message. ![AuthenticationFailedException Message Example](https://raw.githubusercontent.com/Azure/azure-sdk-for-net/main/sdk/identity/Azure.Identity/images/AuthFailedErrorMessageExample.png) @@ -75,7 +75,7 @@ This error contains several pieces of information: - __Failing Credential Type__: The type of credential that failed to authenticate. This can be helpful when diagnosing issues with chained credential types such as `DefaultAzureCredential` or `ChainedTokenCredential`. -- __STS Error Code and Message__: The error code and message returned from the Azure AD STS. This can give insight into the specific reason the request failed. For instance, in this specific case because the provided client secret is incorrect. More information on STS error codes can be found [here](https://learn.microsoft.com/azure/active-directory/develop/reference-aadsts-error-codes#aadsts-error-codes). +- __STS Error Code and Message__: The error code and message returned from the Microsoft Entra STS. This can give insight into the specific reason the request failed. For instance, in this specific case because the provided client secret is incorrect. More information on STS error codes can be found [here](https://learn.microsoft.com/azure/active-directory/develop/reference-aadsts-error-codes#aadsts-error-codes). - __Correlation ID and Timestamp__: The correlation ID and call Timestamp used to identify the request in server-side logs. This information can be useful to support engineers when diagnosing unexpected STS failures. @@ -138,7 +138,7 @@ DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions() | Error Code | Description | Mitigation | |---|---|---| -|AADSTS700027|Client assertion contains an invalid signature.|Ensure the specified certificate has been uploaded to the Azure AD application registration. Instructions for uploading certificates to the application registration can be found [here](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-1-upload-a-certificate).| +|AADSTS700027|Client assertion contains an invalid signature.|Ensure the specified certificate has been uploaded to the Microsoft Entra application registration. Instructions for uploading certificates to the application registration can be found [here](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-1-upload-a-certificate).| |AADSTS700016|The specified application wasn't found in the specified tenant.| Ensure the specified `clientId` and `tenantId` are correct for your application registration. For multi-tenant apps, ensure the application has been added to the desired tenant by a tenant admin. To add a new application in the desired tenant, follow the instructions [here](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). ## Troubleshoot `ClientAssertionCredential` authentication issues @@ -165,7 +165,7 @@ DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions() | Error Message |Description| Mitigation | |---|---|---| -|`CredentialUnavailableException` raised with message. "WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured."|The `WorkloadIdentityCredential` requires `ClientId`, `TenantId` and `TokenFilePath` to authenticate with Azure Active Directory.| +|`CredentialUnavailableException` raised with message. "WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured."|The `WorkloadIdentityCredential` requires `ClientId`, `TenantId` and `TokenFilePath` to authenticate with Microsoft Entra ID.| |The workload options are not fully configured.|The workload identity configuration wasn't provided in environment variables or through `WorkloadIdentityCredentialOptions`.|Ensure the appropriate environment variables are set **prior to application startup** or are specified in code.