Authentication
Make sure you are using the latest versions.
Overview
All the Azure Maven/Gradle plugins share the same authentication logic. You can use either one of authentication in the bellowing, if you don't specify any authentication configuration in <auth> section, the plugin will try all the auth methods one by one.
- Service Principles in plugin configuration
- Service Principles in settings.xml (for Maven use only)
- Managed Identity (since
azure-webapp-maven-plugin:2.6.0,azure-functions-maven-plugin:1.19.0,azure-spring-apps-maven-plugin:.1.12.0, for Azure hosting compute resource only) - Azure CLI (Recommended for developer)
- VSCode will be supported soon
- Visual Studio will be supported in future releases
- OAuth2 (A browser is required)
- Device Code
- Maven Login(deprecated) (Deprecating, may will not be supported in future release)
The authentication information is supposed to be at <auth> selection at top level of plugin configuration, here are two sample configurations for Azure functions plugins(maven and gradle):
Sample Configuration 1
<plugin>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-functions-maven-plugin</artifactId>
<version>${azure.functions.maven.plugin.version}</version>
<configuration>
<auth>
<type>service_principal</type>
<client>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</client>
<tenant>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy</tenant>
<key>zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz</key>
<environment>azure</environment>
</auth>
<!-- function app name -->
<appName>${azure}</appName>
...
</configuration>
</plugin>
Sample Configuration 2
azurefunctions {
resourceGroup = 'my-resource-group'
appName = 'my-functions-sample1'
// ...
authentication {
type = "service_principal"
environment= "azure"
client = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
tenant = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
key = "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
}
}
You need to update the plugin to recent versions to get full support of all auth types.
Type
You can specify which authentication method to use with <type> in <auth> configuration, the default value is auto, and here are all valid values:
- service_principal
- Will use credential specified in plugin configuration or Maven settings.xml, this is also the first priority authentication method in
auto
- Will use credential specified in plugin configuration or Maven settings.xml, this is also the first priority authentication method in
- managed_identity
- Will use the system managed credential managed by azure, see this link to enable system managed identity(don't forget to add role assignment for you managed identity)
- azure_cli
- Will use credential provided by Azure CLI, this could also be used in Azure Cloud Shell.
- vscode
- Will use credential provided by Azure Account extension.
- visual_studio
- Will use credential provided by Visual Studio, click the 'File -> Account Settings...' to see account information.
- oauth2
- Will use credential provided by oauth2, a browser will be opened, you need to follow the page to follow the login process.
- device_code
- Very similar to oauth2, it provides you a login-code together with an url, you need to open a browser at any machine and fill-in the login-code, then you can follow the page to follow to finish the login process on the web page.
- azure_auth_maven_plugin
- Will use credential provided by Azure Auth Maven Plugin, it will first consume existing secret files, and will guide you login with OAuth or Device Login if you hadn't authenticated with Auth Maven Plugin before.
- auto
- The default auth type, it will try all the auth methods in the following sequence: service_principal, managed_identity, azure_cli, vscode, visual_studio, oauth2, device_code, azure_auth_maven_plugin
If you need to connect to non-global azure cloud, you need to set the
<environment>explicitly in <auth> selection for service_principal, managed_identity, oauth2, device_code methods.
Service Principles in plugin configuration
Follow the instructions in Create the service principal to create a service principal which will be used to authenticate with Azure.
az ad sp create-for-rbac -n <your-application-name>
Use service principals in <configuration> section of azure plugins like azure-xxx-maven-plugin in pom.xml, for example:
<configuration>
<auth>
<client>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</client>
<tenant>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy</tenant>
<key>zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz</key>
<environment>azure</environment>
</auth>
</configuration>
Where the values for the configuration properties are listed in the following table:
| Property | Required | Description |
|---|---|---|
| client | true | Specifies the Client ID of your service principal. |
| tenant | true | Specifies the Tenant ID of your service principal. |
| key | false | Specifies the password if your service principal uses password authentication. |
| certificate | false | Specifies the absolute path of your certificate if your service principal uses certificate authentication. Note: Only PKCS12 certificates are supported. |
| certificatePassword | false | Specifies the password for your certificate, if there is any. |
| environment | false | Specifies the target Azure cloud environment; the default value is azure. The possible values are: - azure- azure_china- azure_germany- azure_us_government |
Service Principles in settings.xml
It is recommended to store Service Principals above in Maven settings.xml. You can use client and key(alternatively you can use certificate and certificatePassword), you can use maven to protect the key and certificatePassword, in the following sample, the key is encrypted by maven.
<server>
<id>azure-sp-auth1</id>
<configuration>
<client>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</client>
<tenant>yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy</tenant>
<key>{abcdefg...hijk==}</key>
<environment>azure</environment>
</configuration>
</server>
Note: The maven
settings.xmlfile might be in a path like the following examples:
/etc/maven/settings.xml%ProgramFiles%\apache-maven\3.5.0\conf\settings.xml$HOME/.m2/settings.xml
in pom.xml, the server id is referenced in serverId(please be aware that the <auth> configuration is not supposed to be specified in azure maven plugin, but feature plugins like azure spring plugin).
<configuration>
<auth>
<type>service_principal</type>
<serverId>azure-sp-auth1</serverId>
</auth>
</configuration>
Note:
If you specify both<serverId>and other configurations like<client>and<tenant>in last chapter, only<serverId>will be used, you may be shown an error if you specified a wrong serverId.
Inpom.xml, you can not use maven encrypted values.
Managed Identity
- Nothing needs to config in
pom.xmlif there is only one managed identity associated to the Azure hosting resource. - Specify which user assigned identity by client if there are multiple identities associated.
<configuration>
<auth>
<type>managed_identity</type>
<client>xxxxxxxxxxxxxxxxxxxxx</client>
</auth>
</configuration>
Azure CLI
Install the Azure CLI 2.0 by following the instructions in the Install Azure CLI 2.0 article.
- Run the following commands to log into your Azure subscription：
$ az login
$ az account set --subscription <put your subscription guid here>
This will create credential files under $HOME/.azure/ that Azure Maven plugins will leverage it with very high priority, you can specify to use Azure CLI credential explicitly with following configuration
<configuration>
<auth><type>azure_cli</type></auth>
</configuration>
VSCode
Install the VSCode Account Plugin in VSCode.
- Open VSCode, press
F1and type in 'Azure: Sign in', and press ENTER. - Follow the web page to finish the login process
- If you have multiple subscriptions, you can do the following steps to select a target subscription: Open VSCode,press
F1and type in 'Azure: Select Subscriptions', mark the target subscription and click on theOKbutton at the right corner of the VSCode prompt.
Visual Studio
Install the Visual Studio, open Visual Studio, choose File -> Account Settings..., at the account page, click the All Accounts + Add -> Microsoft account to sign in at Visual Studio side.
OAuth2
If you are not in azure environment(cloud shell, managed identity), and you have no above tools installed, and you have a browser, you can use this auth type, it will open the browser for the login page, you can then continue the sign-in process through the web page.
<configuration>
<auth>
<type>oauth2</type>
<tenant>${tenantId}</tenant> <!-- optional -->
</auth>
</configuration>
Device Code
If you are not in azure environment(cloud shell, managed identity), and you have no above tools installed, and the shell in which you are invoking mvn can invoke a browser, you can use this auth type, it will open the browser for the login page, you can then continue the sign-in process through the web page. you can configure to use Device Code credential explicitly with following configuration:
<configuration>
<auth>
<type>device_code</type>
<tenant>${tenantId}</tenant> <!-- optional -->
</auth>
</configuration>
Maven Plugin for Azure Account
This method use azure:login maven goal from azure-maven-plugin(you can get login azure through mvn command mvn com.microsoft.azure:azure-maven-plugin:0.2.0:login). Check here for details.