CircleCI jobs can use OpenID Connect (OIDC) identity tokens to securely access cloud providers without having to store a static credential in CircleCI. This article describes how to access Azure resources using OpenID Connect (OIDC).

Creating an Azure Active Directory application and service principal

First, create a new application and service principal for Azure Active Directory. Copy the values you enter; they will be used in the CircleCI workflow:

  • Application (client) ID
  • Directory (tenant) ID

Application overview

Next, assign roles to this application from Access Control (IAM).

In this case, we will assign only the Reader role.

Assign role

Adding federation credentials

The next step is to add federation credentials to make the Azure Active Directory application you created available to OpenID Connect (OIDC).

Go to Certificates and Secrets > Federation Credentials > Add Credentials.

Add federation credentials

From Federation Credentials Scenario, select Other Issuers.

Other issues

Fill in the required fields to add federation credentials:

  • Issuer:<organization_id>

The organization_id can be found in CircleCI’s Organization Settings.

Organization settings

  • Subject identifier: org/<organization_id>/project/<project_id>/user/<user_id>

The project_id can be found in the Project Settings for your CircleCI project.

Project settings

The user_id can be found in your User Settings.

User settings

  • Name: Enter any value.

  • Audience: Add your <organization_id>.

Creating a CircleCI context

The CircleCI workflow that you create must specify the application (client) ID and directory (tenant) ID of your Azure Active Directory application. A safer option is to store these values as CircleCI contexts.

Create a new context called OIDC-Azure and add the following values to Environment Variables.

Environment variables

  • AZURE_CLIENT_ID: Application (client) ID of the Azure Active Directory application
  • AZURE_TENANT_ID: Directory (tenant) ID for Azure Active Directory applications

Creating a CircleCI workflow

Now create a CircleCI configuration file .circleci/config.yml and enter this code:

version: 2.1

      - image: cimg/azure:2023.07
      - run:
          name: az login using OIDC
          command: |
            az login \
                --service-principal \
                --user "${AZURE_CLIENT_ID}" \
                --tenant "${AZURE_TENANT_ID}" \
                --federated-token "${CIRCLE_OIDC_TOKEN}"
      - run: az vm list

      - login-azure-with-oidc:
            - OIDC-Azure

The execution environment is the cimg/azure Docker image provided by CircleCI with the Azure CLI pre-installed.

To login to Azure (az login), first use the --service-principal option to log in using the service principal of Azure Active Directory.

Then, using the oidc-azure context that you just saved, specify the following within the job:

  • AZURE_CLIENT_ID: Application (client) ID of the Azure Active Directory application
  • AZURE_TENANT_ID: Directory (tenant) ID for Azure Active Directory applications

Specify the --federated-token option CircleCI_OIDC_TOKEN. This is the token provided by the CircleCI job that gives the OpenID Connect (OIDC) token.

The az login command is executed followed by the az vm list command using the reader role previously assigned to the service principal.

The execution of the workflow confirms the success of the az login command using OIDC and the successful execution of the az vm list command.



In this article, we have shown how to achieve secure access to Azure by using OpenID Connect (OIDC), without having to maintain a static credential on the CircleCI side.

CircleCI offers a full range of multi-cloud integration and deployment options, including support for OpenID Connect. We hope you will use these to improve your existing CircleCI workflows or when introducing a new CI/CD pipeline!

Learn more about OIDC: