Authenticating with OIDC

This page is for infrastructure operators.

This page describes how to enable authentication to Anthos Management Center through your choice of OpenID Connect (OIDC provider). OIDC is an authentication layer, built on top of OAuth 2.0, that specifies a RESTful HTTP API, and uses JSON as a data format.

OIDC allows you to use your existing identity provider to manage user and group authentication. With OIDC, you can manage access to a cluster by using the standard procedures in your organization for creating, enabling, and disabling accounts.

Before you begin

Before setting up OIDC, you need the following:

  1. The domain name used to access Management Center, provided by the infrastructure operator, for example: anthos.example.com.
  2. An OIDC provider such as Microsoft Active Directory Federation Services (ADFS), Google SSO, or Keycloak. Both the cluster and your browser must be able to connect to the OIDC provider. The OIDC provider does not have to connect back to the cluster directly. If you don't have an OIDC provider, see Authenticating with Keycloak to install one. Keycloak is for demonstration purposes only and is not recommended for a production environment.

Creating identity profiles

Identity profiles contain the required configuration to use an identity provider for authentication. The following steps create an identity profile:

  1. In Management Center Console, open the Identity and Access menu.

  2. In the Identity tab, click Set Up Anthos Identity Service (OIDC).

  3. Assign a user friendly profile name in the Profile Name field. This is the name the profile is referenced by.

  4. Enter the OIDC Provider URL, Client ID and Client Secret from your OIDC provider.

  5. Set the Username Claim field. The username claim is the claim in the OIDC token that holds the username. For example, if the username claim is email, then users are identified by the user field in the OIDC token.

    When setting this claim, make sure that the claim exists in the requested scopes.

  6. Set the Username Prefix field. The username prefix is used to distinguish between users from different identity providers. The user prefix also needs to be included when assigning RBAC permissions to users.

    For example, if the username claim is email, and the user prefix is prefix-, then users are identified as prefix-sally@example.com. The user is sally@example.com and the prefix, prefix-, is prefixed on the user to distinguish between different identity providers.

  7. Set the Groups Claim field. In Anthos private mode the default is groups. See Role bindings for more on binding groups to roles.

  8. Set the Group Prefix field. The group prefix is used to distinguish between groups from different identity providers. The group prefix must also be included when assigning RBAC permissions to groups.

    For example, if the group claim is groups, and the group prefix is groupprefix-, then groups would be identified as groupprefix-group. The group is group and the prefix, groupprefix-, is prefixed on the group. We recommend inserting a separator at the end of the prefix as described in setting the username prefix in step 6.

  9. (Optional) Set the Scopes field if the scopes aren't openid email profile.

    Scopes are the identifiers used to specify what access privileges to request in the ID token:

    • openid is required for OIDC.
    • profile includes the user's default profile claims.
    • email generally includes the email and email_verified claims.
  10. If the OIDC provider (such as Google SSO) requires additional parameters, set the Extra Parameters field.

    For example, the Extra Parameters field can be set to prompt=consent,access_type=offline to display a consent screen each time before requesting authorization of scopes of access.

  11. If the HTTPS connection to the /.well-known/openid-configuration page or the JWKS page of your OIDC provider are secured by an untrusted certificate (such as a self-signed certificate), you need to fill in the OIDC Provider certificate field with the HTTPS certificate used by your OIDC provider.

    • Encode the PEM-encoded certificate for the OIDC provider into base64. To create the string, encode the certificate, including headers, into base64. Include the resulting string as a single line.

    • Example: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tC...k1JSUN2RENDQWFT==

    • See Authenticating with Keycloak for an example of setting this field.

  12. Click Submit and return to the Identity and Access tab.

  13. Register the callback URL with the OIDC provider.

Create additional identity profiles by clicking Add in the Identity Profile tab.

Applying identity profiles to the admin cluster

Identity profiles must be applied to clusters after they are created.

  1. In the Identity Profile tab, click Apply to clusters.

    Apply Profile to Admin Cluster

  2. Click the Admin Cluster tab. In the Profiles drop-down list, select the profile name for the profile created previously. You can select multiple profiles to apply to the cluster.

    OIDC Profile Page

  3. Verify the domain name for the profile. This is the domain name that is mapped to the identity provider profile. Unauthenticated users who try to access paths on the domain are directed to log in with this identity provider. This domain name is assigned by the infrastructure operator.

    Each profile must be assigned a different domain name if more than one profile is to be applied at a time.

    See Configure domain name to access Management Center for details on configuring a domain name.

  4. Enter an initial username that is granted Platform Admin access rights (e.g., alice@example.com,bob@example.com). The username should be prefixed with the user prefix set in the profile. For example, if the prefix is prefix- then the username in the Initial Platform Admin field should look like prefix-alice@example.com. See more details about platform admins and authorization in Authorization roles.

  5. Apply the settings and wait for several minutes for the configurations to apply and services to restart.

Now you can access Management Center with your domain name. If you are not logged in, you are redirected to your OIDC provider to log in.

Log in with OIDC to the admin cluster Kubernetes API server

Users can download admin-actl-auth-login-config.yaml from the Identity and Access page after OIDC is set up.

  1. On the Identity and Access page, click the Identity tab and then the Cluster tab.

  2. Find the cluster named admin and click View Configuration Details.

  3. Click Download login config to download the configuration that is used to log in with identity to the admin cluster Kubernetes API server.

    AIS config download button

  4. The output file admin-actl-auth-login-config.yaml contains the configuration necessary for users to authenticate with the admin cluster. Share admin-actl-auth-login-config.yaml with trusted users who need access to the cluster.

  5. After acquiring admin-actl-auth-login-config.yaml, users can log in by using the actl auth login command. When users successfully login through a browser, a kubeconfig file is produced. Users can use that new file to access the cluster using their federated credentials:

    # Where to store the new kubeconfig
    export ADMIN_OIDC_KUBECONFIG=$(pwd)/admin-oidc-kubeconfig
    
    actl auth login --login-config=admin-actl-auth-login-config.yaml --cluster=admin \
      --kubeconfig=${ADMIN_OIDC_KUBECONFIG} \
      --preferred-auth="CONFIGURATION_NAME"
    

    Replace CONFIGURATION_NAME with the identity profile name to authenticate with.

  6. Users can now use ${ADMIN_OIDC_KUBECONFIG}to access resources on the admin cluster, for example:

    kubectl get pods -n anthos-management-center --kubeconfig=${ADMIN_OIDC_KUBECONFIG}
    
  7. ${ADMIN_OIDC_KUBECONFIG} can also be used to authenticate actl CLI commands, for example:

    actl platform management-center describe --kubeconfig=${ADMIN_OIDC_KUBECONFIG}
    

Reset authentication config

If a platform administrator loses access to Management Center due to a mistake in the authentication settings, run the following command below to reset OIDC authentication to the original setup, and get the new access URL to Management Center.

actl auth reset --kubeconfig=ADMIN_KUBECONFIG

# Get the new access URL to management center.
actl platform management-center describe --kubeconfig=ADMIN_KUBECONFIG