Configure Azure Active Directory authentication for an Azure Red Hat OpenShift 4 cluster (CLI)

If you choose to install and use the CLI locally, this article requires that you are running the Azure CLI version 2.6.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Retrieve your cluster-specific URLs that are going to be used to configure the Azure Active Directory application.

Set the variables for resource group and cluster name.

Replace <resource_group> with your resource group's name and <aro_cluster> with your cluster's name.


Construct the cluster's OAuth callback URL and store it in a variable oauthCallbackURL.


The AAD section in the OAuth callback URL should match the OAuth identity provider name you'll setup later.

domain=$(az aro show -g $resource_group -n $aro_cluster --query clusterProfile.domain -o tsv)
location=$(az aro show -g $resource_group -n $aro_cluster --query location -o tsv)
apiServer=$(az aro show -g $resource_group -n $aro_cluster --query apiserverProfile.url -o tsv)
webConsole=$(az aro show -g $resource_group -n $aro_cluster --query consoleProfile.url -o tsv)

The format of the oauthCallbackURL is slightly different with custom domains:

  • Run the following command if you are using a custom domain, e.g.

  • If you are not using a custom domain then the $domain will be an eight character alnum string and is extended by $



The AAD section in the OAuth callback URL should match the OAuth identity provider name you'll setup later.

Create an Azure Active Directory application for authentication

Replace <client_secret> with a secure password for the application.


Create an Azure Active Directory application and retrieve the created application identifier.

app_id=$(az ad app create \
  --query appId -o tsv \
  --display-name aro-auth \
  --reply-urls $oauthCallbackURL \
  --password $client_secret)

Retrieve the tenant ID of the subscription that owns the application.

tenant_id=$(az account show --query tenantId -o tsv)

Create a manifest file to define the optional claims to include in the ID Token

Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

You can use optional claims to:

  • Select additional claims to include in tokens for your application.
  • Change the behavior of certain claims that Azure AD returns in tokens.
  • Add and access custom claims for your application.

We'll configure OpenShift to use the email claim and fall back to upn to set the Preferred Username by adding the upn as part of the ID token returned by Azure Active Directory.

Create a manifest.json file to configure the Azure Active Directory application.

cat > manifest.json<< EOF
  "name": "upn",
  "source": null,
  "essential": false,
  "additionalProperties": []
"name": "email",
  "source": null,
  "essential": false,
  "additionalProperties": []

Update the Azure Active Directory application's optionalClaims with a manifest

az ad app update \
  --set optionalClaims.idToken=@manifest.json \
  --id $app_id

Update the Azure Active Directory application scope permissions

To be able to read the user information from Azure Active Directory, we need to define the proper scopes.

Add permission for the Azure Active Directory Graph.User.Read scope to enable sign in and read user profile.

az ad app permission add \
 --api 00000002-0000-0000-c000-000000000000 \
 --api-permissions 311a71cc-e848-46a1-bdf8-97ff7156d8e6=Scope \
 --id $app_id


You can safely ignore the message to grant the consent unless you are authenticated as a Global Administrator for this Azure Active Directory. Standard domain users will be asked to grant consent when they first login to the cluster using their AAD credentials.

Assign users and groups to the cluster (optional)

Applications registered in an Azure Active Directory (Azure AD) tenant are, by default, available to all users of the tenant who authenticate successfully. Azure AD allows tenant administrators and developers to restrict an app to a specific set of users or security groups in the tenant.

Follow the instructions on the Azure Active Directory documentation to assign users and groups to the app.

Configure OpenShift OpenID authentication

Retrieve the kubeadmin credentials. Run the following command to find the password for the kubeadmin user.

kubeadmin_password=$(az aro list-credentials \
  --name $aro_cluster \
  --resource-group $resource_group \
  --query kubeadminPassword --output tsv)

Log in to the OpenShift cluster's API server using the following command.

oc login $apiServer -u kubeadmin -p $kubeadmin_password

Create an OpenShift secret to store the Azure Active Directory application secret.

oc create secret generic openid-client-secret-azuread \
  --namespace openshift-config \

Create a oidc.yaml file to configure OpenShift OpenID authentication against Azure Active Directory.

cat > oidc.yaml<< EOF
kind: OAuth
  name: cluster
  - name: AAD
    mappingMethod: claim
    type: OpenID
      clientID: $app_id
        name: openid-client-secret-azuread
      - email
      - profile
        include_granted_scopes: "true"
        - email
        - upn
        - name
        - email

Apply the configuration to the cluster.

oc apply -f oidc.yaml

You will get back a response similar to the following. configured

Verify login through Azure Active Directory

If you now logout of the OpenShift Web Console and try to log in again, you'll be presented with a new option to log in with AAD. You may need to wait for a few minutes.

Log in screen with Azure Active Directory option