Skip to content

Authentication

Jump to bottom
Ed Burns edited this page Jan 10, 2023 · 46 revisions

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.

  1. Service Principles in plugin configuration
  2. Service Principles in settings.xml (for Maven use only)
  3. 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)
  4. Azure CLI (Recommended for developer)
  5. VSCode will be supported soon
  6. Visual Studio will be supported in future releases
  7. OAuth2 (A browser is required)
  8. Device Code
  9. 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
  • 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
  • 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.xml file 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.
In pom.xml, you can not use maven encrypted values.

Managed Identity

  • Nothing needs to config in pom.xml if 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>

image

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 F1 and 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 F1 and type in 'Azure: Select Subscriptions', mark the target subscription and click on the OK button at the right corner of the VSCode prompt.
VS code sign-in

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.

VS account-settings

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.

Clone this wiki locally