Configure Microsoft Entra 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.30.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 Microsoft Entra 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.

resource_group=<resource_group>
aro_cluster=<aro_cluster>

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

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. contoso.com.

  oauthCallbackURL=https://oauth-openshift.apps.$domain/oauth2callback/AAD
  

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

  oauthCallbackURL=https://oauth-openshift.apps.$domain.$location.aroapp.io/oauth2callback/AAD
  

Create a Microsoft Entra application for authentication

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

client_secret=<client_secret>

Create a Microsoft Entra 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 Microsoft Entra 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 Microsoft Entra ID 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 Microsoft Entra ID.

Create a manifest.json file to configure the Microsoft Entra application.

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

Update the Microsoft Entra application's optionalClaims with a manifest

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

Update the Microsoft Entra application scope permissions

To be able to read the user information from Microsoft Entra ID, 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

Assign users and groups to the cluster (optional)

Applications registered in a Microsoft Entra tenant are, by default, available to all users of the tenant who authenticate successfully. Microsoft Entra ID 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 Microsoft Entra 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 Microsoft Entra application secret.

oc create secret generic openid-client-secret-azuread \
  --namespace openshift-config \
  --from-literal=clientSecret=$client_secret

Create a oidc.yaml file to configure OpenShift OpenID authentication against Microsoft Entra ID.

cat > oidc.yaml<< EOF
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: AAD
    mappingMethod: claim
    type: OpenID
    openID:
      clientID: $app_id
      clientSecret:
        name: openid-client-secret-azuread
      extraScopes:
      - email
      - profile
      extraAuthorizeParameters:
        include_granted_scopes: "true"
      claims:
        preferredUsername:
        - email
        - upn
        name:
        - name
        email:
        - email
      issuer: https://login.microsoftonline.com/$tenant_id
EOF

Apply the configuration to the cluster.

oc apply -f oidc.yaml

You will get back a response similar to the following.

oauth.config.openshift.io/cluster configured

Verify login through Microsoft Entra ID

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 Microsoft Entra ID. You may need to wait for a few minutes.