After your OpenShift Dedicated cluster is created, you must configure identity providers to determine how users log in to access the cluster.

Understanding identity providers

OpenShift Dedicated includes a built-in OAuth server. Developers and administrators obtain OAuth access tokens to authenticate themselves to the API. As an administrator, you can configure OAuth to specify an identity provider after you install your cluster. Configuring identity providers allows users to log in and access the cluster.

Supported identity providers

You can configure the following types of identity providers:

Identity provider Description

GitHub or GitHub Enterprise

Configure a github identity provider to validate usernames and passwords against GitHub or GitHub Enterprise’s OAuth authentication server.

GitLab

Configure a gitlab identity provider to use GitLab.com or any other GitLab instance as an identity provider.

Google

Configure a google identity provider using Google’s OpenID Connect integration.

LDAP

Configure the ldap identity provider to validate usernames and passwords against an LDAPv3 server, using simple bind authentication.

OpenID Connect

Configure an oidc identity provider to integrate with an OpenID Connect identity provider using an Authorization Code Flow.

HTPasswd

Configure an htpasswd identity provider for a single, static administration user. You can log in to the cluster as the user to troubleshoot issues.

Identity provider parameters

The following parameters are common to all identity providers:

Parameter Description

name

The provider name is prefixed to provider user names to form an identity name.

mappingMethod

Defines how new identities are mapped to users when they log in. Enter one of the following values:

claim

The default value. Provisions a user with the identity’s preferred user name. Fails if a user with that user name is already mapped to another identity.

lookup

Looks up an existing identity, user identity mapping, and user, but does not automatically provision users or identities. This allows cluster administrators to set up identities and users manually, or using an external process. Using this method requires you to manually provision users.

generate

Provisions a user with the identity’s preferred user name. If a user with the preferred user name is already mapped to an existing identity, a unique user name is generated. For example, myuser2. This method should not be used in combination with external processes that require exact matches between OpenShift Dedicated user names and identity provider user names, such as LDAP group sync.

add

Provisions a user with the identity’s preferred user name. If a user with that user name already exists, the identity is mapped to the existing user, adding to any existing identity mappings for the user. Required when multiple identity providers are configured that identify the same set of users and map to the same user names.

When adding or changing identity providers, you can map identities from the new provider to existing users by setting the mappingMethod parameter to add.

Configuring a GitHub identity provider

Configure a GitHub identity provider to validate user names and passwords against GitHub or GitHub Enterprise’s OAuth authentication server and access your OpenShift Dedicated cluster. OAuth facilitates a token exchange flow between OpenShift Dedicated and GitHub or GitHub Enterprise.

Configuring GitHub authentication allows users to log in to OpenShift Dedicated with their GitHub credentials. To prevent anyone with any GitHub user ID from logging in to your OpenShift Dedicated cluster, you must restrict access to only those in specific GitHub organizations or teams.

Prerequisites
Procedure
  1. From OpenShift Cluster Manager (OCM), navigate to the Clusters page and select the cluster that you need to configure identity providers for.

  2. Click the Access control tab.

  3. Click Add identity provider.

    You can also click the Add Oauth configuration link in the warning message displayed after cluster creation to configure your identity providers.

  4. Select GitHub from the drop-down menu.

  5. Enter a unique name for the identity provider. This name cannot be changed later.

    • An OAuth callback URL is automatically generated in the provided field. You will use this to register the GitHub application.

      https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>

      For example:

      https://oauth-openshift.apps.example-openshift-cluster.com/oauth2callback/github/
  6. Register an application on GitHub.

  7. Return to OpenShift Dedicated and select a mapping method from the drop-down menu. Claim is recommended in most cases.

  8. Enter the Client ID and Client secret provided by GitHub.

  9. Enter a hostname. A hostname must be entered when using a hosted instance of GitHub Enterprise.

  10. Optional: You can use a certificate authority (CA) file to validate server certificates for the configured GitHub Enterprise URL. Click Browse to locate and attach a CA file to the identity provider.

  11. Select Use organizations or Use teams to restrict access to a particular GitHub organization or a GitHub team.

  12. Enter the name of the organization or team you would like to restrict access to. Click Add more to specify multiple organizations or teams that users can be a member of.

  13. Click Confirm.

Verification
  • The configured identity provider is now visible on the Access control tab of the Clusters page.

Configuring a GitLab identity provider

Configure a GitLab identity provider to use GitLab.com or any other GitLab instance as an identity provider.

Prerequisites
  • If you use GitLab version 7.7.0 to 11.0, you connect using the OAuth integration. If you use GitLab version 11.1 or later, you can use OpenID Connect (OIDC) to connect instead of OAuth.

Procedure
  1. From OpenShift Cluster Manager (OCM), navigate to the Clusters page and select the cluster that you need to configure identity providers for.

  2. Click the Access control tab.

  3. Click Add identity provider.

    You can also click the Add Oauth configuration link in the warning message displayed after cluster creation to configure your identity providers.

  4. Select GitLab from the drop-down menu.

  5. Enter a unique name for the identity provider. This name cannot be changed later.

    • An OAuth callback URL is automatically generated in the provided field. You will provide this URL to GitLab.

      https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>

      For example:

      https://oauth-openshift.apps.example-openshift-cluster.com/oauth2callback/gitlab/
  6. Add a new application in GitLab.

  7. Return to OpenShift Dedicated and select a mapping method from the drop-down menu. Claim is recommended in most cases.

  8. Enter the Client ID and Client secret provided by GitLab.

  9. Enter the URL of your GitLab provider.

  10. Optional: You can use a certificate authority (CA) file to validate server certificates for the configured GitLab URL. Click Browse to locate and attach a CA file to the identity provider.

  11. Click Confirm.

Verification
  • The configured identity provider is now visible on the Access control tab of the Clusters page.

Configuring a Google identity provider

Configure a Google identity provider to allow users to authenticate with their Google credentials.

Using Google as an identity provider allows any Google user to authenticate to your server. You can limit authentication to members of a specific hosted domain with the hostedDomain configuration attribute.

Procedure
  1. From OpenShift Cluster Manager (OCM), navigate to the Clusters page and select the cluster that you need to configure identity providers for.

  2. Click the Access control tab.

  3. Click Add identity provider.

    You can also click the Add Oauth configuration link in the warning message displayed after cluster creation to configure your identity providers.

  4. Select Google from the drop-down menu.

  5. Enter a unique name for the identity provider. This name cannot be changed later.

    • An OAuth callback URL is automatically generated in the provided field. You will provide this URL to Google.

      https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>

      For example:

      https://oauth-openshift.apps.example-openshift-cluster.com/oauth2callback/github/
  6. Configure a Google identity provider using Google’s OpenID Connect integration.

  7. Return to OpenShift Dedicated and select a mapping method from the drop-down menu. Claim is recommended in most cases.

  8. Enter the Client ID of a registered Google project and the Client secret issued by Google.

  9. Enter a hosted domain to restrict users to a Google Apps domain.

  10. Click Confirm.

Verification
  • The configured identity provider is now visible on the Access control tab of the Clusters page.

Configuring a LDAP identity provider

Configure the LDAP identity provider to validate user names and passwords against an LDAPv3 server, using simple bind authentication.

Prerequisites
  • When configuring a LDAP identity provider, you will need to enter a configured LDAP URL. The configured URL is an RFC 2255 URL, which specifies the LDAP host and search parameters to use. The syntax of the URL is:

    ldap://host:port/basedn?attribute?scope?filter
    URL component Description

    ldap

    For regular LDAP, use the string ldap. For secure LDAP (LDAPS), use ldaps instead.

    host:port

    The name and port of the LDAP server. Defaults to localhost:389 for ldap and localhost:636 for LDAPS.

    basedn

    The DN of the branch of the directory where all searches should start from. At the very least, this must be the top of your directory tree, but it could also specify a subtree in the directory.

    attribute

    The attribute to search for. Although RFC 2255 allows a comma-separated list of attributes, only the first attribute will be used, no matter how many are provided. If no attributes are provided, the default is to use uid. It is recommended to choose an attribute that will be unique across all entries in the subtree you will be using.

    scope

    The scope of the search. Can be either one or sub. If the scope is not provided, the default is to use a scope of sub.

    filter

    A valid LDAP search filter. If not provided, defaults to (objectClass=*)

    When doing searches, the attribute, filter, and provided user name are combined to create a search filter that looks like:

    (&(<filter>)(<attribute>=<username>))
    If the LDAP directory requires authentication to search, specify a bindDN and bindPassword to use to perform the entry search.
Procedure
  1. From OpenShift Cluster Manager (OCM), navigate to the Clusters page and select the cluster that you need to configure identity providers for.

  2. Click the Access control tab.

  3. Click Add identity provider.

    You can also click the Add Oauth configuration link in the warning message displayed after cluster creation to configure your identity providers.

  4. Select LDAP from the drop-down menu.

  5. Enter a unique name for the identity provider. This name cannot be changed later.

  6. Select a mapping method from the drop-down menu. Claim is recommended in most cases.

  7. Enter a LDAP URL to specify the LDAP search parameters to use.

  8. Optional: Enter a Bind DN and Bind password.

  9. Enter the attributes that will map LDAP attributes to identities.

    • Enter an ID attribute whose value should be used as the user ID. Click Add more to add multiple ID attributes.

    • Optional: Enter a Preferred username attribute whose value should be used as the display name. Click Add more to add multiple preferred username attributes.

    • Optional: Enter an Email attribute whose value should be used as the email address. Click Add more to add multiple email attributes.

  10. Optional: Click Show advanced Options to add a certificate authority (CA) file to your LDAP identity provider to validate server certificates for the configured URL. Click Browse to locate and attach a CA file to the identity provider.

  11. Optional: Under the advanced options, you can choose to make the LDAP provider Insecure. If you select this option, a CA file cannot be used.

    If you are using an insecure LDAP connection (ldap:// or port 389), then you must check the Insecure option in the configuration wizard.

  12. Click Confirm.

Verification
  • The configured identity provider is now visible on the Access control tab of the Clusters page.

Configuring an OpenID identity provider

Configure an OpenID identity provider to integrate with an OpenID Connect identity provider using an Authorization Code Flow.

The Authentication Operator in OpenShift Dedicated requires that the configured OpenID Connect identity provider implements the OpenID Connect Discovery specification.

Claims are read from the JWT id_token returned from the OpenID identity provider and, if specified, from the JSON returned by the Issuer URL.

At least one claim must be configured to use as the user’s identity.

You can also indicate which claims to use as the user’s preferred user name, display name, and email address. If multiple claims are specified, the first one with a non-empty value is used. The standard claims are:

Claim Description

preferred_username

The preferred user name when provisioning a user. A shorthand name that the user wants to be referred to as, such as janedoe. Typically a value that corresponding to the user’s login or username in the authentication system, such as username or email.

email

Email address.

name

Display name.

See the OpenID claims documentation for more information.

Prerequisites
  • Before you configure OpenID Connect, check the installation prerequisites for any Red Hat product or service you want to use with your OpenShift Dedicated cluster.

Procedure
  1. From OpenShift Cluster Manager (OCM), navigate to the Clusters page and select the cluster that you need to configure identity providers for.

  2. Click the Access control tab.

  3. Click Add identity provider.

    You can also click the Add Oauth configuration link in the warning message displayed after cluster creation to configure your identity providers.

  4. Select OpenID from the drop-down menu.

  5. Enter a unique name for the identity provider. This name cannot be changed later.

    • An OAuth callback URL is automatically generated in the provided field.

      https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>

      For example:

      https://oauth-openshift.apps.example-openshift-cluster.com/oauth2callback/openid/
  6. Create an authorization request using an Authorization Code Flow.

  7. Return to OpenShift Dedicated and select a mapping method from the drop-down menu. Claim is recommended in most cases.

  8. Enter a Client ID and Client secret provided from OpenID.

  9. Enter an Issuer URL. This is the URL that the OpenID provider asserts as the Issuer Identifier. It must use the https scheme with no URL query parameters or fragments.

  10. Enter an Email attribute whose value should be used as the email address. Click Add more to add multiple email attributes.

  11. Enter a Name attribute whose value should be used as the preferred username. Click Add more to add multiple preferred usernames.

  12. Enter a Preferred username attribute whose value should be used as the display name. Click Add more to add multiple display names.

  13. Optional: Click Show advanced Options to add a certificate authority (CA) file to your OpenID identity provider.

  14. Optional: Under the advanced options, you can add Additional scopes. By default, the OpenID scope is requested.

  15. Click Confirm.

Verification
  • The configured identity provider is now visible on the Access control tab of the Clusters page.

Configuring an HTPasswd identity provider

Configure an HTPasswd identity provider to create a single, static user with cluster administration privileges. You can log in to your cluster as the user to troubleshoot issues.

Procedure
  1. From OpenShift Cluster Manager (OCM), navigate to the Clusters page and select the cluster that you need to configure identity providers for.

  2. Click the Access control tab.

  3. Click Add identity provider.

    You can also click the Add Oauth configuration link in the warning message displayed after cluster creation to configure your identity providers.

  4. Select HTPasswd from the Identity Provider drop-down menu.

  5. Add a unique name in the Name field for the identity provider.

  6. Use the suggested username and password for the static user, or create your own.

    The credentials defined in this step are not visible after you select Confirm in the following step. If you lose the credentials, you must recreate the identity provider and define the credentials again.

  7. Select Confirm to create the HTPasswd identity provider and the user.

  8. Grant the static user permission to manage the cluster:

    1. Select Add user in the Cluster administrative users section of the Access control page.

    2. Enter the username that you defined in the preceding step into the User ID field.

    3. Select Add user to grant standard administration privileges to the user.

      The user is added to the dedicated-admins group.

Verification
  • The configured identity provider is now visible on the Access control tab of the Clusters page.

    After creating the identity provider, synchronization usually completes within two minutes. You can login to the cluster as the user after the HTPasswd identity provider becomes available.

Accessing your cluster

After you have configured your identity providers, users can access the cluster from the OpenShift Cluster Manager (OCM).

Prerequisites
  • You have created a cluster.

  • Identity providers have been configured for your cluster.

Procedure
  1. From OpenShift Cluster Manager (OCM), click on the cluster you want to access.

  2. Click Open Console.

  3. Click on your identity provider and provide your credentials to log into the cluster.

Verification
  • After you have accessed the cluster, you are directed to the console for your OpenShift Dedicated cluster.