Connect to an identity provider

An identity provider (IdP) is a system entity that creates, maintains, and manages identity information for principals. The IdP also provides authentication services to applications within a federation or distributed network.

Since the Infrastructure Operator (IO) connects its identity provider first, the Platform Administrator (PA) can't access the clusters or dashboards until the IO adds the PA's identity provider. The PA must request their IO add the identity provider by opening a ticket in the ticketing system and providing their identity provider's information:

Number of servers and their types.
Amount of block storage in TB.
Amount of object storage in TB.
Mandatory parameters for OIDC:
- clientID: ID for the client application that makes authentication requests to the OpenID provider.
- clientSecret: secret known only to the application and the OpenID provider.
- issuerURL: URL where authorization requests are sent to your OpenID.
- scopes: additional scopes to send to the OpenID provider.
- userclaim: JSON web token (JWT) claim to use as the username.
- certificateAuthorityData: A base64-encoded PEM-encoded certificate for the OIDC provider.
Mandatory parameters for SAML providers:
- idpCertificateDataList: The IdP certificates to verify the SAML response. These certificates must be standard base64 encoded, and PEM formatted. Only a maximum of two certificates are supported to facilitate IdP certificate rotation.
- idpEntityID: The SAML entity ID for the SAML provider, specified in a URI format. For example: https://www.idp.com/saml.
- idpSingleSignOnURI: The URI to the SSO endpoint of the SAML provider. For example: https://www.idp.com/saml/sso.
Username or group of user names for the initial administrators.

Connect to an existing identity provider

After the initial identity provider is set up and connected to the organization, you can connect additional existing identity providers using the GDC console.

To get the permissions that you need to connect an existing identity provider, ask your Organization IAM Admin to grant you the Organization IAM Admin role. The initial admin that you specify when connecting the identity provider must also have the Organization IAM Admin role assigned.

To connect the identity provider, you must have a single client ID and secret from your identity provider. You can either connect to an existing OIDC or a SAML provider.

Connect to an existing OIDC provider

Sign in to the GDC console. The following example shows the console after signing into an organization called org-1:
In the navigation menu, click Identity and Access > Identity.
Click Setup New Identity Provider.
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.
  
  Note: Distributed Cloud doesn't insert a separator between the prefix and the group name. Insert a separator such as - or : at the end of the prefix to increase readability. Otherwise prefix and kiran@example.com are identified as prefixkiran@example.com.
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.
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.
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 user name, such as myidp-kiran@example.com.
Review your selections and click Setup.

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

Connect to an existing SAML provider

Sign in to the GDC console.
In the navigation menu, click Identity and Access > Identity.
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.
  
  Note: Distributed Cloud doesn't insert a separator between the prefix and the group name. Insert a separator such as - or : at the end of the prefix to increase readability. Otherwise prefix and kiran@example.com are identified as prefixkiran@example.com.
6. 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.
7. 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.
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.
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.
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.