sigs.k8s.io/cluster-api-provider-azure@v1.14.3/docs/book/src/topics/aad-integration.md (about)

     1  # AAD Integration
     2  
     3  CAPZ can be configured to use Azure Active Directory (AD) for user authentication. In this configuration, you can log into a CAPZ cluster using an Azure AD token. Cluster operators can also configure Kubernetes role-based access control (Kubernetes RBAC) based on a user's identity or directory group membership.
     4  
     5  <aside class="note warning">
     6  
     7  <h1> Warning </h1>
     8  
     9  The following operations to configure Azure AD applications must be completed by an Azure tenant administrator.
    10  
    11  </aside>
    12  
    13  ## Create Azure AD server component
    14  
    15  ### Create the Azure AD application
    16  
    17  ```bash
    18  export CLUSTER_NAME=my-aad-cluster
    19  ```
    20  
    21  ```bash
    22  export AZURE_SERVER_APP_ID=$(az ad app create \
    23      --display-name "${CLUSTER_NAME}Server" \
    24      --identifier-uris "https://${CLUSTER_NAME}Server" \
    25      --query appId -o tsv)
    26  ```
    27  
    28  ### Update the application group membership claims
    29  ```bash
    30  az ad app update --id ${AZURE_SERVER_APP_ID} --set groupMembershipClaims=All
    31  ```
    32  
    33  ### Create a service principal
    34  ```bash
    35  az ad sp create --id ${AZURE_SERVER_APP_ID}
    36  ```
    37  
    38  ## Create Azure AD client component
    39  ```bash
    40  AZURE_CLIENT_APP_ID=$(az ad app create \
    41      --display-name "${CLUSTER_NAME}Client" \
    42      --native-app \
    43      --reply-urls "https://${CLUSTER_NAME}Client" \
    44      --query appId -o tsv)
    45  ```
    46  
    47  ### Create a service principal
    48  ```bash
    49  az ad sp create --id ${AZURE_CLIENT_APP_ID}
    50  ```
    51  
    52  ### Grant the application API permissions
    53  ```bash
    54  oAuthPermissionId=$(az ad app show --id ${AZURE_SERVER_APP_ID} --query "oauth2Permissions[0].id" -o tsv)
    55  az ad app permission add --id ${AZURE_CLIENT_APP_ID} --api ${AZURE_SERVER_APP_ID} --api-permissions ${oAuthPermissionId}=Scope
    56  az ad app permission grant --id ${AZURE_CLIENT_APP_ID} --api ${AZURE_SERVER_APP_ID}
    57  ```
    58  
    59  ## Create the cluster
    60  
    61  To deploy a cluster with support for AAD, use the [aad flavor](https://raw.githubusercontent.com/kubernetes-sigs/cluster-api-provider-azure/main/templates/cluster-template-aad.yaml).
    62  
    63  Make sure that `AZURE_SERVER_APP_ID` is set to the ID of the server AD application created above.
    64  
    65  ### Get the admin kubeconfig
    66  ```bash
    67  clusterctl get kubeconfig ${CLUSTER_NAME} > ./kubeconfig
    68  export KUBECONFIG=./kubeconfig
    69  ```
    70  
    71  ## Create Kubernetes RBAC binding
    72  
    73  Get the user principal name (UPN) for the user currently logged in using the az ad signed-in-user show command. This user account is enabled for Azure AD integration in the next step:
    74  
    75  <aside class="note">
    76  
    77  <h1> Note </h1>
    78  
    79  If the user you grant the Kubernetes RBAC binding for is in the same Azure AD tenant, assign permissions based on the userPrincipalName. If the user is in a different Azure AD tenant, query for and use the objectId property instead.
    80  
    81  </aside>
    82  
    83  ```bash
    84  az ad signed-in-user show --query objectId -o tsv
    85  ```
    86  
    87  Create a YAML manifest `my-azure-ad-binding.yaml`:
    88  
    89  ```yaml
    90  apiVersion: rbac.authorization.k8s.io/v1
    91  kind: ClusterRoleBinding
    92  metadata:
    93    name: my-cluster-admin
    94  roleRef:
    95    apiGroup: rbac.authorization.k8s.io
    96    kind: ClusterRole
    97    name: cluster-admin
    98  subjects:
    99  - apiGroup: rbac.authorization.k8s.io
   100    kind: User
   101    name: your_objectId
   102  ```
   103  
   104  Create the ClusterRoleBinding using the kubectl apply command and specify the filename of your YAML manifest:
   105  
   106  ```bash
   107  kubectl apply -f my-azure-ad-binding.yaml
   108  ```
   109  
   110  ## Accessing the cluster
   111  
   112  ### Install kubelogin
   113  kubelogin is a client-go credential (exec) plugin implementing Azure authentication. Follow the setup instructions [here](https://github.com/Azure/kubelogin/blob/master/README.md).
   114  
   115  ### Set the config user context
   116  ```bash
   117  kubectl config set-credentials ad-user --exec-command kubelogin --exec-api-version=client.authentication.k8s.io/v1beta1 --exec-arg=get-token --exec-arg=--environment --exec-arg=$AZURE_ENVIRONMENT --exec-arg=--server-id --exec-arg=$AZURE_SERVER_APP_ID --exec-arg=--client-id --exec-arg=$AZURE_CLIENT_APP_ID --exec-arg=--tenant-id --exec-arg=$AZURE_TENANT_ID
   118  kubectl config set-context ${CLUSTER_NAME}-ad-user@${CLUSTER_NAME} --user ad-user --cluster ${CLUSTER_NAME}
   119  ```
   120  
   121  To verify it works, run:
   122  
   123  ```bash
   124  kubectl config use-context ${CLUSTER_NAME}-ad-user@${CLUSTER_NAME}
   125  kubectl get pods -A
   126  ```
   127  
   128  You will receive a sign in prompt to authenticate using Azure AD credentials using a web browser. After you've successfully authenticated, the kubectl command should display the pods in the CAPZ cluster.
   129  
   130  ## Adding AAD Groups
   131  
   132  To add a group to the admin role run:
   133  
   134  ```bash
   135  AZURE_GROUP_OID=<Your Group ObjectID>
   136  kubectl create clusterrolebinding aad-group-cluster-admin-binding --clusterrole=cluster-admin --group=${AZURE_GROUP_OID}
   137  ```
   138  
   139  ## Adding users
   140  
   141  To add another user, create a additional role binding for that user:
   142  
   143  ```bash
   144  USER_OID=<Your User ObjectID or UserPrincipalName>
   145  kubectl create clusterrolebinding aad-user-binding --clusterrole=cluster-admin --user ${USER_OID}
   146  ```
   147  
   148  You can update the cluster role bindings to suit your needs for that user or group. See the [default role bindings](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings) for more details, and the [general guide to Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
   149  
   150  ## Known Limitations
   151  
   152  - The user must not be a member of more than 200 groups.