Connect to an identity provider

Stay organized with collections Save and categorize content based on your preferences.

Console

1. Sign in to the GDC console. The following example shows the console after signing into an organization called org-1:
2. In the navigation menu, click Identity and Access > Identity.

3. Click Setup New Identity Provider.

4. In the Configure identity provider section, complete the following steps and click Next:

   1. In the Identity provider dropdown menu, select Open ID Connect (OIDC).
   2. Enter an Identity provider name.
   3. In the Google Distributed Cloud URL field, enter the URL you use to access GDC.
   4. In the Issuer URI field, enter the URL where authorization requests are sent to your identity provider. The Kubernetes API server uses this URL to discover public keys for verifying tokens. The URL must use HTTPS.
   5. In the Client ID field, enter the ID for the client application that makes authentication requests to the identity provider.
   6. In the Client secret section, select Configure client secret (Recommended).
      1. In the Client secret field, enter the client secret, which is a shared secret between your identity provider and Distributed Cloud.

   7. Optional: In the Prefix field, enter a prefix. The prefix is added to the beginning of user claims and group claims. Prefixes are used to distinguish between different identity provider configurations. For example, if you set a prefix of myidp, a user claim might be myidpusername@example.com and a group claim might be myidpgroup@example.com. The prefix must also be included when assigning role-based access control (RBAC) permissions to groups.

   8. Optional: In the Encryption section, select Enable encrypted tokens.

      To enable encryption tokens, you must have the IdP Federation Admin role. Ask your Organization IAM Admin to grant you the IdP Federation Admin (idp-federation-admin) role.

      1. In the Key ID field, enter your key ID. The key ID is a public key of a JSON web encryption token (JWT). Your OIDC provider sets up and provisions a key ID.
      2. In the Decryption key field, enter the decryption key in PEM format. The decryption key is an asymmetric key that decrypts an encryption. Your OIDC provider sets up and provisions a decryption key.

5. In the Configure attributes section, complete the following steps and click Next:

   1. In the Certificate authority for OIDC provider field, enter a base64-encoded PEM-encoded certificate for the identity provider. For more information, see https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail.
      1. To create the string, encode the certificate, including headers, into base64.
      2. Include the resulting string in as a single line. Example: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tC...k1JSUN2RENDQWFT==
   2. In the Group claim field, enter the name of the claim in the identity provider token that holds the user's group information.
   3. In the User claim field, enter the claim to identify each user. The default claim for many providers is sub. You can choose other claims, such as email or name, depending on the identity provider. Claims other than email are prefixed with the issuer URL to prevent naming clashes.
   4. Optional: In the Custom attributes section, click Add and enter key-value pairs for additional claims about a user, such as their department or profile picture URL.
   5. If your identity provider requires additional scopes, in the Scopes field, enter the comma-separated scopes to send to the identity provider.
   6. In the Extra parameters section, enter any additional key-value pairs (comma-separated) required by your identity provider. If you are authorizing a group, pass in resource=token-groups-claim.

6. In the Specify initial admins section, complete the following steps and click Next:

   1. Choose whether to add individual users or groups as initial administrators.
   2. In the Username or group alias field, enter the user or group email address to access the organization. If you are the administrator, enter your email address for example kiran@example.com. The prefix is added before the username, such as myidp-kiran@example.com.

7. Review your selections and click Setup.

The new identity provider profile is available in the Identity profiles list.

API

To connect your identity provider to your organization, create the global IdentityProviderConfig custom resource.

1. Create an IdentityProviderConfig custom resource YAML file, such as pa-idp-oidc.yaml:

   apiVersion: iam.global.gdc.goog/v1
   kind: IdentityProviderConfig
   metadata:
     name: pa-idp-oidc
     namespace: platform
   spec:
     oidc:
       certificateAuthorityData: "IDP_BASE64_ENCODED_CERTIFICATE"
       clientID: IDP_CLIENT_ID
       clientSecret: IDP_CLIENT_SECRET
       groupPrefix: IDP_GROUP_PREFIX
       groupsClaim: IDP_GROUP_CLAIM
       issuerURI: IDP_ISSUER_URI
       scopes: openid email profile
       userClaim: IDP_USER_CLAIM
       userPrefix: IDP_USER_PREFIX
   

   Replace the following variables:

   • IDP_BASE64_ENCODED_CERTIFICATE: the base64-encoded certificate for the IdP.
   • IDP_CLIENT_ID: the client ID for the IdP.
   • IDP_CLIENT_SECRET: the client secret for the IdP.
   • IDP_GROUP_PREFIX: the prefix for groups in the IdP.
   • IDP_GROUP_CLAIM: the name of the claim in the IdP token that groups information.
   • IDP_ISSUER_URI: the issuer URI for the IdP.
   • IDP_USER_CLAIM: the name of the claim in the IdP token for the user.
   • IDP_USER_PREFIX: the prefix for the user IdP.

2. Apply the IdentityProviderConfig custom resource to the global API server:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f pa-idp-oidc.yaml
   

   Replace the GLOBAL_API_SERVER_KUBECONFIG variable with the path to the kubeconfig file for the global API server.

Console

1. Sign in to the GDC console.
2. In the navigation menu, click Identity and Access > Identity.

3. In the Configure identity provider section, complete the following steps and click Next:

   1. In the Identity provider drop-down menu, select Security Assertion Markup Language (SAML).
   2. Enter an Identity provider name.
   3. In the Identity ID field, enter the ID for the client application that makes authentication requests to the identity provider.
   4. In the SSO URI field, enter the URL to the single sign on endpoint of the provider. For example: https://www.idp.com/saml/sso.

   5. In the Identity provider prefix field, enter a prefix. The prefix is added to the beginning of user and group claims. Prefixes distinguish between different identity provider configurations. For example: If you set a prefix of myidp, a user claim might show as myidpusername@example.com and a group claim might show as myidpgroup@example.com. You must also include the prefix when assigning RBAC permissions to groups.

   6. For enhanced security, configure your SAML provider to issue assertions with a lifespan of 5 to 10 minutes. This setting is configurable within your SAML provider's settings.

   7. Optional: In the SAML Assertions section, select Enable encrypted SAML assertions.

      To enable encrypted SAML assertions, you must have the IdP Federation Admin role. Ask your Organization IAM Admin to grant you the IdP Federation Admin (idp-federation-admin) role.

      1. In the Encryption certificate field, enter your encryption certificate in PEM format. You receive your encryption certificate after generating the SAML provider.
      2. In the Decryption key field, enter your decryption key. You receive your decryption key after generating the SAML provider.

   8. Optional: In the SAML Signed requests section, check Enable signed SAML requests.

      1. In the Signing certificate field, enter your signing certificate in the PEM file format. Your SAML provider sets up and produces you a signing certificate.
      2. In the Signing key field, enter your signing key in the PEM file format. Your SAML provider sets up and produces you a signing key.

4. In the Configure attributes page, complete the following steps and click Next:

   1. In the IDP certificate field, enter a base64-encoded PEM-encoded certificate for the identity provider. For more information, see https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail.
      1. To create the string, encode the certificate, including headers, into base64.
      2. Include the resulting string in as a single line. For example: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tC...k1JSUN2RENDQWFT==.
   2. Enter any additional certificates in the field Additional IDP certificate.
   3. In the User attribute field, enter the attribute to identify each user. The default attribute for many providers is sub. You can choose other attributes, such as email or name, depending on the identity provider. Attributes other than email are prefixed with the issuer URL to prevent naming clashes.
   4. In the Group attribute field, enter the name of the attribute in the identity provider token that holds the user's group information.
   5. Optional: In the Attribute mapping area, click Add and enter key-value pairs for additional attributes about a user, such as their department or profile picture URL.

5. In the Specify initial admins section, complete the following steps and click Next:

   1. Choose whether to add individual users or groups as initial administrators.
   2. In the Username field, enter the user or group email address to access the organization. If you are the administrator, enter your email address for example kiran@example.com. The prefix is added before the user name, such as myidp-kiran@example.com.

6. In the Review page, check all the values of each identity configuration before continuing. Click Back to return to the previous pages and make necessary corrections. When you've configured all values to your specification, click Setup.

API

To connect your identity provider to your organization, create the global IdentityProviderConfig custom resource.

1. Create an IdentityProviderConfig custom resource YAML file, such as pa-idp-saml.yaml:

   apiVersion: iam.global.gdc.goog/v1
   kind: IdentityProviderConfig
   metadata:
     name: pa-idp-saml
     namespace: platform
   spec:
     saml:
       groupPrefix: IDP_GROUP_PREFIX
       groupsAttribute: IDP_GROUP_ATTRIBUTE
       idpCertificateDataList:
       - "IDP_BASE64_ENCODED_CERTIFICATE"
       idpEntityID: IDP_SAML_ENTITY_ID
       idpSingleSignOnURI: IDP_SAML_SSO_URI
       userAttribute: IDP_USER_ATTRIBUTE
       userPrefix: IDP_USER_PREFIX
   

   Replace the following variables:

   • IDP_GROUP_PREFIX: the prefix for groups in the IdP.
   • IDP_GROUP_ATTRIBUTE: the attribute for groups in the IdP.
   • IDP_BASE64_ENCODED_CERTIFICATE: the base64-encoded certificate for the IdP.
   • IDP_SAML_ENTITY_ID: the URL or URI for uniquely identifying the IdP.
   • IDP_SAML_SSO_URI: the issuer URI for the IdP.
   • IDP_USER_ATTRIBUTE: the attribute for the IdP user, such as an email.
   • IDP_USER_PREFIX: the name of the claim in the IdP token for the user.

2. Apply the IdentityProviderConfig custom resource to the global API server:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f pa-idp-saml.yaml
   

   Replace the GLOBAL_API_SERVER_KUBECONFIG variable with the path to the kubeconfig file for the global API server.