DOCSEARCHbyAlgolia
Submit Docs

Azure Login Action

repository·master·Indexed 19 days ago

https://github.com/azure/login

A GitHub Action that provides a secure way to authenticate workflows with Azure, enabling the use of Azure CLI and Azure PowerShell in CI/CD pipelines. Version 3.0.0 supports multiple authentication methods, including OpenID Connect (OIDC), Service Principal Secrets, and System-assigned or User-assigned Managed Identities. It supports various cloud environments such as Azure Public Cloud, Azure US Government, Azure China Cloud, Azure German Cloud, and Azure Stack.

Tokens
4.9K
Snippets
14
Records
25
Agent score
65%

What's inside azure-login

  1. Overview of Azure Login Action

    master

    The Azure Login Action allows you to authenticate into Azure within a GitHub Actions workflow. Once authenticated, you can execute Azure CLI and Azure PowerShell scripts.

    Supported authentication methods include:

    • OpenID Connect (OIDC): The recommended method for increased security.
    • Service Principal Secret: Using a JSON credential string.
    • System-assigned Managed Identity
    • User-assigned Managed Identity

    Security Warnings

    • Log Privacy: By default, Azure CLI output is printed to stdout and stored in build logs. To prevent sensitive data from appearing in logs, set the environment variable AZURE_CORE_OUTPUT to none. You can override this for specific commands using the --output argument.
    • Self-hosted Runners: Avoid using Managed Identity on self-hosted runners in public repositories, as any user who can open a pull request might gain access to the runner's identity.

  2. Azure CLI dependency and compatibility

    master
    This action internally uses the Azure CLI and executes az login using the credentials provided via secrets. The action is tested against Azure CLI edge builds to ensure compatibility with upcoming releases and prevent workflow failures caused by breaking changes in the CLI.

  3. Login with OpenID Connect (OIDC) [Recommended]

    master

    OIDC is the recommended method for authenticating with Azure in GitHub Actions. It requires configuring a federated identity credential on either a Service Principal or a Managed Identity.

    Prerequisites:

    • Azure CLI version 2.30 or above.
    • A configured federated identity credential on your Azure identity.
    • GitHub Action secrets: AZURE_CLIENT_ID, AZURE_SUBSCRIPTION_ID, and AZURE_TENANT_ID.
    • Crucial: You must set permissions: id-token: write at the workflow or job level to allow the generation of the OIDC token.

    Usage: Pass the client, tenant, and subscription IDs directly to the with block of azure/login@v3.

    name: Run Azure Login with OIDC
on: [push]

permissions:
  id-token: write
  contents: read

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Azure login
        uses: azure/login@v3
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Azure CLI script
        uses: azure/cli@v2
        with:
          azcliversion: latest
          inlineScript: |
            az account show

  4. Login with a Service Principal Secret

    master

    You can authenticate using a Service Principal client secret. This requires creating a GitHub Action secret named AZURE_CREDENTIALS containing a JSON object with the following keys:

    • clientSecret: The service principal client secret.
    • subscriptionId: The subscription ID.
    • tenantId: The tenant ID.
    • clientId: The service principal client ID.

    Usage: Pass the AZURE_CREDENTIALS secret to the creds parameter of azure/login@v3.

        - uses: azure/login@v3
      with:
        creds: ${{ secrets.AZURE_CREDENTIALS }}

  5. Login without a subscription

    master

    If you need to run tenant-level commands (like az ad) that do not require an active subscription, set the allow-no-subscriptions parameter to true.

        - name: Azure Login
      uses: azure/login@v3
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        allow-no-subscriptions: true
        enable-AzPSSession: true

  6. Login to Azure US Government or Azure Stack Hub

    master

    To target specific Azure environments, use the environment parameter in azure/login@v3.

    • Azure US Government: Set environment: 'AzureUSGovernment'
    • Azure Stack Hub: Set environment: 'AzureStack'
        - uses: azure/login@v3
      with:
        creds: ${{ secrets.AZURE_CREDENTIALS }}
        environment: 'AzureUSGovernment'
        enable-AzPSSession: true

  7. Login with User-assigned Managed Identity

    master

    This method is only supported on GitHub self-hosted runners hosted on Azure virtual machines.

    Prerequisites:

    • An Azure VM configured as a GitHub self-hosted runner.
    • A user-assigned managed identity created and assigned a role.
    • The identity configured on the Azure virtual machine.
    • GitHub Action secrets: AZURE_CLIENT_ID (the identity's client ID), AZURE_SUBSCRIPTION_ID, and AZURE_TENANT_ID.

    Usage: Set auth-type: IDENTITY and provide the client-id of the user-assigned identity.

        - name: Azure login
      uses: azure/login@v3
      with:
        auth-type: IDENTITY
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
        enable-AzPSSession: true

  8. Login with System-assigned Managed Identity

    master

    This method is only supported on GitHub self-hosted runners hosted on Azure virtual machines.

    Prerequisites:

    • An Azure VM configured as a GitHub self-hosted runner.
    • System-assigned managed identity enabled on the VM.
    • Required software installed: PowerShell, Azure CLI, and Azure PowerShell.
    • GitHub Action secrets: AZURE_SUBSCRIPTION_ID and AZURE_TENANT_ID.

    Usage: Set auth-type: IDENTITY in the azure/login@v3 action.

        - name: Azure login
      uses: azure/login@v3
      with:
        auth-type: IDENTITY
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
        enable-AzPSSession: true

  9. Configure Azure Cloud Environments and Audience

    master

    By default, the action connects to the Azure Public Cloud (azurecloud). If you are using a different cloud environment, you must set the environment parameter and update the audience parameter accordingly.

    Supported environment values:

    • AzureUSGovernment
    • AzureChinaCloud
    • AzureGermanCloud
    • AzureStack

    When using OIDC, the default audience is api://AzureADTokenExchange.

  10. Configure Azure Stack environment

    master

    When the environment parameter is set to azurestack, the action performs additional setup to register the Azure Stack cloud environment. This requires the resourceManagerEndpointUrl parameter.

    To prevent conflicts, the action will:

    1. Unregister the existing AzureCloud cloud if it exists.
    2. Unregister the existing azurestack cloud if it is already registered.
    3. Register the azurestack cloud using the provided --endpoint-resource-manager and derived suffixes for Key Vault (--suffix-keyvault-dns) and Storage (--suffix-storage-endpoint).

    Requirement: resourceManagerEndpointUrl must be provided when environment is azurestack.

  11. Authentication methods in Azure CLI Login

    master

    The AzureCliLogin implementation supports several authentication flows depending on the provided configuration. The action automatically selects the appropriate az login command based on your auth-type and provided credentials:

    1. Service Principal with Secret: Uses --service-principal, --username (or --client-id for newer CLI versions), --tenant, and --password.
    2. OIDC (OpenID Connect): Uses --service-principal, --username (or --client-id), --tenant, and --federated-token.
    3. User-Assigned Managed Identity: Uses --identity and identifies the identity via --client-id (for CLI v2.69.0+) or --username (for older versions).
    4. System-Assigned Managed Identity: Uses --identity only.

    Note: If allow-no-subscriptions is enabled, the --allow-no-subscriptions flag is passed to the CLI command.

  12. Configure login cleanup behavior

    master

    The Azure Login Action performs "cleanup" to remove the login context. You can control this using environment variables at the workflow, job, or step level.

    Cleanup Steps:

    1. Pre-cleanup (main: step): Cleans up before the main login logic.
      • Disabled by default.
      • Enable via: AZURE_LOGIN_PRE_CLEANUP: true
    2. Post-cleanup (post: step): Cleans up after the action completes.
      • Enabled by default.
      • Disable via: AZURE_LOGIN_POST_CLEANUP: false