Configure external identity providers with AKS structured authentication (preview)

Set up GitHub Actions OIDC authentication

1. Ensure your GitHub Actions workflows have the necessary permissions.

2. Configure the id-token: write permission in your workflow files. For example:

   permissions:
     id-token: write
     contents: read
   

3. Set up appropriate repository and organization settings for OIDC token access. Configure repository OIDC settings and organization security policies for token usage.

Set up Google Identity OAuth 2.0 authentication

1. Navigate to the Google Cloud Console.
2. Create or select a project.
3. Create OAuth 2.0 credentials.
4. Note your client ID and client secret for later use.

Create JWT authenticator configuration for GitHub Actions OIDC

• Create a file named jwt-config.json with the following configuration:

  {
    "issuer": {
        "url": "https://token.actions.githubusercontent.com",
        "audiences": [
            "my-api"
        ]
    },
    "claimValidationRules": [
        {
            "expression": "has(claims.sub)",
            "message": "must have sub claim"
        }
    ],
    "claimMappings": {
        "username": {
            "expression": "'aks:jwt:github:' + claims.sub"
        }
    },
    "userValidationRules": [
        {
            "expression": "has(user.username)",
            "message": "must have username"
        },
        {
            "expression": "!user.username.startsWith('aks:jwt:github:system')",
            "message": "username must not start with 'aks:jwt:github:system'"
        }
    ]
  }
  

Create JWT authenticator configuration for Google Identity

• Create a file named jwt-config.json with the following configuration:

  {
      "issuer": {
          "url": "https://accounts.google.com",
          "audiences": [
              "your-client-id.apps.googleusercontent.com"
          ]
      },
      "claimValidationRules": [
          {
              "expression": "has(claims.sub)",
              "message": "must have sub claim"
          }
      ],
      "claimMappings": {
          "username": {
              "expression": "'aks:jwt:google:' + claims.sub"
          },
          "groups": {
              "expression": "has(claims.groups) ? claims.groups.split(',').map(g, 'aks:jwt:' + g) : []"
          }
      },
      "userValidationRules": [
          {
              "expression": "has(user.username)",
              "message": "must have username"
          },
          {
              "expression": "!user.username.startsWith('aks:jwt:google:system')",
              "message": "username must not start with 'aks:jwt:google:system'"
          }
      ]
  }
  

Set up GitHub Actions OIDC for authentication

1. Create environment variables for and set the following required repository secrets in your GitHub repository:

   • AKS_SERVER_URL: Your AKS cluster's API server URL.
   • AKS_CA_DATA: Base64-encoded certificate authority data for your AKS cluster.

2. Create a workflow that obtains an OIDC token and uses it to authenticate with your AKS cluster. The following example workflow gets all pods running on the cluster:

   Note

   The audience value my-api should match the audience configured in your JWT authenticator configuration.

   name: AKS Access with GitHub OIDC
   on:
     workflow_dispatch:
     push:
       branches: [main]
   
   permissions:
     id-token: write
     contents: read
   
   jobs:
     aks-access:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v4
   
         - name: Install kubectl
           uses: azure/setup-kubectl@v3
           with:
             version: 'latest'
   
         - name: Get GitHub OIDC token
           id: get_token
           run: |
             TOKEN=$(curl -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
               "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=my-api" | \
               jq -r '.value')
             echo "::add-mask::$TOKEN"
             echo "oidc_token=$TOKEN" >> $GITHUB_OUTPUT
   
         - name: Create kubeconfig with OIDC token
           run: |
             cat <<EOF > kubeconfig
             apiVersion: v1
             kind: Config
             clusters:
             - cluster:
                 certificate-authority-data: ${{ secrets.AKS_CA_DATA }}
                 server: ${{ secrets.AKS_SERVER_URL }}
               name: aks-cluster
             contexts:
             - context:
                 cluster: aks-cluster
                 user: github-oidc-user
               name: aks-context
             current-context: aks-context
             users:
             - name: github-oidc-user
               user:
                 token: ${{ steps.get_token.outputs.oidc_token }}
             EOF
   
         - name: List all pods in the cluster
           run: |
             export KUBECONFIG=./kubeconfig
             kubectl get pods --all-namespaces
   

Get cluster information for JWT authenticator configuration

1. Get the API server URL for your cluster using the az aks show command.

   az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --query "fqdn" -o tsv | \
     awk '{print "https://" $0 ":443"}'
   

2. Get the base64-encoded certificate authority data for your cluster using the az aks get-credentials command.

   # Get CA data (base64 encoded)
   az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --file - --format exec | \
     grep certificate-authority-data | awk '{print $2}'
   

Set up Google Identity OAuth 2.0 for authentication

You can set up Google Identity authentication using either the kubelogin plugin or by directly using a static token.

1. Trigger the workflow either by pushing to the main branch or manually triggering it from the Actions tab in your repository.

2. Monitor the workflow execution in the Actions tab to verify authentication is working.

   Expected output for first-time setup before Role-Based Access Control (RBAC) configuration:

   Error from server (Forbidden): nodes is forbidden: User "aks:jwt:github:your-sub" cannot list resource "nodes" in API group "" at the cluster scope
   

   This error indicates successful authentication but lack of authorization.

• Test the authentication using the kubectl get nodes command with the --user flag to specify the user context you created for Google Identity authentication. For example:

  kubectl get nodes --user external-user
  

  Expected output for first-time setup before Role-Based Access Control (RBAC) configuration:

  Error from server (Forbidden): nodes is forbidden: User "aks:jwt:google:your-subject" cannot list resource "nodes" in API group "" at the cluster scope
  

  This error indicates successful authentication but lack of authorization.

1. Create a file named rbac-config.yaml to configure RBAC bindings for external users. For example:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: external-user-role
   rules:
   - apiGroups: [""]
     resources: ["pods", "services", "nodes"]
     verbs: ["get", "list"]
   - apiGroups: ["apps"]
     resources: ["deployments", "replicasets"]
     verbs: ["get", "list"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: external-user-binding
   subjects:
   - kind: User
     # This matches the username expression in claim mappings for GitHub; example of GitHub subject is "repo:<organization-name>/<repository-name>:ref:refs/heads/main"
     name: aks:jwt:github:your-github-sub
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: external-user-role
     apiGroup: rbac.authorization.k8s.io
   

2. Apply the RBAC configuration using the kubectl apply command:

   kubectl apply -f rbac-config.yaml
   

1. Create a file named rbac-config.yaml to configure RBAC bindings for external users. For example:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: external-user-role
   rules:
   - apiGroups: [""]
     resources: ["pods", "services", "nodes"]
     verbs: ["get", "list"]
   - apiGroups: ["apps"]
     resources: ["deployments", "replicasets"]
     verbs: ["get", "list"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: external-user-binding
   subjects:
   - kind: User
     # This matches the username expression in claim mappings for Google
     name: aks:jwt:google:your-subject-claim
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: external-user-role
     apiGroup: rbac.authorization.k8s.io
   

2. Apply the RBAC configuration using the kubectl apply command:

   kubectl apply -f rbac-config.yaml