To use the APIs in the Azure Management Libraries for Java, as the first step you need to create an authenticated client. This document is to introduce several possible approaches for authentication.
- An Azure tenant for Graph RBAC.
- An Azure subscription for resource management.
- An Azure Active Directory service principal. You can create a service principal via Azure Portal, Azure CLI or Azure Powershell.
If you want to authenticate as simple as possible, you need to prepare TokenCredential
and AzureProfile
as below.
- The
TokenCredential
is an interface in theazure-core
package for credentials that can provide a token. - Azure Identity offers multiple implementations of the
TokenCredential
class in theazure-identity
package. To learn more, see credentials in Azure Identity.
Sample code to create a simple ClientSecretCredential
:
ClientSecretCredential clientSecretCredential = new ClientSecretCredentialBuilder()
.clientId("<YOUR_CLIENT_ID>")
.clientSecret("<YOUR_CLIENT_SECRET>")
.tenantId("<YOUR_TENANT_ID>")
// authority host is optional
.authorityHost("<AZURE_AUTHORITY_HOST>")
.build();
The value of AZURE_AUTHORITY_HOST
can be set via AzureAuthorityHosts
or AzureEnvironment::getActiveDirectoryEndpoint
.
- The
AzureProfile
is a class holdingAzureEnvironment
,subscriptionId
,tenantId
to configure the requests sending to wire. - The
subscriptionId
is mandatory for most resource management while thetenantId
would be required only for Graph RBAC. They can be set via environment variables.
variable name | value |
---|---|
AZURE_TENANT_ID |
id of the principal's Azure Active Directory tenant |
AZURE_SUBSCRIPTION_ID |
id of the subscription for the Azure resources |
Sample code to create a AzureProfile
:
//AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
AzureProfile profile = new AzureProfile("<YOUR_TENANT_ID>", "<YOUR_SUBSCRIPTION_ID>", AzureEnvironment.AZURE);
The sample code assumes global Azure. Please change AzureEnvironment.AZURE
variable if otherwise.
Sample code for Azure Germany, with EnvironmentCredential
:
AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE_GERMANY);
EnvironmentCredential credential = new EnvironmentCredentialBuilder()
.authorityHost(profile.environment().getActiveDirectoryEndpoint())
.build();
Once the TokenCredential
and AzureProfile
are ready, you can move forward with below authenticating code. It helps build http pipeline internally with default configuration.
Azure azure = Azure.authenticate(credential, profile).withDefaultSubscription();
The Authenticated
class provides access to a subset of Azure APIs that do not require a specific subscription. If the profile does not contain a subscription, you can select a subscription via Authenticated::subscriptions
. Similarly, you can select a tenant via Authenticated::tenants
.
Azure.Authenticated authenticated = Azure.authenticate(credential, profile);
String subscriptionId = authenticated.subscriptions().list().iterator().next().subscriptionId();
Azure azure = authenticated.withSubscription(subscriptionId);
If you want to take full control of Azure client, you could build your own http pipeline for authentication.
- The
HttpPipelinePolicy
is an interface that process provided request context and invokes the next policy. To learn more, see policies in Azure Core and policies in Azure Management Libraries for Java.
- The
HttpClient
is a generic interface for sending HTTP requests and getting responses. - azure-core-http-netty provides a Netty derived HTTP client.
- azure-core-http-okhttp provides an OkHttp derived HTTP client.
- The
HttpPipeline
is a class that HTTP requests and responses will flow through. It is a construct that contains a list ofHttpPipelinePolicy
which are applied to a request sequentially to prepare it being sent by anHttpClient
.
Sample code to create a HttpPipeline
:
HttpPipeline httpPipeline = new HttpPipelineBuilder()
.policies(httpPipelinePolicies)
.httpClient(httpClient)
.build();
Once your custom configurations are ready, you can move forward with below authenticating code. It would execute the settings you apply in the custom HttpPipeline.
Azure azure = Azure.authenticate(httpPipeline, profile).withDefaultSubscription();
If you want to configure part of http pipeline instead of building new one, you may set via Azure::configure
.
Azure azure = Azure.configure()
.withPolicy(customPolicy)
.withRetryPolicy(customRetryPolicy)
.withHttpClient(httpClient)
.authenticate(credential, profile)
.withDefaultSubscription();