com.azure.identity.package-info Maven / Gradle / Ivy
Show all versions of azure-identity Show documentation
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
/**
* The Azure Identity library provides
* Microsoft Entra ID token
* authentication support across the
* Azure SDK. The library focuses on
* OAuth authentication with Microsoft Entra ID, and it offers various credential classes capable of acquiring a Microsoft Entra token
* to authenticate service requests. All the credential classes in this package are implementations of the
* TokenCredential interface offered by azure-core, and any of them can be used to construct service clients capable
* of authenticating with a TokenCredential.
*
* Getting Started
*
* The {@link com.azure.identity.DefaultAzureCredential} is appropriate for most scenarios where the application is
* intended to ultimately be run in Azure. This is because the {@link com.azure.identity.DefaultAzureCredential}
* combines credentials commonly used to authenticate when deployed, with credentials used to authenticate in a
* development environment.
*
* Note: This credential is intended to simplify getting started with the SDK by handling
* common scenarios with reasonable default behaviors. Developers who want more control or whose scenario isn't
* served by the default settings should use other credential types (detailed below). For more information refer to the
* default azure credential conceptual
* documentation.
*
* Sample: Construct a simple DefaultAzureCredential
*
* The following code sample demonstrates the creation of a {@link com.azure.identity.DefaultAzureCredential}, using
* the {@link com.azure.identity.DefaultAzureCredentialBuilder} to configure it. Once this credential is created, it
* may be passed into the builder of many of the Azure SDK for Java client builders as the 'credential' parameter.
*
*
*
* TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
*
*
*
* Further, it is recommended to read
* {@link com.azure.identity.DefaultAzureCredential DefaultAzureCredential JavaDocs} for more detailed information about
* the credential usage and the chain of credentials it runs underneath.
*
* The {@link com.azure.identity.DefaultAzureCredential} works well in most of the scenarios as it executes a chain
* of credentials underneath which covers well known authentication scenarios for both Azure hosted platforms and
* development environment. But, in some scenarios where only a specific authentication mechanism will work, it is
* recommended to use that specific credential to authenticate. Let's take a look at the individual
* authentication scenarios and their respective credential use below.
*
*
*
* Authenticate in Developer Environment
*
* Azure supports developer environment authentication via Azure CLI, Azure Powershell and Azure Tools for IntelliJ
* plugin in IntelliJ IDE. It involves interactively authenticating using user credentials locally on the developer
* machine. Once authenticated, the login information is persisted.
*
* The Azure Identity library supports authenticating in developer environment via
* {@link com.azure.identity.AzureCliCredential}, {@link com.azure.identity.AzurePowerShellCredential} and
* {@link com.azure.identity.IntelliJCredential}. These credentials offer a seamless authentication experience by
* utilizing the cached Azure Plugin login information from their respective IDE tool. For more information refer to the
* developer environment authentication
* documentation.
*
* Sample: Construct AzureCliCredential
*
* The following code sample demonstrates the creation of a {@link com.azure.identity.AzureCliCredential},
* using the {@link com.azure.identity.AzureCliCredentialBuilder} to configure it .Once this credential
* is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the
* 'credential' parameter.
*
*
*
* TokenCredential azureCliCredential = new AzureCliCredentialBuilder().build();
*
*
*
* Further, it is recommended to read
* {@link com.azure.identity.AzureCliCredential AzureCliCredential JavaDocs} for more detailed
* information about the credential usage.
*
* For other credentials that are compatible with developer tools authentication, refer to the table below.
*
*
*
*
* Authenticate via development tools
*
*
* Credential class
* Usage
*
*
*
*
* {@link com.azure.identity.AzurePowerShellCredential}
* This credential authenticates in a development environment with the logged in user or service principal
* in Azure PowerShell. It utilizes the account of the already logged in user on Azure Powershell
* to get an access token. If there's no user logged in locally on Azure Powershell, then it will not work.
* Further, it is recommended to read
* {@link com.azure.identity.AzurePowerShellCredential AzurePowerShellCredential JavaDocs} for more
* information about the credential usage.
*
*
* {@link com.azure.identity.IntelliJCredential}
* This credential authenticates in a development environment with the logged in user or service principal
* in Azure Toolkit for IntelliJ plugin on IntelliJ IDE. It utilizes the cached login information of the Azure
* Toolkit for IntelliJ plugin to seamlessly authenticate the application. If there's no user logged in locally
* on Azure Toolkit for IntelliJ in IntelliJ IDE, then it will not work. Further, it is recommended to read
* {@link com.azure.identity.IntelliJCredential IntelliJCredential JavaDocs} for more
* information about the credential usage.
*
*
*
*
*
*
*
*
* Authenticating on Azure Hosted Platforms via Managed Identity
*
* Azure
* Managed Identity is a feature in
* Microsoft Entra ID
* that provides a way for applications running on Azure to authenticate themselves with Azure resources without
* needing to manage or store any secrets like passwords or keys.
*
* The {@link com.azure.identity.ManagedIdentityCredential} authenticates the configured 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 the
* {@link com.azure.identity.ManagedIdentityCredential} will get your application authenticated, and offers a great
* secretless authentication experience. For more information refer to the
* managed identity authentication
* documentation.
*
* Sample: Construct a Managed Identity Credential
*
* The following code sample demonstrates the creation of a {@link com.azure.identity.ManagedIdentityCredential},
* using the {@link com.azure.identity.ManagedIdentityCredentialBuilder} to configure it. Once this credential is
* created, it may be passed into the builder of many of the Azure SDK for Java client builders as the
* 'credential' parameter.
*
*
*
* TokenCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder().build();
*
*
*
* Further, it is recommended to read
* {@link com.azure.identity.ManagedIdentityCredential ManagedIdentityCredential JavaDocs} for more detailed information
* about the credential usage and the Azure platforms it supports.
*
* For other credentials that work well in Azure Hosted platforms, refer to the table below.
*
*
*
*
* Authenticate Azure-hosted applications
*
*
* Credential class
* Usage
*
*
*
*
* {@link com.azure.identity.EnvironmentCredential}
* This credential authenticates a service principal or user via credential information specified in
* environment variables. The service principal authentication works well in Azure hosted platforms when Managed
* Identity is not available. Further, it is recommended to read
* {@link com.azure.identity.EnvironmentCredential EnvironmentCredential JavaDocs} for more information about
* the credential usage.
*
*
* {@link com.azure.identity.ChainedTokenCredential}
* This credential allows users to define custom authentication flows by chaining multiple credentials
* together. For example, the {@link com.azure.identity.ManagedIdentityCredential} and
* {@link com.azure.identity.EnvironmentCredential} can be chained together to sequentially execute on Azure
* hosted platforms. The credential that first returns the token is used for authentication. Further, it is
* recommended to read {@link com.azure.identity.ChainedTokenCredential ChainedTokenCredential JavaDocs} for more
* information about the credential usage.
*
*
*
*
*
*
*
*
* Authenticate with Service Principals
*
* Service Principal authentication is a type of authentication in Azure that enables a non-interactive login to
* Microsoft Entra ID, allowing an
* application or service to authenticate itself with Azure resources.
* A Service Principal is essentially an identity created for an application in Microsoft Entra ID that can be used to
* authenticate with Azure resources. It's like a "user identity" for the application or service, and it provides
* a way for the application to authenticate itself with Azure resources without needing to use a user's credentials.
* Microsoft Entra ID allows users to
* register service principals which can be used as an identity for authentication.
* A client secret and/or a client certificate associated with the registered service principal is used as the password
* when authenticating the service principal.
*
* The Azure Identity library supports both client secret and client
* certificate based service principal authentication via {@link com.azure.identity.ClientSecretCredential} and
* {@link com.azure.identity.ClientCertificateCredential} respectively. For more information refer to the
* service principal authentication
* documentation.
*
* Sample: Construct a ClientSecretCredential
*
* The following code sample demonstrates the creation of a {@link com.azure.identity.ClientSecretCredential},
* using the {@link com.azure.identity.ClientSecretCredentialBuilder} to configure it. The {@code tenantId},
* {@code clientId} and {@code clientSecret} parameters are required to create
* {@link com.azure.identity.ClientSecretCredential} .Once this credential is created, it may be passed into the
* builder of many of the Azure SDK for Java client builders as the 'credential' parameter.
*
*
*
* TokenCredential clientSecretCredential = new ClientSecretCredentialBuilder().tenantId(tenantId)
* .clientId(clientId)
* .clientSecret(clientSecret)
* .build();
*
*
*
* Further, it is recommended to read
* {@link com.azure.identity.ClientSecretCredential ClientSecretCredential JavaDocs} for more detailed information
* about the credential usage.
*
* For other credentials that are compatible with service principal authentication, refer to the table below.
*
*
*
*
* Authenticate service principals
*
*
* Credential class
* Usage
*
*
*
*
* {@link com.azure.identity.ClientAssertionCredential}
* This credential authenticates a service principal using a signed client assertion.
* It allows clients to prove their identity to Microsoft Entra ID without requiring them to disclose their
* credentials (such as a username and password). Further, it is recommended to read
* {@link com.azure.identity.ClientAssertionCredential ClientAssertionCredential JavaDocs} for more
* information about the credential usage.
*
*
* {@link com.azure.identity.ClientCertificateCredential}
* This credential authenticates a service principal using a certificate. It doesn't require transmission of
* a client secret and mitigates the security related password storage and network transmission issues.
* Further, it is recommended to read {@link com.azure.identity.ClientCertificateCredential
* ClientCertificateCredential JavaDocs} for more information about the credential usage.
*
*
*
*
*
*
*
*
* Authenticate with User Credentials
*
* User credential authentication is a type of authentication in Azure that involves a user providing their
* username and password to authenticate with Azure resources. In Azure, user credential authentication can be used to
* authenticate with Microsoft Entra ID.
*
* The Azure Identity library supports user credentials based authentication via
* {@link com.azure.identity.InteractiveBrowserCredential}, {@link com.azure.identity.DeviceCodeCredential} and
* {@link com.azure.identity.UsernamePasswordCredential}. For more information refer to the
* user credential authentication documentation.
*
*
* Sample: Construct InteractiveBrowserCredential
*
* The following code sample demonstrates the creation of a {@link com.azure.identity.InteractiveBrowserCredential},
* using the {@link com.azure.identity.InteractiveBrowserCredentialBuilder} to configure it .Once this credential
* is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the
* 'credential' parameter.
*
*
*
* TokenCredential interactiveBrowserCredential = new InteractiveBrowserCredentialBuilder().redirectUrl(
* "http://localhost:8765").build();
*
*
*
* Further, it is recommended to read
* {@link com.azure.identity.InteractiveBrowserCredential InteractiveBrowserCredential JavaDocs} for more information
* about the credential usage.
*
* For other credentials that are compatible with user credentials based authentication, refer to the table below.
*
*
*
*
*
* Authenticate users
*
*
* Credential class
* Usage
*
*
*
*
* {@link com.azure.identity.DeviceCodeCredential}
* This credential interactively authenticates a user on devices with limited UI. It prompts users
* to open an authentication URL with a device code on a UI enabled device and requires them to interactively
* authenticate there. Once authenticated, the original device requesting authentication gets authenticated
* and receives the access token. Further, it is recommended to read
* {@link com.azure.identity.DeviceCodeCredential DeviceCodeCredential JavaDocs} for more
* information about the credential usage.
*
*
* {@link com.azure.identity.AuthorizationCodeCredential}
* This credential authenticates a user with a previously obtained authorization code as part of an
* Oauth 2 flow. This is applicable for applications which control the logic of interactive user authentication
* to fetch an authorization code first. Once the application has received the authorization code, it can
* then configure it on this credential and use it to get an access token. Further, it is recommended to read
* {@link com.azure.identity.AuthorizationCodeCredential AuthorizationCodeCredential JavaDocs} for more
* information about the credential usage.
*
*
* {@link com.azure.identity.UsernamePasswordCredential}
* This credential authenticates a user with a username and password without multi-factored auth.
* This credential can be used on developer environment for user principals which do not require
* 2FA/MFA (multi-facotred) authentication. Further, it is recommended to read
* {@link com.azure.identity.UsernamePasswordCredential UsernamePasswordCredential JavaDocs} for more
* information about the credential usage.
*
*
*
*
*
*
* @see com.azure.identity.DefaultAzureCredential
* @see com.azure.identity.ManagedIdentityCredential
* @see com.azure.identity.EnvironmentCredential
* @see com.azure.identity.ClientSecretCredential
* @see com.azure.identity.ClientCertificateCredential
* @see com.azure.identity.InteractiveBrowserCredential
* @see com.azure.identity.DeviceCodeCredential
* @see com.azure.identity.UsernamePasswordCredential
* @see com.azure.identity.AzureCliCredential
* @see com.azure.identity.IntelliJCredential
*/
package com.azure.identity;