From 6b3ce4d35a82263ed48260e9bb8490bf93683ae1 Mon Sep 17 00:00:00 2001 From: g2vinay Date: Wed, 11 Aug 2021 13:07:37 -0700 Subject: [PATCH 1/9] update --- sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md diff --git a/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md b/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md new file mode 100644 index 000000000000..e69de29bb2d1 From 244a24813a978c9f03cc1304a2198c7b48ee3f8a Mon Sep 17 00:00:00 2001 From: Vinay Gera Date: Wed, 11 Aug 2021 13:15:27 -0700 Subject: [PATCH 2/9] Update ManagedIdentity.md --- .../troubleshoot/ManagedIdentity.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md b/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md index e69de29bb2d1..afea041b5ea3 100644 --- a/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md +++ b/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md @@ -0,0 +1,99 @@ +## Troubleshooting Mananged Identity Authenticaiton Issues + +### Credential Unavailable + +#### Connection Timed Out / Connection could not be established / Target Environment could not be determined. +The Managed Identity credential runs only on Azure Hosted machines/servers. So ensure that you are running your application on an +Azure Hosted resource. Currently Azure Identity SDK supports [Managed Identity Authentication]((https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)) +in the below listed Azure Services, so ensure you're running your application on one of these resources and have enabled the Managed Identity on +them by following the instructions at their configuration links below. + +Azure Service | Managed Identity Configuration +--- | --- | +[Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) +[Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=java) +[Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/use-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/aks/use-managed-identity) +[Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/msi-authorization) | | +[Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-arc-enabled-servers) +[Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) + +### Client Authentication Issue + +#### 403: Access Forbidden +Ensure that your Managed Identity (User Assigned / System assigned has right permissions assigned to it for the Azure Resource via RBAC. +Below are the instructions to assign specific RBAC roles to an individual Identity in Azure Portal. + +## Step 1: Identify the needed scope + +![Diagram showing the scope levels for Azure RBAC.](https://github.com/MicrosoftDocs/azure-docs/blob/master/includes/role-based-access-control/media/scope-levels.png) + +1. Sign in to the [Azure portal](https://portal.azure.com). + +1. In the Search box at the top, search for the scope you want to grant access to. For example, search for **Management groups**, **Subscriptions**, **Resource groups**, or a specific resource. + +1. Click the specific resource for that scope. + + The following shows an example resource group. + + ![Screenshot of resource group overview page.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/shared/rg-overview.png) + +## Step 2: Open the Add role assignment pane + +**Access control (IAM)** is the page that you typically use to assign roles to grant access to Azure resources. It's also known as identity and access management (IAM) and appears in several locations in the Azure portal. + +1. Click **Access control (IAM)**. + + The following shows an example of the Access control (IAM) page for a resource group. + + ![Screenshot of Access control (IAM) page for a resource group.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/shared/rg-access-control.png) + +1. Click the **Role assignments** tab to view the role assignments at this scope. + +1. Click **Add** > **Add role assignment**. + If you don't have permissions to assign roles, the Add role assignment option will be disabled. + + ![Screenshot of Add > Add role assignment menu.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/shared/add-role-assignment-menu.png) + + The Add role assignment pane opens. + + ![Screenshot of Add role assignment page with Role, Assign access to, and Select options.](https://github.com/MicrosoftDocs/azure-docs/blob/master/includes/role-based-access-control/media/add-role-assignment-page.png) + +## Step 3: Select the appropriate role + +1. In the **Role** list, search or scroll to find the role that you want to assign. + + To help you determine the appropriate role, you can hover over the info icon to display a description for the role. For additional information, you can view the [Azure built-in roles](built-in-roles.md) article. + + ![Screenshot of Select a role list in Add role assignment.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/role-assignments-portal/add-role-assignment-role.png) + +1. Click to select the role. + +## Step 4: Select who needs access + +1. In the **Assign access to** list, select the type of security principal to assign access to. + + | Type | Description | + | --- | --- | + | **User, group, or service principal** | If you want to assign the role to a user, group, or service principal (application), select this type. | + | **User assigned managed identity** | If you want to assign the role to a [user-assigned managed identity](../active-directory/managed-identities-azure-resources/overview.md), select this type. | + | *System assigned managed identity* | If you want to assign the role to a [system-assigned managed identity](../active-directory/managed-identities-azure-resources/overview.md), select the Azure service instance where the managed identity is located. | + + ![Screenshot of selecting a security principal in Add role assignment.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/role-assignments-portal/add-role-assignment-type.png) + +1. If you selected a user-assigned managed identity or a system-assigned managed identity, select the **Subscription** where the managed identity is located. + +1. In the **Select** section, search for the security principal by entering a string or scrolling through the list. + + ![Screenshot of selecting a user in Add role assignment.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/role-assignments-portal/add-role-assignment-user.png) + +1. Once you have found the security principal, click to select it. + +## Step 5: Assign role + +1. To assign the role, click **Save**. + + After a few moments, the security principal is assigned the role at the selected scope. + +1. On the **Role assignments** tab, verify that you see the role assignment in the list. + + ![Screenshot of role assignment list after assigning role.](https://github.com/MicrosoftDocs/azure-docs/blob/master/articles/role-based-access-control/media/role-assignments-portal/rg-role-assignments.png) From de53493f4d6cf18318c0d7c151b4d3c35b96f57f Mon Sep 17 00:00:00 2001 From: Vinay Gera Date: Wed, 11 Aug 2021 13:16:06 -0700 Subject: [PATCH 3/9] Update ManagedIdentity.md --- sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md b/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md index afea041b5ea3..639559ec81b7 100644 --- a/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md +++ b/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md @@ -1,4 +1,4 @@ -## Troubleshooting Mananged Identity Authenticaiton Issues +## Troubleshooting Mananged Identity Authentication Issues ### Credential Unavailable From fe2cac3004f33830b7d159fa1b4344ac1b9e15cd Mon Sep 17 00:00:00 2001 From: Vinay Gera Date: Wed, 11 Aug 2021 13:22:33 -0700 Subject: [PATCH 4/9] Create DefaultAzureCredential.md --- .../azure-identity/DefaultAzureCredential.md | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 sdk/identity/azure-identity/DefaultAzureCredential.md diff --git a/sdk/identity/azure-identity/DefaultAzureCredential.md b/sdk/identity/azure-identity/DefaultAzureCredential.md new file mode 100644 index 000000000000..c82e92053125 --- /dev/null +++ b/sdk/identity/azure-identity/DefaultAzureCredential.md @@ -0,0 +1,167 @@ +## Default Azure Credential + +The DefaultAzureCredential is appropriate for most scenarios where the application ultimately runs in the Azure Cloud. +DefaultAzureCredential combines credentials that are commonly used to authenticate when deployed, with credentials that +are used to authenticate in a development environment. The DefaultAzureCredential will attempt to authenticate via the +following mechanisms in order. + +![DefaultAzureCredential authentication flow](https://github.com/Azure/azure-sdk-for-java/raw/main/sdk/identity/azure-identity/images/defaultazurecredential.png) + + +* Environment - The DefaultAzureCredential will read account information specified via environment variables and use it to authenticate. +* Managed Identity - If the application deploys to an Azure host with Managed Identity enabled, the DefaultAzureCredential will authenticate with that account. +* IntelliJ - If you've authenticated via Azure Toolkit for IntelliJ, the DefaultAzureCredential will authenticate with that account. +* Visual Studio Code - If you've authenticated via the Visual Studio Code Azure Account plugin, the DefaultAzureCredential will authenticate with that account. +* Azure CLI - If you've authenticated an account via the Azure CLI az login command, the DefaultAzureCredential will authenticate with that account. + +## Environment Configuration Based Authentication with Default Azure Credential + +### Configuration + +You can configure DefaultAzureCredential with environment variables. The `DefaultAzureCredential` will utilize the environment variables through `EnvionmentCredential` in the chain of credentials and attempt to authenticate. + +Each type of authentication requires values for specific environment variables as described below: + +**SERVICE PRINCIPAL WITH SECRET** + +Variable name | Value | +--- | --- | +AZURE_CLIENT_ID | ID of an Azure Active Directory application. +AZURE_TENANT_ID | ID of the application's Azure Active Directory 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 Active Directory application. +AZURE_TENANT_ID | ID of the application's Azure Active Directory tenant. +AZURE_CLIENT_CERTIFICATE_PATH | Path to a PEM-encoded certificate file including private key (without password protection). + +**USERNAME AND PASSWORD** +Variable name | Value | +--- | --- | +AZURE_CLIENT_ID | ID of an Azure Active Directory application. +AZURE_USERNAME | A username (usually an email address). +AZURE_PASSWORD | The associated password for the given username. + +### Code Sample +The following example demonstrates authenticating the SecretClient from the `azure-security-keyvault-secrets` client library using the DefaultAzureCredential. The `DefaultAzureCredential` will scan for the configured environment variables and if they are found then authentication will be attempted using `EnvironmentCredential` from the chain of credentials. + +```java +// Azure SDK client builders accept the credential as a parameter. +SecretClient client = new SecretClientBuilder() + .vaultUrl("https://.vault.azure.net") + .credential(new DefaultAzureCredentialBuilder().build()) + .buildClient(); +``` + + + +## Managed Identity Authentication with Default Azure Credential + +### Configuration +The Managed Identity authenticates the managed identity (system or user assigned) of an Azure resource. So, if the application is running inside an Azure resource that supports Managed Identity through `IDENTITY/MSI, IMDS` endpoints, or both, then this credential will get your application authenticated, and offers a great secretless authentication experience. + +Currently Azure Identity SDK supports [Managed Identity Authentication]((https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)) the following Azure Services: +Azure Service | Managed Identity Configuration +--- | --- | +[Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) +[Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=java) +[Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/use-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/aks/use-managed-identity) +[Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/msi-authorization) | | +[Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-arc-enabled-servers) +[Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) + + +### Code Sample +This examples demonstrates authenticating the `SecretClient` from the [azure-security-keyvault-secrets][secrets_client_library] client library using the `DefaultAzureCredential`. Ensure that you have enabled Managed Identity on your Azure resource as per Instructions above. + +```java +/** + * Authenticate with a User Assigned Managed identity. + */ +public void createManagedIdentityCredential() { + DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder() + .managedIdentityClientId("") // only required for user assigned + .build(); + + // Azure SDK client builders accept the credential as a parameter + SecretClient client = new SecretClientBuilder() + .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net") + .credential(defaultAzureCredential) + .buildClient(); +} +``` + +```java +/** + * Authenticate with a System Assigned Managed identity. + */ +public void createManagedIdentityCredential() { + DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder() + .build(); + + // Azure SDK client builders accept the credential as a parameter + SecretClient client = new SecretClientBuilder() + .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net") + .credential(defaultAzureCredential) + .buildClient(); +} +``` + + +## IntelliJ Authentication with Default Azure Credential + +The `DefaultAzureCredential` utilizes `IntelliJCredential` from the credential chain and authenticates in a development environment with the account in Azure Toolkit for IntelliJ. It uses the logged in user information on the IntelliJ IDE and uses it to authenticate the application against Azure Active Directory. + +### Configuration + +Sign in Azure Toolkit for IntelliJ through the steps outlined below: + +* In your IntelliJ window, open File > Settings > Plugins. +* Search for “Azure Toolkit for IntelliJ” in the marketplace. Install and restart IDE. +* Find the new menu item Tools > Azure > Azure Sign In… +* Device Login will help you log in as a user account. Follow the instructions to log in on the login.microsoftonline.com website with the device code. IntelliJ will prompt you to select your subscriptions. Select the subscription with the resources that you want to access. + +On Windows environment, you'll also need the KeePass database path to read IntelliJ credentials. You can find the path in IntelliJ settings under File > Settings > Appearance & Behavior > System Settings > Passwords. Note down the location of the KeePassDatabase path. + + + +### Code Sample +The following example demonstrates authenticating the SecretClient from the [azure-security-keyvault-secrets]() client library using the `DefaultAzureCredential` on a workstation where IntelliJ IDEA is installed, and the user has signed in with an Azure account. +```java +DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder() + // KeePass configuration isrequired only for Windows. No configuration needed for Linux / Mac. + .intelliJkeePassDatabasePath("C:\\Users\\user\\AppData\\Roaming\\JetBrains\\IdeaIC2020.1\\c.kdbx") + .build(); + +// Azure SDK client builders accept the credential as a parameter +SecretClient client = new SecretClientBuilder() + .vaultUrl("https://.vault.azure.net") + .credential(defaultAzureCredential) + .buildClient(); +``` + +## VS Code Authentication with Default Azure Credential + +The Visual Studio Code credential enables authentication in development environments where VS Code is installed with the [VS Code Azure Account extension](https://docs.microsoft.com/en-us/azure/developer/java/sdk/identity-dev-env-auth#intellij-credential). It uses the logged-in user information in the VS Code IDE and uses it to authenticate the application against Azure Active Directory. + +### Configuration + +Sign in Visual Studio Code Azure Account Extension + +The Visual Studio Code authentication is handled by an integration with the [Azure Account extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account). To use this form of authentication, install the Azure Account extension, then use View > Command Palette to execute the Azure: Sign In command. This command opens a browser window and displays a page that allows you to sign in to Azure. After you've completed the login process, you can close the browser as directed. Running your application (either in the debugger or anywhere on the development machine) will use the credential from your sign-in. + + +### Code Sample +The following example demonstrates authenticating the SecretClient from the azure-security-keyvault-secrets client library using the `DefaultAzureCredential` on a workstation where Visual Studio Code is installed, and the user has signed in with an Azure account. + +```java +DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build(); + +// Azure SDK client builders accept the credential as a parameter. +SecretClient client = new SecretClientBuilder() + .vaultUrl("https://.vault.azure.net") + .credential(defaultAzureCredential) + .buildClient(); +``` From 7ff3e1a894506ccf6af91b7df5ca3fd146653d6d Mon Sep 17 00:00:00 2001 From: g2vinay Date: Mon, 23 Aug 2021 10:43:17 -0700 Subject: [PATCH 5/9] update --- sdk/identity/azure-identity/Troubleshoot.md | 129 ++++++++++++++++++ .../troubleshoot/ManagedIdentity.md | 0 2 files changed, 129 insertions(+) create mode 100644 sdk/identity/azure-identity/Troubleshoot.md delete mode 100644 sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md diff --git a/sdk/identity/azure-identity/Troubleshoot.md b/sdk/identity/azure-identity/Troubleshoot.md new file mode 100644 index 000000000000..12a5bd30d745 --- /dev/null +++ b/sdk/identity/azure-identity/Troubleshoot.md @@ -0,0 +1,129 @@ +## Table of contents + - [Troubleshooting Service Principal Authentication Issues](#troubleshooting-service-principal-authentication-issues) + - [Troubleshooting Mananged Identity Authenticaiton Issues](#troubleshooting-mananged-identity-authenticaiton-issues) + - [Troubleshooting Visual Studio Code Authenticaiton Issues](#troubleshooting-visual-studio-code-authenticaiton-issues) + - [Troubleshooting Azure CLI Authenticaiton Issues](#troubleshooting-azure-cli-authenticaiton-issues) + - [Troubleshooting Azure Powershell Authenticaiton Issues](#troubleshooting-azure-powershell-authenticaiton-issues) + +## Troubleshooting Service Principal Authentication Issues. + +### Illegal/Invalid Argument Issues + +#### Client Id + +The Client Id is the application Id of the registered application / service principal in Azure Active Directory. +It is a required parameter for `ClientSecretCredential` and `ClientCertificateCredential`. If you have already created your service principal +then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). + +#### Tenant Id +The tenant id is te Global Unique Identifier (GUID) that identifies your organization. It is a required parameter for +`ClientSecretCredential` and `ClientCertificateCredential`. If you have already created your service principal +then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). + +#### Client Secret +The client secret is the secret string that the application uses to prove its identity when requesting a token, this can also can be referred to as an application password. +If you have already created a servie principal you can follow the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret) to get the client secret for your application. + +If you're looking to create a new service principal and would like to use that, then follow tne instructions [here](https://docs.microsoft.com/en-us/azure/developer/java/sdk/identity-service-principal-auth#create-a-service-principal-with-the-azure-cli) to create a new service principal. + + +## Troubleshooting Mananged Identity Authenticaiton Issues + +### Credential Unavailable + +#### Connection Timed Out / Connection could not be established / Target Environment could not be determined. +The Managed Identity credential runs only on Azure Hosted machines/servers. So ensure that you are running your application on an +Azure Hosted resource. Currently Azure Identity SDK supports [Managed Identity Authentication]((https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)) +in the below listed Azure Services, so ensure you're running your application on one of these resources and have enabled the Managed Identity on +them by following the instructions at their configuration links below. + +Azure Service | Managed Identity Configuration +--- | --- | +[Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) +[Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=java) +[Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/use-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/aks/use-managed-identity) +[Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/msi-authorization) | | +[Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-arc-enabled-servers) +[Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) + + +## Troubleshooting Visual Studio Code Authenticaiton Issues + +### Credential Unavailable + +#### Failed To Read VS Code Credentials / Authenticate via Azure Tools plugin in VS Code. +THe `VS Code Credential` failed to read the credential details from the cache. + +The Visual Studio Code authentication is handled by an integration with the Azure Account extension. +To use this form of authentication, ensure that you have installed the Azure Account extension, +then use View > Command Palette to execute the Azure: Sign In command. This command opens a browser window and displays a page that allows you +to sign in to Azure. After you've completed the login process, you can close the browser as directed. Running your application +(either in the debugger or anywhere on the development machine) will use the credential from your sign-in. + +If you already had the Azure Account extension installed and had logged in to your account. Then try logging out and logging in again, as +that will re-populate the cache on the disk and potentially mitigate the error you're getting. + +#### Msal Interaction Required Error +THe `VS Code Credential` was able to read the cached credentials from the cache but the cached token is likely expired. +Log into the Azure Account extension by via View > Command Palette to execute the Azure: Sign In command in the VS Code IDE. + +#### ADFS Tenant Not Supported +The ADFS Tenants are not supported via the Azure Account extension in VS Code currently. +The supported clouds are: + +Azure Cloud | Cloud Authority Host +--- | --- | +AZURE PUBLIC CLOUD | https://login.microsoftonline.com/ +AZURE GERMANY | https://login.microsoftonline.de/ +AZURE CHINA | https://login.chinacloudapi.cn/ +AZURE GOVERNMENT | https://login.microsoftonline.us/ + + +## Troubleshooting Azure CLI Authenticaiton Issues + +### Credential Unavailable + +#### Azure CLI Not Installed. +THe `Azure CLI Credential` failed to execute as Azure CLI command line tool is not installed. +To use Azure CLI credential, the Azure CLI needs to be installed, please follow the instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) +to install it for your platform and then try running the credential again. + +#### Azure account not logged in. +The `Azure CLI Credential` utilizes the current logged in Azure user in Azure CLI to fetch an access token. +You need to login to your account in Azure CLI via `az login` command. You can further read instructions to [Sign in with Azure CLI](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). +Once logged in try running the credential again. + +### Illegal State +#### Safe Working Directory Not Located. +The `Azure CLI Credential` was not able to locoate a value for System Environment property `SystemRoot` to execute in. +Please ensure the `SystemRoot` environment variable is configured to a safe working directory and then try running the credential again. + + +## Troubleshooting Azure Powershell Authenticaiton Issues + +### Credential Unavailable + +#### Powershell not installed. + +The `Azure Powershell Credential` utilizes the locally installed `Powershell` command line tool to fetch an access token. Please ensure it is installed on your platform by following the instructions [here](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.1) and then run the credential again. + +#### Azure Az Moudle Not Installed. +The `Azure Powershell Credential` failed to execute as Azure az module is not installed. +To use Azure Powershell credential, the Azure az module needs to be installed, please follow the instructions [here](https://docs.microsoft.com/en-us/powershell/azure/install-az-ps?view=azps-6.3.0) +to install it for your platform and then try running the credential again. + +#### Azure account not logged in. +The `Azure Powershell Credential` utilizes the current logged in Azure user in Azure Powershell to fetch an access token. +You need to login to your account in Azure Powershell via `Connect-AzAccount` command. You can further read instructions to [Sign in with Azure Powershell](https://docs.microsoft.com/en-us/powershell/azure/authenticate-azureps?view=azps-6.3.0). +Once logged in try running the credential again. + + +#### Deserialization error. +The `Azure Powershell Credential` was able to retrieve a response from the Azure Powershell when attempting to get an access token but failed +to parse that response. +In your local powershell window, run the following command to ensure that Azure Powerhsell is returning an access token in correct format. + +```pwsh +Get-AzAccessToken -ResourceUrl "" +``` +In the event above command is not working properly, follow the instructions to resolve the Azure Powershell issue being faced and then try running the credential again. diff --git a/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md b/sdk/identity/azure-identity/troubleshoot/ManagedIdentity.md deleted file mode 100644 index e69de29bb2d1..000000000000 From 44b38a0676d2fd240193ae7d59ea6b27e312b8eb Mon Sep 17 00:00:00 2001 From: g2vinay Date: Mon, 30 Aug 2021 10:00:12 -0700 Subject: [PATCH 6/9] update --- sdk/identity/azure-identity/Troubleshoot.md | 96 +++++++++++- .../identity/ChainedTokenCredential.java | 6 +- .../implementation/IdentityClient.java | 148 ++++++++++++------ .../implementation/IntelliJCacheAccessor.java | 11 ++ 4 files changed, 212 insertions(+), 49 deletions(-) diff --git a/sdk/identity/azure-identity/Troubleshoot.md b/sdk/identity/azure-identity/Troubleshoot.md index 12a5bd30d745..a0e6fcbc3fdb 100644 --- a/sdk/identity/azure-identity/Troubleshoot.md +++ b/sdk/identity/azure-identity/Troubleshoot.md @@ -1,10 +1,88 @@ +## Troubleshooting Azure Identity Authentication Issues +The Azure Identity SDK offers various `TokenCredential` implementations. These implementations tend to throw `CredentialUnavailable` and `ClientAuthentication` exceptions. +The `CredentialUnavailableException` indicates that the credential cannot execute in the current environment setup due to lack of required configuration. +The `ClientAuthenticationException` indicates that the credential was able to run/execute but ran into an authentication issue from the server's end. This can happen due to invalid configuration/details passed in to the credential at construction time. +This troubleshooting guide covers mitigation steps to resolve these exceptions thrown by various `TokenCredential` implementations in the Azure Identity Java client library. + ## Table of contents + - [Troubleshooting Default Azure Credential Authentication Issues](#troubleshooting-default-azure-credential-authentication-issues) + - [Troubleshooting Environment Credential Authentication Issues](#troubleshooting-environment-credential-authentication-issues) - [Troubleshooting Service Principal Authentication Issues](#troubleshooting-service-principal-authentication-issues) + - [Troubleshooting Username Password Authentication Issues](#troubleshooting-username-password-authentication-issues) - [Troubleshooting Mananged Identity Authenticaiton Issues](#troubleshooting-mananged-identity-authenticaiton-issues) - [Troubleshooting Visual Studio Code Authenticaiton Issues](#troubleshooting-visual-studio-code-authenticaiton-issues) - [Troubleshooting Azure CLI Authenticaiton Issues](#troubleshooting-azure-cli-authenticaiton-issues) - [Troubleshooting Azure Powershell Authenticaiton Issues](#troubleshooting-azure-powershell-authenticaiton-issues) + + +## Troubleshooting Default Azure Credential Authentication Issues. + +### Credential Unavailable Exception +The `DefaultAzureCredential` attempts to retrieve an access token by sequentially invoking a chain of credentials. The `CredentialUnavailableException` in this scenario signifies that all the credentials in the chain failed to retrieve the token in the current environment setup/configuration. You need to follow the configurtion instructions for the respective credential you're looking to use via `DefaultAzureCredential` chain, so that the credential can work in your environment. + +Please follow the configuration instructions in the `Credential Unvavailable` section of hte troublehsooting guidelines below for the repsective credential/authentication type you're looking to use via `DefaultAzureCredential`: + +| Credential Type | Trobuleshoot Guide | +| --- | --- | +| Environment Credential | [Environment Credential Troubleshooting Guide](#troubleshooting-environment-credential-authentication-issues) | +| Managed Identity Credential | [Managed Identity Troubleshooting Guide](#troubleshooting-managed-identity-authentication-issues) | +| Visual Studio Code Credential | [Visual Studio Code Troubleshooting Guide](#troubleshooting-visual-studio-code-authenticaiton-issues) | +| Azure CLI Credential | [Azure CLI Troubleshooting Guide](#troubleshooting-azure-cli-authenticaiton-issues) | +| Azure Powershell Credential | [Azure Powershell Troubleshooting Guide](#troubleshooting-azure-powershell-authentication-issues) | + + + + +## Troubleshooting Environment Credential Authentication Issues. + +### Credential Unavailable Exception + +#### Environment variables not configured +The `EnvironmentCredential` supports Service Principal authentication and Username + Password Authentication. To utilize the desired way of authentication via `EnvironmentCredential`, you need to ensure the environment varialbes below are configured properly and the application is able to read them. + + +##### Service principal with secret +| Variable Name | Value | +| --- | --- | +AZURE_CLIENT_ID | ID of an Azure Active Directory application. | +AZURE_TENANT_ID |ID of the application's Azure Active Directory 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 Active Directory application. | +AZURE_TENANT_ID | ID of the application's Azure Active Directory tenant. | +AZURE_CLIENT_CERTIFICATE_PATH | Path to a PEM-encoded certificate file including private key (without password protection). | + +##### Username and password +| Variable name | Value | +| --- | --- | +AZURE_CLIENT_ID | ID of an Azure Active Directory application. | +AZURE_USERNAME | A username (usually an email address). | +AZURE_PASSWORD | The associated password for the given username. | + +### Client Authentication Exception +The `EnvironmentCredential` supports Service Principal authentication and Username + Password Authentication. +Please follow the troublehsooting guidelines below for the repsective authentication which you tried and failed. + +| Authentication Type | Trobuleshoot Guide | +| --- | --- | +| Service Principal | [Service Principal Auth Troubleshooting Guide](#troubleshooting-username-password-authentication-issues) | +| Username Password | [Username Password Auth Troubleshooting Guide](#troubleshooting-username-password-authentication-issues) | + + + + +## Troubleshooting Username Password Authentication Issues. + +### Two Factor Authentication Required Error. +The `UsernamePassword` credential works only for users whose two factor authentication has been disabled in Azure Active Directrory. You can change the Multi Factor Authentication in Azure Portal by folliwng the steps [here](https://docs.microsoft.com/en-us/azure/active-directory/authentication/howto-mfa-userstates#change-the-status-for-a-user). + + + + ## Troubleshooting Service Principal Authentication Issues. ### Illegal/Invalid Argument Issues @@ -20,13 +98,23 @@ The tenant id is te Global Unique Identifier (GUID) that identifies your organiz `ClientSecretCredential` and `ClientCertificateCredential`. If you have already created your service principal then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). -#### Client Secret +### Client Secret Credential Issues + +#### Client Secret Argument The client secret is the secret string that the application uses to prove its identity when requesting a token, this can also can be referred to as an application password. If you have already created a servie principal you can follow the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret) to get the client secret for your application. +### Client Certificate Credential Issues + +#### Client Certificate Argument +The `Client Certificate Credential` accepts `pfx` and `pem` certificates. The certificate needs to be associated with your registered application/service principal. To create and associate a certificate with your registered app. please follow the instrucitons [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-1-upload-a-certificate). + +### Create a new service principal If you're looking to create a new service principal and would like to use that, then follow tne instructions [here](https://docs.microsoft.com/en-us/azure/developer/java/sdk/identity-service-principal-auth#create-a-service-principal-with-the-azure-cli) to create a new service principal. + + ## Troubleshooting Mananged Identity Authenticaiton Issues ### Credential Unavailable @@ -47,6 +135,8 @@ Azure Service | Managed Identity Configuration [Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) + + ## Troubleshooting Visual Studio Code Authenticaiton Issues ### Credential Unavailable @@ -79,6 +169,8 @@ AZURE CHINA | https://login.chinacloudapi.cn/ AZURE GOVERNMENT | https://login.microsoftonline.us/ + + ## Troubleshooting Azure CLI Authenticaiton Issues ### Credential Unavailable @@ -99,6 +191,8 @@ The `Azure CLI Credential` was not able to locoate a value for System Environmen Please ensure the `SystemRoot` environment variable is configured to a safe working directory and then try running the credential again. + + ## Troubleshooting Azure Powershell Authenticaiton Issues ### Credential Unavailable diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/ChainedTokenCredential.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/ChainedTokenCredential.java index 8cef48f2a993..d1b1826467bf 100644 --- a/sdk/identity/azure-identity/src/main/java/com/azure/identity/ChainedTokenCredential.java +++ b/sdk/identity/azure-identity/src/main/java/com/azure/identity/ChainedTokenCredential.java @@ -25,6 +25,8 @@ */ @Immutable public class ChainedTokenCredential implements TokenCredential { + private static final String TROUBLESHOOT_MESSAGE = "To mitigate this issue, please refer to the troubleshooting " + + "guidelines here at https://aka.ms/azure-identity-java-default-azure-credential-troubleshoot"; private final ClientLogger logger = new ClientLogger(getClass()); private final List credentials; private final String unavailableError = this.getClass().getSimpleName() + " authentication failed. ---> "; @@ -73,8 +75,8 @@ public Mono getToken(TokenRequestContext request) { CredentialUnavailableException last = exceptions.get(exceptions.size() - 1); for (int z = exceptions.size() - 2; z >= 0; z--) { CredentialUnavailableException current = exceptions.get(z); - last = new CredentialUnavailableException(current.getMessage() + "\r\n" + last.getMessage(), - last.getCause()); + last = new CredentialUnavailableException(current.getMessage() + "\r\n" + last.getMessage() + + (z == 0 ? TROUBLESHOOT_MESSAGE : "")); } return Mono.error(last); })); diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java index 12f295b8ea9f..338310001a8b 100644 --- a/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java +++ b/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java @@ -206,7 +206,9 @@ private Mono getConfidentialClientApplication() { } } else { return Mono.error(logger.logExceptionAsError( - new IllegalArgumentException("Must provide client secret or client certificate path"))); + new IllegalArgumentException("Must provide client secret or client certificate path." + + " To mitigate this issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java-azure-service-principal-authentication-troubleshoot"))); } ConfidentialClientApplication.Builder applicationBuilder = @@ -309,6 +311,7 @@ private Mono getPublicClientApplication(boolean sharedT public Mono authenticateWithIntelliJ(TokenRequestContext request) { try { IntelliJCacheAccessor cacheAccessor = new IntelliJCacheAccessor(options.getIntelliJKeePassDatabasePath()); + IntelliJAuthMethodDetails authDetails = cacheAccessor.getAuthDetailsIfAvailable(); String authType = authDetails.getAuthMethod(); if (authType.equalsIgnoreCase("SP")) { @@ -340,7 +343,10 @@ public Mono authenticateWithIntelliJ(TokenRequestContext request) { return Mono.error(e); } } else if (authType.equalsIgnoreCase("DC")) { - + logger.verbose("IntelliJ Authentication => Device Code Authentication scheme detected in Azure Tools" + + " for IntelliJ Plugin."); + logger.verbose("Checking if the provided tenant is an ADFS tenant or not. The ADFS tenants are not" + + " supported via IntelliJ Authentication currently." ); if (isADFSTenant()) { return Mono.error(new CredentialUnavailableException("IntelliJCredential " + "authentication unavailable. ADFS tenant/authorities are not supported.")); @@ -361,6 +367,9 @@ public Mono authenticateWithIntelliJ(TokenRequestContext request) { .map(MsalToken::new)); } else { + logger.verbose("IntelliJ Authentication = > Only Service Principal and Device Code Authentication" + + " schemes are currently supported via IntelliJ Credential currently. Please ensure you used one" + + " of those schemes from Azure Tools for IntelliJ plugin."); throw logger.logExceptionAsError(new CredentialUnavailableException( "IntelliJ Authentication not available." + " Please login with Azure Tools for IntelliJ plugin in the IDE.")); @@ -406,14 +415,20 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { } ProcessBuilder builder = new ProcessBuilder(starter, switcher, command.toString()); + logger.verbose("Azure CLI Authentication => Retrieving safe working directory to execute Azure CLI" + + " commands from."); String workingDirectory = getSafeWorkingDirectory(); if (workingDirectory != null) { builder.directory(new File(workingDirectory)); } else { throw logger.logExceptionAsError(new IllegalStateException("A Safe Working directory could not be" - + " found to execute CLI command from.")); + + " found to execute CLI command from. To mitigate this issue, please refer to the troubleshooting " + + " guidelines here at https://aka.ms/azure-identity-java--azure-cli-credential-troubleshoot")); } builder.redirectErrorStream(true); + + logger.verbose("Azure CLI Authentication => Invoking the process to execute Azure CLI commands and " + + "retrieve an Access Token."); Process process = builder.start(); reader = new BufferedReader(new InputStreamReader(process.getInputStream(), "UTF-8")); @@ -426,8 +441,10 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { } if (line.startsWith(WINDOWS_PROCESS_ERROR_MESSAGE) || line.matches(LINUX_MAC_PROCESS_ERROR_MESSAGE)) { throw logger.logExceptionAsError( - new CredentialUnavailableException( - "AzureCliCredential authentication unavailable. Azure CLI not installed")); + new CredentialUnavailableException( + "AzureCliCredential authentication unavailable. Azure CLI not installed." + + "To mitigate this issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java--azure-cli-credential-troubleshoot")); } output.append(line); } @@ -440,9 +457,11 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { String redactedOutput = redactInfo("\"accessToken\": \"(.*?)(\"|$)", processOutput); if (redactedOutput.contains("az login") || redactedOutput.contains("az account set")) { throw logger.logExceptionAsError( - new CredentialUnavailableException( - "AzureCliCredential authentication unavailable." - + " Please run 'az login' to set up account")); + new CredentialUnavailableException( + "AzureCliCredential authentication unavailable." + + " Please run 'az login' to set up account. To further mitigate this" + + " issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java--azure-cli-credential-troubleshoot")); } throw logger.logExceptionAsError(new ClientAuthenticationException(redactedOutput, null)); } else { @@ -450,6 +469,9 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { new ClientAuthenticationException("Failed to invoke Azure CLI ", null)); } } + + logger.verbose("Azure CLI Authentication => A token response was received from Azure CLI, deserializng the" + + " response into an Access Token."); Map objectMap = SERIALIZER_ADAPTER.deserialize(processOutput, Map.class, SerializerEncoding.JSON); String accessToken = objectMap.get("accessToken"); @@ -503,7 +525,9 @@ public Mono authenticateWithAzurePowerShell(TokenRequestContext req .onErrorResume(t -> { if (!t.getClass().getSimpleName().equals("CredentialUnavailableException")) { return Mono.error(new ClientAuthenticationException( - "Azure Powershell authentication failed. Error Details: " + t.getMessage(), + "Azure Powershell authentication failed. Error Details: " + t.getMessage() + + ". To mitigate this issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java--azure-powershell-credential-troubleshoot", null, t)); } exceptions.add((CredentialUnavailableException) t); @@ -518,7 +542,9 @@ public Mono authenticateWithAzurePowerShell(TokenRequestContext req last = new CredentialUnavailableException("Azure Powershell authentication failed using default" + "powershell(pwsh) with following error: " + current.getMessage() + "\r\n" + "Azure Powershell authentication failed using powershell-core(powershell)" - + " with following error: " + last.getMessage(), + + " with following error: " + last.getMessage() + + (z == 0 ? ". To mitigate this issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java--azure-powershell-credential-troubleshoot" : ""), last.getCause()); } return Mono.error(last); @@ -528,38 +554,53 @@ public Mono authenticateWithAzurePowerShell(TokenRequestContext req private Mono getAccessTokenFromPowerShell(TokenRequestContext request, PowershellManager powershellManager) { return powershellManager.initSession() - .flatMap(manager -> manager.runCommand("Import-Module Az.Accounts -MinimumVersion 2.2.0 -PassThru") - .flatMap(output -> { - if (output.contains("The specified module 'Az.Accounts' with version '2.2.0' was not loaded " - + "because no valid module file")) { - return Mono.error(new CredentialUnavailableException( - "Az.Account module with version >= 2.2.0 is not installed. It needs to be installed to use" - + "Azure PowerShell Credential.")); - } - StringBuilder accessTokenCommand = new StringBuilder("Get-AzAccessToken -ResourceUrl "); - accessTokenCommand.append(ScopeUtil.scopesToResource(request.getScopes())); - accessTokenCommand.append(" | ConvertTo-Json"); - return manager.runCommand(accessTokenCommand.toString()) - .flatMap(out -> { - if (out.contains("Run Connect-AzAccount to login")) { - return Mono.error(new CredentialUnavailableException( - "Run Connect-AzAccount to login to Azure account in PowerShell.")); - } - try { - Map objectMap = SERIALIZER_ADAPTER.deserialize(out, Map.class, - SerializerEncoding.JSON); - String accessToken = objectMap.get("Token"); - String time = objectMap.get("ExpiresOn"); - OffsetDateTime expiresOn = OffsetDateTime.parse(time) - .withOffsetSameInstant(ZoneOffset.UTC); - return Mono.just(new AccessToken(accessToken, expiresOn)); - } catch (IOException e) { - return Mono.error(logger - .logExceptionAsError(new CredentialUnavailableException( - "Encountered error when deserializing response from Azure Power Shell.", e))); - } - }); - })).doFinally(ignored -> powershellManager.close()); + .flatMap(manager -> { + String azAccountsCommand = "Import-Module Az.Accounts -MinimumVersion 2.2.0 -PassThru"; + logger.verbose("Azure Powershell Authentication = > Checking if Az.Accounts module is installed or " + + "not in Azure Powershell by executing this command `%s`. This module is required to execute Azure" + + " Powershell Credential.", azAccountsCommand); + String + return manager.runCommand(azAccountsCommand) + .flatMap(output -> { + if (output.contains("The specified module 'Az.Accounts' with version '2.2.0' was not loaded " + + "because no valid module file")) { + return Mono.error(new CredentialUnavailableException( + "Az.Account module with version >= 2.2.0 is not installed. It needs to be installed to" + + " use Azure PowerShell Credential.")); + } + logger.verbose("Az.accounts module was found installed."); + StringBuilder accessTokenCommand = new StringBuilder("Get-AzAccessToken -ResourceUrl "); + accessTokenCommand.append(ScopeUtil.scopesToResource(request.getScopes())); + accessTokenCommand.append(" | ConvertTo-Json"); + String command = accessTokenCommand.toString(); + logger.verbose("Azure Powershell Authentication => Executing the command `%s` in Azure " + + "Powershell to retrieve the Access Token.", + accessTokenCommand); + return manager.runCommand(accessTokenCommand.toString()) + .flatMap(out -> { + if (out.contains("Run Connect-AzAccount to login")) { + return Mono.error(new CredentialUnavailableException( + "Run Connect-AzAccount to login to Azure account in PowerShell.")); + } + + try { + logger.verbose("Azure Powershell Authentication => Attempting to deserialize the " + + "received response from Azure Powershell."); + Map objectMap = SERIALIZER_ADAPTER.deserialize(out, Map.class, + SerializerEncoding.JSON); + String accessToken = objectMap.get("Token"); + String time = objectMap.get("ExpiresOn"); + OffsetDateTime expiresOn = OffsetDateTime.parse(time) + .withOffsetSameInstant(ZoneOffset.UTC); + return Mono.just(new AccessToken(accessToken, expiresOn)); + } catch (IOException e) { + return Mono.error(logger + .logExceptionAsError(new CredentialUnavailableException( + "Encountered error when deserializing response from Azure Power Shell.", e))); + } + }); + }); + }).doFinally(ignored -> powershellManager.close()); } /** @@ -610,7 +651,9 @@ public Mono authenticateWithUsernamePassword(TokenRequestContext requ return pc.acquireToken(userNamePasswordParametersBuilder.build()); } )).onErrorMap(t -> new ClientAuthenticationException("Failed to acquire token with username and " - + "password", null, t)).map(MsalToken::new); + + "password. To mitigate this issue, please refer to the troubleshooting guidelines " + + "here at https://aka.ms/azure-identity-java--azure-username-password-credential-troubleshoot", + null, t)).map(MsalToken::new); } /** @@ -719,16 +762,24 @@ public Mono authenticateWithDeviceCode(TokenRequestContext request, */ public Mono authenticateWithVsCodeCredential(TokenRequestContext request, String cloud) { + logger.verbose("VS Code Authentication => Checking if the provided is an ADFS tenant or not. The ADFS tenants" + + " are not supported via Visual Studio Authentication currently." ); if (isADFSTenant()) { return Mono.error(new CredentialUnavailableException("VsCodeCredential " - + "authentication unavailable. ADFS tenant/authorities are not supported.")); + + "authentication unavailable. ADFS tenant/authorities are not supported. " + + "To mitigate this issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java-azure-vscode-credential-troubleshoot")); } VisualStudioCacheAccessor accessor = new VisualStudioCacheAccessor(); + logger.verbose("VS Code Authentication => Starting to retrieve the cached refresh token from VS Code Azure" + + " Extension's cache"); String credential = accessor.getCredentials("VS Code Azure", cloud); + logger.verbose("VS Code Authentication => Retrieved the cached refresh token from VS Code Azure Extension's" + + " cache."); RefreshTokenParameters.RefreshTokenParametersBuilder parametersBuilder = RefreshTokenParameters - .builder(new HashSet<>(request.getScopes()), credential); + .builder(new HashSet<>(request.getScopes()), credential); if (request.getClaims() != null) { ClaimsRequest customClaimRequest = CustomClaimRequest.formatAsClaimsRequest(request.getClaims()); @@ -738,9 +789,14 @@ public Mono authenticateWithVsCodeCredential(TokenRequestContext requ return publicClientApplicationAccessor.getValue() .flatMap(pc -> Mono.fromFuture(pc.acquireToken(parametersBuilder.build())) .onErrorResume(t -> { + logger.verbose("VS Code Authentication => Encountered an error as the refresh token found in the" + + " VS code cache was expired. Please login again interactively in VS Code Azure Extension" + + " plugin to mitigate this issue."); if (t instanceof MsalInteractionRequiredException) { return Mono.error(new CredentialUnavailableException("Failed to acquire token with" - + " VS code credential", t)); + + " VS code credential." + + " To mitigate this issue, please refer to the troubleshooting guidelines here at " + + "https://aka.ms/azure-identity-java-azure-vscode-credential-troubleshoot", t)); } return Mono.error(new ClientAuthenticationException("Failed to acquire token with" + " VS code credential", null, t)); diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IntelliJCacheAccessor.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IntelliJCacheAccessor.java index e326805a4801..281cfaefa912 100644 --- a/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IntelliJCacheAccessor.java +++ b/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IntelliJCacheAccessor.java @@ -247,6 +247,9 @@ public IntelliJAuthMethodDetails getAuthDetailsIfAvailable() throws IOException break; } } + logger.verbose("IntelliJ Authentication => Reading in Azure Tools for IntelliJ Plugin's metadata file" + + " located at `%s`. This file contains authentication scheme details used when logging via" + + " Azure Plugin in IntelliJ IDE.", authFile.getAbsolutePath()); if (authFile == null || !authFile.exists()) { throw logger.logExceptionAsError( new CredentialUnavailableException(INTELLIJ_CREDENTIAL_NOT_AVAILABLE_ERROR)); @@ -256,16 +259,24 @@ public IntelliJAuthMethodDetails getAuthDetailsIfAvailable() throws IOException String authType = authMethodDetails.getAuthMethod(); if (CoreUtils.isNullOrEmpty(authType)) { + logger.verbose("IntelliJ Authentication => Authentication Type could not be found in Azure Tools for" + + " IntelliJ Plugin's metadata file located at `%s`.", authFile.getAbsolutePath()); throw logger.logExceptionAsError( new CredentialUnavailableException(INTELLIJ_CREDENTIAL_NOT_AVAILABLE_ERROR)); } if (authType.equalsIgnoreCase("SP")) { if (CoreUtils.isNullOrEmpty(authMethodDetails.getCredFilePath())) { + logger.verbose("IntelliJ Authentication => Service Principal Authentication Detected but file path to " + + "service principal could not be found in Azure Tools for IntelliJ Plugin's metadata file located" + + " at `%s`.", authFile.getAbsolutePath()); throw logger.logExceptionAsError( new CredentialUnavailableException(INTELLIJ_CREDENTIAL_NOT_AVAILABLE_ERROR)); } } else if (authType.equalsIgnoreCase("DC")) { if (CoreUtils.isNullOrEmpty(authMethodDetails.getAccountEmail())) { + logger.verbose("IntelliJ Authentication => Device Code Authentication Detected but user email info used" + + " for logging in could not be found in Azure Tools for IntelliJ Plugin's metadata file located" + + " at `%s`.", authFile.getAbsolutePath()); throw logger.logExceptionAsError( new CredentialUnavailableException(INTELLIJ_CREDENTIAL_NOT_AVAILABLE_ERROR)); } From ebbf4d12bce1e01b92297c752edaabb30bf7b3ae Mon Sep 17 00:00:00 2001 From: g2vinay Date: Tue, 14 Sep 2021 10:17:33 -0700 Subject: [PATCH 7/9] update --- .../azure-identity/DefaultAzureCredential.md | 167 ------------------ 1 file changed, 167 deletions(-) delete mode 100644 sdk/identity/azure-identity/DefaultAzureCredential.md diff --git a/sdk/identity/azure-identity/DefaultAzureCredential.md b/sdk/identity/azure-identity/DefaultAzureCredential.md deleted file mode 100644 index c82e92053125..000000000000 --- a/sdk/identity/azure-identity/DefaultAzureCredential.md +++ /dev/null @@ -1,167 +0,0 @@ -## Default Azure Credential - -The DefaultAzureCredential is appropriate for most scenarios where the application ultimately runs in the Azure Cloud. -DefaultAzureCredential combines credentials that are commonly used to authenticate when deployed, with credentials that -are used to authenticate in a development environment. The DefaultAzureCredential will attempt to authenticate via the -following mechanisms in order. - -![DefaultAzureCredential authentication flow](https://github.com/Azure/azure-sdk-for-java/raw/main/sdk/identity/azure-identity/images/defaultazurecredential.png) - - -* Environment - The DefaultAzureCredential will read account information specified via environment variables and use it to authenticate. -* Managed Identity - If the application deploys to an Azure host with Managed Identity enabled, the DefaultAzureCredential will authenticate with that account. -* IntelliJ - If you've authenticated via Azure Toolkit for IntelliJ, the DefaultAzureCredential will authenticate with that account. -* Visual Studio Code - If you've authenticated via the Visual Studio Code Azure Account plugin, the DefaultAzureCredential will authenticate with that account. -* Azure CLI - If you've authenticated an account via the Azure CLI az login command, the DefaultAzureCredential will authenticate with that account. - -## Environment Configuration Based Authentication with Default Azure Credential - -### Configuration - -You can configure DefaultAzureCredential with environment variables. The `DefaultAzureCredential` will utilize the environment variables through `EnvionmentCredential` in the chain of credentials and attempt to authenticate. - -Each type of authentication requires values for specific environment variables as described below: - -**SERVICE PRINCIPAL WITH SECRET** - -Variable name | Value | ---- | --- | -AZURE_CLIENT_ID | ID of an Azure Active Directory application. -AZURE_TENANT_ID | ID of the application's Azure Active Directory 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 Active Directory application. -AZURE_TENANT_ID | ID of the application's Azure Active Directory tenant. -AZURE_CLIENT_CERTIFICATE_PATH | Path to a PEM-encoded certificate file including private key (without password protection). - -**USERNAME AND PASSWORD** -Variable name | Value | ---- | --- | -AZURE_CLIENT_ID | ID of an Azure Active Directory application. -AZURE_USERNAME | A username (usually an email address). -AZURE_PASSWORD | The associated password for the given username. - -### Code Sample -The following example demonstrates authenticating the SecretClient from the `azure-security-keyvault-secrets` client library using the DefaultAzureCredential. The `DefaultAzureCredential` will scan for the configured environment variables and if they are found then authentication will be attempted using `EnvironmentCredential` from the chain of credentials. - -```java -// Azure SDK client builders accept the credential as a parameter. -SecretClient client = new SecretClientBuilder() - .vaultUrl("https://.vault.azure.net") - .credential(new DefaultAzureCredentialBuilder().build()) - .buildClient(); -``` - - - -## Managed Identity Authentication with Default Azure Credential - -### Configuration -The Managed Identity authenticates the managed identity (system or user assigned) of an Azure resource. So, if the application is running inside an Azure resource that supports Managed Identity through `IDENTITY/MSI, IMDS` endpoints, or both, then this credential will get your application authenticated, and offers a great secretless authentication experience. - -Currently Azure Identity SDK supports [Managed Identity Authentication]((https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)) the following Azure Services: -Azure Service | Managed Identity Configuration ---- | --- | -[Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) -[Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=java) -[Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/use-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/aks/use-managed-identity) -[Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/msi-authorization) | | -[Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-arc-enabled-servers) -[Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) - - -### Code Sample -This examples demonstrates authenticating the `SecretClient` from the [azure-security-keyvault-secrets][secrets_client_library] client library using the `DefaultAzureCredential`. Ensure that you have enabled Managed Identity on your Azure resource as per Instructions above. - -```java -/** - * Authenticate with a User Assigned Managed identity. - */ -public void createManagedIdentityCredential() { - DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder() - .managedIdentityClientId("") // only required for user assigned - .build(); - - // Azure SDK client builders accept the credential as a parameter - SecretClient client = new SecretClientBuilder() - .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net") - .credential(defaultAzureCredential) - .buildClient(); -} -``` - -```java -/** - * Authenticate with a System Assigned Managed identity. - */ -public void createManagedIdentityCredential() { - DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder() - .build(); - - // Azure SDK client builders accept the credential as a parameter - SecretClient client = new SecretClientBuilder() - .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net") - .credential(defaultAzureCredential) - .buildClient(); -} -``` - - -## IntelliJ Authentication with Default Azure Credential - -The `DefaultAzureCredential` utilizes `IntelliJCredential` from the credential chain and authenticates in a development environment with the account in Azure Toolkit for IntelliJ. It uses the logged in user information on the IntelliJ IDE and uses it to authenticate the application against Azure Active Directory. - -### Configuration - -Sign in Azure Toolkit for IntelliJ through the steps outlined below: - -* In your IntelliJ window, open File > Settings > Plugins. -* Search for “Azure Toolkit for IntelliJ” in the marketplace. Install and restart IDE. -* Find the new menu item Tools > Azure > Azure Sign In… -* Device Login will help you log in as a user account. Follow the instructions to log in on the login.microsoftonline.com website with the device code. IntelliJ will prompt you to select your subscriptions. Select the subscription with the resources that you want to access. - -On Windows environment, you'll also need the KeePass database path to read IntelliJ credentials. You can find the path in IntelliJ settings under File > Settings > Appearance & Behavior > System Settings > Passwords. Note down the location of the KeePassDatabase path. - - - -### Code Sample -The following example demonstrates authenticating the SecretClient from the [azure-security-keyvault-secrets]() client library using the `DefaultAzureCredential` on a workstation where IntelliJ IDEA is installed, and the user has signed in with an Azure account. -```java -DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder() - // KeePass configuration isrequired only for Windows. No configuration needed for Linux / Mac. - .intelliJkeePassDatabasePath("C:\\Users\\user\\AppData\\Roaming\\JetBrains\\IdeaIC2020.1\\c.kdbx") - .build(); - -// Azure SDK client builders accept the credential as a parameter -SecretClient client = new SecretClientBuilder() - .vaultUrl("https://.vault.azure.net") - .credential(defaultAzureCredential) - .buildClient(); -``` - -## VS Code Authentication with Default Azure Credential - -The Visual Studio Code credential enables authentication in development environments where VS Code is installed with the [VS Code Azure Account extension](https://docs.microsoft.com/en-us/azure/developer/java/sdk/identity-dev-env-auth#intellij-credential). It uses the logged-in user information in the VS Code IDE and uses it to authenticate the application against Azure Active Directory. - -### Configuration - -Sign in Visual Studio Code Azure Account Extension - -The Visual Studio Code authentication is handled by an integration with the [Azure Account extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account). To use this form of authentication, install the Azure Account extension, then use View > Command Palette to execute the Azure: Sign In command. This command opens a browser window and displays a page that allows you to sign in to Azure. After you've completed the login process, you can close the browser as directed. Running your application (either in the debugger or anywhere on the development machine) will use the credential from your sign-in. - - -### Code Sample -The following example demonstrates authenticating the SecretClient from the azure-security-keyvault-secrets client library using the `DefaultAzureCredential` on a workstation where Visual Studio Code is installed, and the user has signed in with an Azure account. - -```java -DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build(); - -// Azure SDK client builders accept the credential as a parameter. -SecretClient client = new SecretClientBuilder() - .vaultUrl("https://.vault.azure.net") - .credential(defaultAzureCredential) - .buildClient(); -``` From ca39883dc3c88d8237793f548e11e64afacef4ec Mon Sep 17 00:00:00 2001 From: g2vinay Date: Tue, 14 Sep 2021 10:31:03 -0700 Subject: [PATCH 8/9] update --- .../azure/identity/EnvironmentCredential.java | 4 +++- .../identity/ManagedIdentityCredential.java | 4 +++- .../implementation/IdentityClient.java | 19 +++++++++---------- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/EnvironmentCredential.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/EnvironmentCredential.java index ddedd404519d..e3cd57162403 100644 --- a/sdk/identity/azure-identity/src/main/java/com/azure/identity/EnvironmentCredential.java +++ b/sdk/identity/azure-identity/src/main/java/com/azure/identity/EnvironmentCredential.java @@ -123,7 +123,9 @@ public Mono getToken(TokenRequestContext request) { if (tokenCredential == null) { return Mono.error(logger.logExceptionAsError(new CredentialUnavailableException( "EnvironmentCredential authentication unavailable." - + " Environment variables are not fully configured."))); + + " Environment variables are not fully configured." + + "Visit https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot to troubleshoot" + + "this issue."))); } else { return tokenCredential.getToken(request); } diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/ManagedIdentityCredential.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/ManagedIdentityCredential.java index d5129fb369c2..330291782bf7 100644 --- a/sdk/identity/azure-identity/src/main/java/com/azure/identity/ManagedIdentityCredential.java +++ b/sdk/identity/azure-identity/src/main/java/com/azure/identity/ManagedIdentityCredential.java @@ -72,7 +72,9 @@ public Mono getToken(TokenRequestContext request) { if (managedIdentityServiceCredential == null) { return Mono.error(logger.logExceptionAsError( new CredentialUnavailableException("ManagedIdentityCredential authentication unavailable. " - + "The Target Azure platform could not be determined from environment variables."))); + + "The Target Azure platform could not be determined from environment variables." + + "Visit https://aka.ms/azsdk/net/identity/managedidentitycredential/troubleshoot to " + + "troubleshoot this issue."))); } return managedIdentityServiceCredential.authenticate(request) .doOnSuccess(t -> logger.info("Azure Identity => Managed Identity environment: {}", diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java index 338310001a8b..556d46877f09 100644 --- a/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java +++ b/sdk/identity/azure-identity/src/main/java/com/azure/identity/implementation/IdentityClient.java @@ -208,7 +208,7 @@ private Mono getConfidentialClientApplication() { return Mono.error(logger.logExceptionAsError( new IllegalArgumentException("Must provide client secret or client certificate path." + " To mitigate this issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java-azure-service-principal-authentication-troubleshoot"))); + + "https://aka.ms/azsdk/java/identity/serviceprincipalauthentication/troubleshoot"))); } ConfidentialClientApplication.Builder applicationBuilder = @@ -423,7 +423,7 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { } else { throw logger.logExceptionAsError(new IllegalStateException("A Safe Working directory could not be" + " found to execute CLI command from. To mitigate this issue, please refer to the troubleshooting " - + " guidelines here at https://aka.ms/azure-identity-java--azure-cli-credential-troubleshoot")); + + " guidelines here at https://aka.ms/azsdk/java/identity/azclicredential/troubleshoot")); } builder.redirectErrorStream(true); @@ -444,7 +444,7 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { new CredentialUnavailableException( "AzureCliCredential authentication unavailable. Azure CLI not installed." + "To mitigate this issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java--azure-cli-credential-troubleshoot")); + + "https://aka.ms/azsdk/java/identity/azclicredential/troubleshoot")); } output.append(line); } @@ -461,7 +461,7 @@ public Mono authenticateWithAzureCli(TokenRequestContext request) { "AzureCliCredential authentication unavailable." + " Please run 'az login' to set up account. To further mitigate this" + " issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java--azure-cli-credential-troubleshoot")); + + "https://aka.ms/azsdk/java/identity/azclicredential/troubleshoot")); } throw logger.logExceptionAsError(new ClientAuthenticationException(redactedOutput, null)); } else { @@ -527,7 +527,7 @@ public Mono authenticateWithAzurePowerShell(TokenRequestContext req return Mono.error(new ClientAuthenticationException( "Azure Powershell authentication failed. Error Details: " + t.getMessage() + ". To mitigate this issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java--azure-powershell-credential-troubleshoot", + + "https://aka.ms/azsdk/java/identity/powershellcredential/troubleshoot", null, t)); } exceptions.add((CredentialUnavailableException) t); @@ -544,7 +544,7 @@ public Mono authenticateWithAzurePowerShell(TokenRequestContext req + "\r\n" + "Azure Powershell authentication failed using powershell-core(powershell)" + " with following error: " + last.getMessage() + (z == 0 ? ". To mitigate this issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java--azure-powershell-credential-troubleshoot" : ""), + + "https://aka.ms/azsdk/java/identity/powershellcredential/troubleshoot" : ""), last.getCause()); } return Mono.error(last); @@ -559,7 +559,6 @@ private Mono getAccessTokenFromPowerShell(TokenRequestContext reque logger.verbose("Azure Powershell Authentication = > Checking if Az.Accounts module is installed or " + "not in Azure Powershell by executing this command `%s`. This module is required to execute Azure" + " Powershell Credential.", azAccountsCommand); - String return manager.runCommand(azAccountsCommand) .flatMap(output -> { if (output.contains("The specified module 'Az.Accounts' with version '2.2.0' was not loaded " @@ -652,7 +651,7 @@ public Mono authenticateWithUsernamePassword(TokenRequestContext requ } )).onErrorMap(t -> new ClientAuthenticationException("Failed to acquire token with username and " + "password. To mitigate this issue, please refer to the troubleshooting guidelines " - + "here at https://aka.ms/azure-identity-java--azure-username-password-credential-troubleshoot", + + "here at https://aka.ms/azsdk/net/identity/usernamepasswordcredential/troubleshoot", null, t)).map(MsalToken::new); } @@ -768,7 +767,7 @@ public Mono authenticateWithVsCodeCredential(TokenRequestContext requ return Mono.error(new CredentialUnavailableException("VsCodeCredential " + "authentication unavailable. ADFS tenant/authorities are not supported. " + "To mitigate this issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java-azure-vscode-credential-troubleshoot")); + + "https://aka.ms/azsdk/net/identity/vscodecredential/troubleshoot")); } VisualStudioCacheAccessor accessor = new VisualStudioCacheAccessor(); @@ -796,7 +795,7 @@ public Mono authenticateWithVsCodeCredential(TokenRequestContext requ return Mono.error(new CredentialUnavailableException("Failed to acquire token with" + " VS code credential." + " To mitigate this issue, please refer to the troubleshooting guidelines here at " - + "https://aka.ms/azure-identity-java-azure-vscode-credential-troubleshoot", t)); + + "https://aka.ms/azsdk/net/identity/vscodecredential/troubleshoot", t)); } return Mono.error(new ClientAuthenticationException("Failed to acquire token with" + " VS code credential", null, t)); From c2fbf09abd0de502341302be38dc7ad3a1d55421 Mon Sep 17 00:00:00 2001 From: Vinay Gera Date: Tue, 12 Oct 2021 11:10:13 -0700 Subject: [PATCH 9/9] update --- sdk/identity/azure-identity/Troubleshoot.md | 74 ++++++++++----------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/sdk/identity/azure-identity/Troubleshoot.md b/sdk/identity/azure-identity/Troubleshoot.md index a0e6fcbc3fdb..4362ce1d00e0 100644 --- a/sdk/identity/azure-identity/Troubleshoot.md +++ b/sdk/identity/azure-identity/Troubleshoot.md @@ -9,26 +9,26 @@ This troubleshooting guide covers mitigation steps to resolve these exceptions t - [Troubleshooting Environment Credential Authentication Issues](#troubleshooting-environment-credential-authentication-issues) - [Troubleshooting Service Principal Authentication Issues](#troubleshooting-service-principal-authentication-issues) - [Troubleshooting Username Password Authentication Issues](#troubleshooting-username-password-authentication-issues) - - [Troubleshooting Mananged Identity Authenticaiton Issues](#troubleshooting-mananged-identity-authenticaiton-issues) - - [Troubleshooting Visual Studio Code Authenticaiton Issues](#troubleshooting-visual-studio-code-authenticaiton-issues) - - [Troubleshooting Azure CLI Authenticaiton Issues](#troubleshooting-azure-cli-authenticaiton-issues) - - [Troubleshooting Azure Powershell Authenticaiton Issues](#troubleshooting-azure-powershell-authenticaiton-issues) + - [Troubleshooting Managed Identity Authentication Issues](#troubleshooting-managed-identity-authentication-issues) + - [Troubleshooting Visual Studio Code Authentication Issues](#troubleshooting-visual-studio-code-authentication-issues) + - [Troubleshooting Azure CLI Authentication Issues](#troubleshooting-azure-cli-authentication-issues) + - [Troubleshooting Azure Powershell Authentication Issues](#troubleshooting-azure-powershell-authentication-issues) ## Troubleshooting Default Azure Credential Authentication Issues. ### Credential Unavailable Exception -The `DefaultAzureCredential` attempts to retrieve an access token by sequentially invoking a chain of credentials. The `CredentialUnavailableException` in this scenario signifies that all the credentials in the chain failed to retrieve the token in the current environment setup/configuration. You need to follow the configurtion instructions for the respective credential you're looking to use via `DefaultAzureCredential` chain, so that the credential can work in your environment. +The `DefaultAzureCredential` attempts to retrieve an access token by sequentially invoking a chain of credentials. The `CredentialUnavailableException` in this scenario signifies that all the credentials in the chain failed to retrieve the token in the current environment setup/configuration. You need to follow the configuration instructions for the respective credential you're looking to use via `DefaultAzureCredential` chain, so that the credential can work in your environment. -Please follow the configuration instructions in the `Credential Unvavailable` section of hte troublehsooting guidelines below for the repsective credential/authentication type you're looking to use via `DefaultAzureCredential`: +Please follow the configuration instructions in the `Credential Unvavailable` section of hte troubleshooting guidelines below for the respective credential/authentication type you're looking to use via `DefaultAzureCredential`: -| Credential Type | Trobuleshoot Guide | +| Credential Type | Troubleshoot Guide | | --- | --- | | Environment Credential | [Environment Credential Troubleshooting Guide](#troubleshooting-environment-credential-authentication-issues) | | Managed Identity Credential | [Managed Identity Troubleshooting Guide](#troubleshooting-managed-identity-authentication-issues) | -| Visual Studio Code Credential | [Visual Studio Code Troubleshooting Guide](#troubleshooting-visual-studio-code-authenticaiton-issues) | -| Azure CLI Credential | [Azure CLI Troubleshooting Guide](#troubleshooting-azure-cli-authenticaiton-issues) | +| Visual Studio Code Credential | [Visual Studio Code Troubleshooting Guide](#troubleshooting-visual-studio-code-authentication-issues) | +| Azure CLI Credential | [Azure CLI Troubleshooting Guide](#troubleshooting-azure-cli-authentication-issues) | | Azure Powershell Credential | [Azure Powershell Troubleshooting Guide](#troubleshooting-azure-powershell-authentication-issues) | @@ -39,7 +39,7 @@ Please follow the configuration instructions in the `Credential Unvavailable` se ### Credential Unavailable Exception #### Environment variables not configured -The `EnvironmentCredential` supports Service Principal authentication and Username + Password Authentication. To utilize the desired way of authentication via `EnvironmentCredential`, you need to ensure the environment varialbes below are configured properly and the application is able to read them. +The `EnvironmentCredential` supports Service Principal authentication and Username + Password Authentication. To utilize the desired way of authentication via `EnvironmentCredential`, you need to ensure the environment variables below are configured properly and the application is able to read them. ##### Service principal with secret @@ -65,9 +65,9 @@ AZURE_PASSWORD | The associated password for the given username. | ### Client Authentication Exception The `EnvironmentCredential` supports Service Principal authentication and Username + Password Authentication. -Please follow the troublehsooting guidelines below for the repsective authentication which you tried and failed. +Please follow the troubleshooting guidelines below for the respective authentication which you tried and failed. -| Authentication Type | Trobuleshoot Guide | +| Authentication Type | Troubleshoot Guide | | --- | --- | | Service Principal | [Service Principal Auth Troubleshooting Guide](#troubleshooting-username-password-authentication-issues) | | Username Password | [Username Password Auth Troubleshooting Guide](#troubleshooting-username-password-authentication-issues) | @@ -77,8 +77,8 @@ Please follow the troublehsooting guidelines below for the repsective authentica ## Troubleshooting Username Password Authentication Issues. -### Two Factor Authentication Required Error. -The `UsernamePassword` credential works only for users whose two factor authentication has been disabled in Azure Active Directrory. You can change the Multi Factor Authentication in Azure Portal by folliwng the steps [here](https://docs.microsoft.com/en-us/azure/active-directory/authentication/howto-mfa-userstates#change-the-status-for-a-user). +### Two-Factor Authentication Required Error. +The `UsernamePassword` credential works only for users whose two-factor authentication has been disabled in Azure Active Directory. You can change the Multi-Factor Authentication in Azure Portal by following the steps [here](https://docs.microsoft.com/azure/active-directory/authentication/howto-mfa-userstates#change-the-status-for-a-user). @@ -89,55 +89,55 @@ The `UsernamePassword` credential works only for users whose two factor authenti #### Client Id -The Client Id is the application Id of the registered application / service principal in Azure Active Directory. +The Client ID is the application ID of the registered application / service principal in Azure Active Directory. It is a required parameter for `ClientSecretCredential` and `ClientCertificateCredential`. If you have already created your service principal -then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). +then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). #### Tenant Id The tenant id is te Global Unique Identifier (GUID) that identifies your organization. It is a required parameter for `ClientSecretCredential` and `ClientCertificateCredential`. If you have already created your service principal -then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). +then you can retrieve the client/app id by following the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in). ### Client Secret Credential Issues #### Client Secret Argument The client secret is the secret string that the application uses to prove its identity when requesting a token, this can also can be referred to as an application password. -If you have already created a servie principal you can follow the instructions [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret) to get the client secret for your application. +If you have already created a service principal you can follow the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret) to get the client secret for your application. ### Client Certificate Credential Issues #### Client Certificate Argument -The `Client Certificate Credential` accepts `pfx` and `pem` certificates. The certificate needs to be associated with your registered application/service principal. To create and associate a certificate with your registered app. please follow the instrucitons [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-1-upload-a-certificate). +The `Client Certificate Credential` accepts `pfx` and `pem` certificates. The certificate needs to be associated with your registered application/service principal. To create and associate a certificate with your registered app. please follow the instructions [here](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#option-1-upload-a-certificate). ### Create a new service principal -If you're looking to create a new service principal and would like to use that, then follow tne instructions [here](https://docs.microsoft.com/en-us/azure/developer/java/sdk/identity-service-principal-auth#create-a-service-principal-with-the-azure-cli) to create a new service principal. +If you're looking to create a new service principal and would like to use that, then follow tne instructions [here](https://docs.microsoft.com/azure/developer/java/sdk/identity-service-principal-auth#create-a-service-principal-with-the-azure-cli) to create a new service principal. -## Troubleshooting Mananged Identity Authenticaiton Issues +## Troubleshooting Managed Identity Authentication Issues ### Credential Unavailable #### Connection Timed Out / Connection could not be established / Target Environment could not be determined. The Managed Identity credential runs only on Azure Hosted machines/servers. So ensure that you are running your application on an -Azure Hosted resource. Currently Azure Identity SDK supports [Managed Identity Authentication]((https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)) +Azure Hosted resource. Currently, Azure Identity SDK supports [Managed Identity Authentication]((https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview)) in the below listed Azure Services, so ensure you're running your application on one of these resources and have enabled the Managed Identity on them by following the instructions at their configuration links below. Azure Service | Managed Identity Configuration --- | --- | -[Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) -[Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=java) +[Azure Virtual Machines](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) | [Configuration Instructions](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm) +[Azure App Service](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) | [Configuration Instructions](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=java) [Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/use-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/aks/use-managed-identity) [Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/msi-authorization) | | -[Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-arc-enabled-servers) -[Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/en-us/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) +[Azure Arc](https://docs.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) | [Configuration Instructions](https://docs.microsoft.com/azure/azure-arc/servers/security-overview#using-a-managed-identity-with-arc-enabled-servers) +[Azure Service Fabric](https://docs.microsoft.com/azure/service-fabric/concepts-managed-identity) | [Configuration Instructions](https://docs.microsoft.com/azure/service-fabric/configure-existing-cluster-enable-managed-identity-token-service) -## Troubleshooting Visual Studio Code Authenticaiton Issues +## Troubleshooting Visual Studio Code Authentication Issues ### Credential Unavailable @@ -171,51 +171,51 @@ AZURE GOVERNMENT | https://login.microsoftonline.us/ -## Troubleshooting Azure CLI Authenticaiton Issues +## Troubleshooting Azure CLI Authentication Issues ### Credential Unavailable #### Azure CLI Not Installed. THe `Azure CLI Credential` failed to execute as Azure CLI command line tool is not installed. -To use Azure CLI credential, the Azure CLI needs to be installed, please follow the instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) +To use Azure CLI credential, the Azure CLI needs to be installed, please follow the instructions [here](https://docs.microsoft.com/cli/azure/install-azure-cli) to install it for your platform and then try running the credential again. #### Azure account not logged in. The `Azure CLI Credential` utilizes the current logged in Azure user in Azure CLI to fetch an access token. -You need to login to your account in Azure CLI via `az login` command. You can further read instructions to [Sign in with Azure CLI](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). +You need to log in to your account in Azure CLI via `az login` command. You can further read instructions to [Sign in with Azure CLI](https://docs.microsoft.com/cli/azure/authenticate-azure-cli). Once logged in try running the credential again. ### Illegal State #### Safe Working Directory Not Located. -The `Azure CLI Credential` was not able to locoate a value for System Environment property `SystemRoot` to execute in. +The `Azure CLI Credential` was not able to locate a value for System Environment property `SystemRoot` to execute in. Please ensure the `SystemRoot` environment variable is configured to a safe working directory and then try running the credential again. -## Troubleshooting Azure Powershell Authenticaiton Issues +## Troubleshooting Azure Powershell Authentication Issues ### Credential Unavailable #### Powershell not installed. -The `Azure Powershell Credential` utilizes the locally installed `Powershell` command line tool to fetch an access token. Please ensure it is installed on your platform by following the instructions [here](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.1) and then run the credential again. +The `Azure Powershell Credential` utilizes the locally installed `Powershell` command line tool to fetch an access token. Please ensure it is installed on your platform by following the instructions [here](https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-7.1) and then run the credential again. -#### Azure Az Moudle Not Installed. +#### Azure Az Module Not Installed. The `Azure Powershell Credential` failed to execute as Azure az module is not installed. -To use Azure Powershell credential, the Azure az module needs to be installed, please follow the instructions [here](https://docs.microsoft.com/en-us/powershell/azure/install-az-ps?view=azps-6.3.0) +To use Azure Powershell credential, the Azure az module needs to be installed, please follow the instructions [here](https://docs.microsoft.com/powershell/azure/install-az-ps?view=azps-6.3.0) to install it for your platform and then try running the credential again. #### Azure account not logged in. The `Azure Powershell Credential` utilizes the current logged in Azure user in Azure Powershell to fetch an access token. -You need to login to your account in Azure Powershell via `Connect-AzAccount` command. You can further read instructions to [Sign in with Azure Powershell](https://docs.microsoft.com/en-us/powershell/azure/authenticate-azureps?view=azps-6.3.0). +You need to log in to your account in Azure Powershell via `Connect-AzAccount` command. You can further read instructions to [Sign in with Azure Powershell](https://docs.microsoft.com/powershell/azure/authenticate-azureps?view=azps-6.3.0). Once logged in try running the credential again. #### Deserialization error. The `Azure Powershell Credential` was able to retrieve a response from the Azure Powershell when attempting to get an access token but failed to parse that response. -In your local powershell window, run the following command to ensure that Azure Powerhsell is returning an access token in correct format. +In your local powershell window, run the following command to ensure that Azure Powershell is returning an access token in correct format. ```pwsh Get-AzAccessToken -ResourceUrl ""