Set up fleet-level authentication management

Console

1. In the Google Cloud console, go to the GKE Identity Servicepage.

   Go to Feature Manager

2. Click Enable Identity Service.

gcloud

Enable the fleet-level identity service feature:

 gcloud  
container  
fleet  
identity-service  
 enable 
 

Console

1. Select clusters to configure:

   1. In the Google Cloud console, go to the GKE Identity Servicepage.

      Go to Feature Manager

   2. Select one or more checkboxes for the clusters that you want to configure. You can choose individual clusters, or specify that you want all clusters to be configured with the same identity configuration. If you have configured fleet-level defaults , the configuration is reconciled back to the default.

   3. Click Update Configuration. The Edit Identity Service Clusters Configpane opens.

   4. In the Identity Providerssection, choose how you want to configure the clusters. You can update an existing configuration, copy a configuration from a different cluster, or create a new configuration. To create a new configuration, click Add an Identity Provider. The New Identity Providersection appears.

2. In the New Identity Providersection, set the provider details:

   OIDC

   1. Select New Open ID Connectto create a new OIDC configuration.
   2. Specify the name you want to use to identify this configuration in the Provider namefield, typically the identity provider name. This name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen. You cannot edit this name once you've created a configuration.
   3. Specify the client ID from the identity provider in the Client IDfield.
   4. Specify the client secret that must be shared between the client application and the identity provider in the Client Secretfield.
   5. Specify the URI where authorization requests are made to your identity provider in the Issuer URLfield.
   6. Click Nextto set the OIDC attributes.

   Azure AD

   1. Select New Azure Active Directoryto create a new Azure AD configuration.
   2. Specify the name you want to use to identify this configuration in the Provider namefield, typically the identity provider name. This name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen. You cannot edit this name once you've created a configuration.
   3. Specify the client ID from the identity provider in the Client IDfield.
   4. Specify the client secret that must be shared between the client application and the identity provider in the Client Secretfield.
   5. Specify the tenant that is the Azure AD account to be authenticated in the Tenant.
   6. Click Nextto set the Azure AD attributes.

   LDAP

   1. Select LDAPto create a new LDAP configuration.
   2. Specify the name you want to use to identify this configuration in the Provider namefield, typically the identity provider name. This name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen. You cannot edit this name once you've created a configuration.
   3. Click Next.
   4. Specify the hostname (mandatory), LDAP connection type, and base64-encoded CA certificate of the LDAP server.
   5. Click Nextto configure the server.
   6. Specify the user's distinguished name, filter, login attribute, and identifier attribute.
   7. Click Nextto set the user details.
   8. If you choose to use groups, specify the group's distinguished name, filter, and identifier attribute.
   9. Click Nextto set the group details.
   10. Specify the service account username and password.
   11. Click Doneto set the service account name.

3. Click Next. The Set attributessection opens.

4. Set the attributes for your identity provider. To view attributes for OIDC or Azure AD, select one of the following options:

   OIDC

   • kubectl redirect URI: The redirect URL and port used by the gcloud CLI and specified by your platform administrator at registration, typically in the form http: // localhost:PORT/callback .
   • Certificate Authority(Optional): If provided by your platform administrator, a PEM-encoded certificate string for the identity provider.
   • Group Claim(Optional): The JWT claim (field name) that your provider uses to return an account's security groups.
   • Group Prefix(Optional): The prefix you want to prepend to security group names to avoid clashes with existing names in your access control rules if you have configurations for multiple identity providers (typically the provider name).
   • Proxy(Optional): Proxy server address to use to connect to the identity provider, if applicable. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. For example: http://user:password@10.10.10.10:8888 .
   • Scopes(Optional): Any additional scopes required by your identity provider. Microsoft Azure and Okta require the offline_access scope. Click Add scopeto add more scopes if necessary.
   • User Claim(Optional): The JWT claim (field name) that your provider uses to identify an account. If you don't specify a value here, the cluster uses "sub", which is the user ID claim used by many providers. You can choose other claims, such as "email" or "name", depending on the OpenID provider. Claims other than "email" are prefixed with the issuer URL to prevent naming clashes.
   • User Prefix(Optional): The prefix you want prepended to user claims to prevent clashes with existing names, if you don't want to use the default prefix.
   • Extra Params(Optional): Any extra parameters required for your configuration, specified as the parameter Keyand Value. Click Add paramto add more parameters if needed.
   • Enable access token(Optional): If enabled, it allows group support for OIDC providers such as Okta.
   • Deploy Google Cloud console proxy(Optional): If enabled, a proxy is deployed that lets the Google Cloud console connect to an on-premises identity provider that is not publicly accessible over the internet.

   Azure AD

   • kubectl redirect URI: The redirect URL and port used by the gcloud CLI and specified by your platform administrator at registration, typically in the form http: // localhost:PORT/callback .
   • User Claim(Optional): The JWT claim (field name) that your provider uses to identify an account. If you don't specify a value here, the cluster uses a value in the order of "email", "preferred_username", or "sub" to fetch the user details.
   • Proxy(Optional): Proxy server address to use to connect to the identity provider, if applicable. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. For example: http://user:password@10.10.10.10:8888 .

5. Click Done.

6. Optional: To add more providers to the configuration, click Add an identity providerand repeat the preceding steps.

7. Click Update configuration.

This installs any required components if necessary and applies the client configuration on your selected clusters.

gcloud

To use the gcloud CLI to configure the fleet, you create a Kubernetes custom resource named ClientConfig with fields for all of the information that the cluster needs to interact with the identity provider. To create and use a ClientConfig, follow these steps:

1. Create a ClientConfig specification in a file named auth-config.yaml . To view example configurations for OIDC, SAML, or LDAP, select one of the following options. For other identity provider configurations, see Provider-specific configurations .

   OIDC

   The following example ClientConfig shows both an oidc configuration and an azuread configuration. For more information about when to use oidc or azuread , see Provider-specific configurations .

     apiVersion 
    : 
     
    authentication.gke.io/v2alpha1 
    kind 
    : 
     
    ClientConfig 
    metadata 
    : 
     
    name 
    : 
     
    default 
     
    namespace 
    : 
     
    kube-public 
    spec 
    : 
     
    authentication 
    : 
     
    - 
     
    name 
    : 
     
     NAME 
    
     
    proxy 
    : 
     
     PROXY_URL 
    
     
    oidc 
    : 
     
    certificateAuthorityData 
    : 
     
     CERTIFICATE_STRING 
    
     
    clientID 
    : 
     
     CLIENT_ID 
    
     
    clientSecret 
    : 
     
     CLIENT_SECRET 
    
     
    deployCloudConsoleProxy 
    : 
     
     PROXY_BOOLEAN 
    
     
    extraParams 
    : 
     
     EXTRA_PARAMS 
    
     
    groupsClaim 
    : 
     
     GROUPS_CLAIM 
    
     
    groupPrefix 
    : 
     
     GROUP_PREFIX 
    
     
    issuerURI 
    : 
     
     ISSUER_URI 
    
     
    kubectlRedirectURI 
    : 
     
    http://localhost: PORT 
   /callback 
     
    scopes 
    : 
     
     SCOPES 
    
     
    userClaim 
    : 
     
     USER_CLAIM 
    
     
    userPrefix 
    : 
     
     USER_PREFIX 
    
     
    - 
     
    name 
    : 
     
    azure 
     
    azureAD 
    : 
     
    clientID 
    : 
     
     CLIENT_ID 
    
     
    clientSecret 
    : 
     
     CLIENT_SECRET 
    
     
    tenant 
    : 
     
     TENANT_UUID 
    
     
    kubectlRedirectURI 
    : 
     
    http://localhost: PORT 
   /callback 
     
    groupFormat 
    : 
     
     GROUP_FORMAT 
    
     
    userClaim 
    : 
     
     USER_CLAIM 
    
    
   

   For more information about the fields in the oidc object, see ClientConfig OIDC fields .

   SAML

   The following example ClientConfig shows a saml configuration:

      
    apiVersion 
    : 
     
    authentication.gke.io/v2alpha1 
     
    kind 
    : 
     
    ClientConfig 
     
    metadata 
    : 
     
    name 
    : 
     
    default 
     
    namespace 
    : 
     
    kube-public 
     
    spec 
    : 
     
    authentication 
    : 
     
    - 
     
    name 
    : 
     
     NAME 
    
     
    saml 
    : 
     
    idpEntityID 
    : 
     
     ENTITY_ID 
    
     
    idpSingleSignOnURI 
    : 
     
     SIGN_ON_URI 
    
     
    idpCertificateDataList 
    : 
     
     IDP_CA_CERT 
    
     
    userAttribute 
    : 
     
     USER_ATTRIBUTE 
    
     
    groupsAttribute 
    : 
     
     GROUPS_ATTRIBUTE 
    
     
    userPrefix 
    : 
     
     USER_PREFIX 
    
     
    groupPrefix 
    : 
     
     GROUP_PREFIX 
    
     
    attributeMapping 
    : 
     
    ATTRIBUTE_KEY_1 
    : 
     
     ATTRIBUTE_CEL_EXPRESSION_1 
    
     
    ATTRIBUTE_KEY_2 
    : 
     
     ATTRIBUTE_CEL_EXPRESSION_2 
    
     
    certificateAuthorityData 
    : 
     
     CERTIFICATE_STRING 
    
     
    preferredAuthentication 
    : 
     
     PREFERRED_AUTHENTICATION 
    
     
    server 
    : 
     
   <> 
   

   For more information about these fields, see ClientConfig SAML fields .

   LDAP

   The following example ClientConfig shows an ldap configuration:

     apiVersion 
    : 
     
    authentication.gke.io/v2alpha1 
    kind 
    : 
     
    ClientConfig 
    metadata 
    : 
     
    name 
    : 
     
    default 
     
    namespace 
    : 
     
    kube-public 
    spec 
    : 
     
    authentication 
    : 
     
    - 
     
    name 
    : 
     
    ldap 
     
    ldap 
    : 
     
    server 
    : 
     
    host 
    : 
     
     HOST_NAME 
    
     
    connectionType 
    : 
     
     CONNECTION_TYPE 
    
     
    certificateAuthorityData 
    : 
     
     CERTIFICATE_AUTHORITY_DATA 
    
     
    user 
    : 
     
    baseDn 
    : 
     
     BASE_DN 
    
     
    loginAttribute 
    : 
     
     LOGIN_ATTRIBUTE 
    
     
    filter 
    : 
     
     FILTER 
    
     
    identifierAttribute 
    : 
     
     IDENTIFIER_ATTRIBUTE 
    
     
    group 
    : 
     
    baseDn 
    : 
     
     BASE_DN 
    
     
    filter 
    : 
     
     FILTER 
    
     
    identifierAttribute 
    : 
     
     IDENTIFIER_ATTRIBUTE 
    
     
    serviceAccount 
    : 
     
    simpleBindCredentials 
    : 
     
    dn 
    : 
     
     DISTINGUISHED_NAME 
    
     
    password 
    : 
     
     PASSWORD 
    
    
   

   For more information about these fields, see ClientConfig LDAP fields .

   You can add multiple identity provider configurations to the same ClientConfig. The cluster attempts to authenticate with each configuration in the order in which they are defined, and stops after the first successful authentication.

2. Apply the ClientConfig to a cluster:

    gcloud  
   container  
   fleet  
   identity-service  
   apply  
    \ 
     
   --membership = 
    CLUSTER_NAME 
     
    \ 
     
   --config = 
   auth-config.yaml 
   

   Replace CLUSTER_NAME with your cluster's unique name within the fleet.

The cluster installs any required components and uses the ClientConfig that you created. The fleet-level controller manages the configuration for the cluster. Any local changes to the cluster configuration are reconciled by the controller to the fleet-level configuration.

Azure AD

This is the default configuration to set up authentication with Azure AD. Using this configuration lets the cluster get user and group information from Azure AD, and lets you set up Kubernetes role based access control (RBAC) based on groups. However, using this configuration limits you to retrieving approximately 200 groups per user.

If you need to retrieve more than 200 groups per user, see the instructions for Azure AD (Advanced).

  ... 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 oidc-azuread 
  
 oidc 
 : 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 cloudConsoleRedirectURI 
 : 
  
 https://console.cloud.google.com/kubernetes/oidc 
  
 extraParams 
 : 
  
 prompt=consent, access_type=offline 
  
 issuerURI 
 : 
  
 https://login.microsoftonline.com/ TENANT_ID 
/v2.0 
  
 kubectlRedirectURI 
 : 
  
 http://localhost: PORT 
/callback 
  
 scopes 
 : 
  
 openid,email,offline_access 
  
 userClaim 
 : 
  
 email 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 ... 
 

Azure AD (Advanced)

This optional configuration for Azure AD lets the cluster retrieve user and group information with no limit on the number of groups per user, using the Microsoft Graph API. For information on platforms that support this configuration, see Identity provider setup information .

If you need to retrieve fewer than 200 groups per user, we recommend that you use the default configuration using an oidc anchor in your ClientConfig. For more information, see the instructions for Azure AD.

All fields in the example configuration are required.

  ... 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 azure 
  
 azureAD 
 : 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 tenant 
 : 
  
  TENANT_UUID 
 
  
 kubectlRedirectURI 
 : 
  
 http://localhost: PORT 
/callback 
  
 groupFormat 
 : 
  
  GROUP_FORMAT 
 
  
 userClaim 
 : 
  
  USER_CLAIM 
 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 ... 
 

Replace GROUP_FORMAT with the format in which you want to retrieve group information. This field can take values corresponding to ID or NAME of the user groups. This setting is only available for clusters in Google Distributed Cloud (on-premises) deployments.

Okta

The following shows you how to set up authentication using both users and groups with Okta as your identity provider. This config lets the cluster retrieve user and group claims by using an access token and Okta's userinfo endpoint.

  ... 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 okta 
  
 oidc 
 : 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 cloudConsoleRedirectURI 
 : 
  
 https://console.cloud.google.com/kubernetes/oidc 
  
 enableAccessToken 
 : 
  
 true 
  
 extraParams 
 : 
  
 prompt=consent 
  
 groupsClaim 
 : 
  
 groups 
  
 issuerURI 
 : 
  
 https:// OKTA_ISSUER_URI 
/ 
  
 kubectlRedirectURI 
 : 
  
 http://localhost: PORT 
/callback 
  
 scopes 
 : 
  
 offline_access,email,profile,groups 
  
 userClaim 
 : 
  
 email 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 ... 
 

Console

1. In the Google Cloud console, go to the Feature Managerpage.

   Go to Feature Manager

   All enabled features are listed as Enabledin their panel.

2. Click DETAILSin the Identity Servicepanel. A details panel displays the status of your registered clusters.

gcloud

Run the following command:

 gcloud  
container  
fleet  
identity-service  
describe