Authenticate to GKE on Azure with external identities

Workforce identity federation grants non-Google identities access toGoogle Cloud services. In the context of GKE on Azure, this means you canuse pre-existing external identities to create or access a GKE clusterwithout relying on Google credentials.

The benefits of using workforce identity federation are the following:

• You eliminate the need for duplicate accounts across different platforms orproviders.
• You set permissions just once, bypassing the need for configurations onmultiple platforms.
• You simplify user access, because fewer logins and passwords are required.

Before you begin

Before you can enable external users or groups to access GKE clusters,you need to perform the following steps:

1. So that external users or groups can use the GKE on Azure API, configureworkforce identity federation.:

   • For Azure users, seeConfigure workforce identity federation with Azure AD.
   • For Okta users, seeConfigure workforce identity federation with Okta.
   • For users from other platforms, seeConfigure workforce identity federation.

2. Assign your external users or groups thegkemulticloud.viewer role so thatthey can access clusters. Assign thecontainer.clusterViewer role to viewclusters in the Google Cloud console.

   Note that roles are collections of permissions. When you assign a role toan entity (user, group, or service account), you're giving that entity allthe permissions that the role contains.

   Users

   For individual users, you need to assign thegkemulticloud.viewer role:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--role="roles/gkemulticloud.viewer"\--member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.
   • WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAMdocumentation underQuery parameters.
   • SUBJECT_VALUE: the ID that uniquely identifies an externaluser. For example, the ID can be an email address such asalex@cymbalgroup.com.

   Groups

   For groups, you need to assign thegkemulticloud.viewer role:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--role="roles/gkemulticloud.viewer"\--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.
   • WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAM documentationunderQuery parameters.
   • GROUP_ID: an ID that uniquely identifies an externalgroup.

3. Optional: Assign your external users or groups the appropriateIdentity and Access Management (IAM) roles. This step is only necessary if you want togrant users or groups the ability to create or update clusters;it's notrequired for simply accessing a cluster.

   Users

   For individual users, you need to assign thegkemulticloud.admin role:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--role="roles/gkemulticloud.admin"\--member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.
   • WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAMdocumentation underQuery parameters.
   • SUBJECT_VALUE: the ID that uniquely identifies an externaluser. For example, the ID can be an email address such asalex@cymbalgroup.com.

   Groups

   For groups, you need to assign thegkemulticloud.admin role:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--role="roles/gkemulticloud.admin"\--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.
   • WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAM documentationunderQuery parameters.
   • GROUP_ID: an ID that uniquely identifies an externalgroup.

For more information about which API roles and permissions are required forGKE on Azure, seeAPI roles and permissions.

Grant external access to GKE clusters

There are two methods of setting up workforce identity federation so thatexternal users or groups can access your GKE clusters.

Method #1 requires you to define an RBAC file and apply it to the cluster. Thismethod offers fine-tuned control over permissions, such as allowingusers read-only access to resources without granting them broader access.

Method #2 requires you to specify access for external identities when creatingor updating a cluster. This method grants full administrative privileges to thespecified users or groups.

Choose the method that best aligns with your desired level of access control:method #1 for more granular permissions, or method #2 for granting full clusteradmin rights.

Method #1: use an RBAC file

The first method of granting external access to GKE clusters involves theuse of an RBAC file. Follow these steps:

1. Define an RBAC YAML file that includes the subjects (users or groups) andthe permissions you want to grant them within the GKE cluster. Here areexample RBAC YAML configurations for individual users and for groups:

   Users

   apiVersion:rbac.authorization.k8s.io/v1kind:ClusterRoleBindingmetadata:name:gateway-cluster-admin-usersubjects:-kind:Username:principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUEroleRef:kind:ClusterRolename:cluster-adminapiGroup:rbac.authorization.k8s.io

   Replace the following:

   • WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAM documentationunderQuery parameters.
   • SUBJECT_VALUE: the ID that uniquely identifies an externaluser. For example, the ID can be an email address such asalex@cymbalgroup.com.

   Groups

   apiVersion:rbac.authorization.k8s.io/v1kind:ClusterRoleBindingmetadata:name:gateway-cluster-admin-groupsubjects:-kind:Groupname:principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_IDroleRef:kind:ClusterRolename:cluster-adminapiGroup:rbac.authorization.k8s.io

   Replace the following:

   • WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAM documentationunderQuery parameters.
   • GROUP_ID: an ID that uniquely identifies an externalgroup.

2. Identify the GKE cluster you want to configure and set it as the activecontext using the following command:

   kubectlconfiguse-contextCLUSTER_CONTEXT

   ReplaceCLUSTER_CONTEXT with theappropriate context name for your cluster.

3. With the desired GKE cluster set as the active context, apply the RBACconfiguration to the cluster using the following command:

   kubectlapply-fRBAC_PATH

   ReplaceRBAC_PATH with the path to the RBAC file youcreated or edited.

   When you run this command, the specified users or groups inthe RBAC configuration now have the permissions to access and manage thetargeted GKE cluster, as defined in the RBAC rules.

4. If you need to make any subsequent changes to the permissions, modify theRBAC file and reapply it to the cluster by repeating the precedingsteps.

Method #2: give access to external identities during cluster creation or update

Method #2 grants access to external identities during the cluster creation orupdate process.

To create a cluster, follow the steps inCreate a cluster.To update a cluster, follow the steps inUpdate a cluster.

When running thegcloud command to create or update a cluster, specify theadmin-users and/oradmin-groups parameters as follows:

gcloudcontainerazureclusters[create|update]CLUSTER_NAME\--location=LOCATION--admin-users=principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subjectSUBJECT_VALUE\--admin-groups=principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• LOCATION: the Google Cloud region where your clusteris managed.
• WORKFORCE_POOL_ID: the ID that uniquely identifies yourworkforce identity poolin Google Cloud. When formatting the ID, ensure thatyou follow the recommended guidelines provided in the IAM documentationunderQuery parameters.
• SUBJECT_VALUE: the ID that uniquely identifies an externaluser. For example, the ID can be an email address such asalex@cymbalgroup.com.
• GROUP_ID: an ID that uniquely identifies an externalgroup.

Summary of granting external IDs access to GKE clusters

After performing either method #1 or method #2, the specified external users orgroups canuse Google Cloud consoleto connect and view cluster details. Alternatively, they canusekubectl with identity from the gcloud CLIto manage, manipulate, and communicate with the cluster.

To executekubectl commands against GKE clusters, seehow togenerate akubeconfig entry.