OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

OpenID Connect Overview

edit

OpenID Connect (OIDC) uses Security Token Service (STS) to allow clients to provide a web identity token to gain access to multiple services. When a client signs into a service using STS, the token is validated against the OIDC identity provider.

The OIDC protocol uses a configuration URL that contains the necessary information to authenticate a client’s identity. The protocol responds to the provider with the credentials needed for the provider to validate the client and sign them in.

Red Hat OpenShift Service on AWS clusters use STS and OIDC to grant the in-cluster operators access to necessary AWS resources.

edit

Understanding the OIDC verification options

There are three options for OIDC verification:

  • Unregistered, managed OIDC configuration

    An unregistered, managed OIDC configuration is created for you during the cluster installation process. The configuration is hosted under Red Hat’s AWS account. This option does not give you the ID that links to the OIDC configuration, so you can only use this type of OIDC configuration on a single cluster.

  • Registered, managed OIDC configuration

    You create a registered, managed OIDC configuration before you start creating your clusters. This configuration is hosted under Red Hat’s AWS account like the unregistered managed OIDC configuration. When you use this option for your OIDC configuration, you receive an ID that links to the OIDC configuration. Red Hat uses this ID to identify the issuer URL and private key. You can then use this URL and private key to create an identity provider and Operator roles. These resources are created under your AWS account by using Identity and Access Management (IAM) AWS services. You can also use the OIDC configuration ID during the cluster creation process.

  • Registered, unmanaged OIDC configuration

    You can create a registered, unmanaged OIDC configuration before you start creating your clusters. This configuration is hosted under your AWS account. When you use this option, you are responsible for managing the private key. You can register the configuration with Red Hat OpenShift Cluster Manager by storing the private key in an AWS secrets file by using the AWS Secrets Manager (SM) service and the issuer URL which hosts the configuration. You can use the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa, to create a registered, unmanaged OIDC configuration with the rosa create oidc-config --managed=false command. This command creates and hosts the configuration under your account and creates the necessary files and private secret key. This command also registers the configuration with OpenShift Cluster Manager.

The registered options can be used to create the required IAM resources before you start creating a cluster. This option results in faster install times since there is a waiting period during cluster creation where the installation pauses until you create an OIDC provider and Operator roles.

For ROSA Classic, you may use any of the OIDC configuration options. If you are using ROSA with HCP, you must create registered OIDC configuration, either as managed or unmanaged. You can share the registered OIDC configurations with other clusters. This ability to share the configuration also allows you to share the provider and Operator roles.

Reusing the OIDC configurations, OIDC provider, and Operator roles between clusters is not recommended for production clusters since the authentication verification is used throughout all of these clusters. Red Hat advises to only reuse resources on non-production test environments.
edit

Creating an OpenID Connect Configuration

When using a cluster hosted by Red Hat, you can create a managed or unmanaged OpenID Connect (OIDC) configuration by using the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa. A managed OIDC configuration is stored within Red Hat’s AWS account, while a generated unmanaged OIDC configuration is stored within your AWS account. The OIDC configuration is registered to be used with OpenShift Cluster Manager. When creating an unmanaged OIDC configuration, the CLI provides the private key for you.

Creating an OpenID Connect configuration

When using a Red Hat OpenShift Service on AWS cluster, you can create the OpenID Connect (OIDC) configuration prior to creating your cluster. This configuration is registered to be used with OpenShift Cluster Manager.

Prerequisites

  • You have installed and configured the latest Red Hat OpenShift Service on AWS (ROSA) CLI, rosa, on your installation host.

Procedure

  1. To create your OIDC configuration alongside the AWS resources, run the following command:

    $ rosa create oidc-config --mode=auto --yes

    This command returns the following information.

    Example output
    ? Would you like to create a Managed (Red Hat hosted) OIDC Configuration Yes
I: Setting up managed OIDC configuration
I: To create Operator Roles for this OIDC Configuration, run the following command and remember to replace <user-defined> with a prefix of your choice:
	rosa create operator-roles --prefix <user-defined> --oidc-config-id 13cdr6b
If you are going to create a Hosted Control Plane cluster please include '--hosted-cp'
I: Creating OIDC provider using 'arn:aws:iam::4540112244:user/userName'
? Create the OIDC provider? Yes
I: Created OIDC provider with ARN 'arn:aws:iam::4540112244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/13cdr6b'

    When creating your cluster, you must supply the OIDC config ID. The CLI output provides this value for --mode auto, otherwise you must determine these values based on aws CLI output for --mode manual.

  2. Optional: you can save the OIDC configuration ID as a variable to use later. Run the following command to save the variable:

    $ export OIDC_ID=<oidc_config_id>(1)
    1 In the example output above, the OIDC configuration ID is 13cdr6b.

    • View the value of the variable by running the following command:

      $ echo $OIDC_ID
      Example output
      13cdr6b
Verification

  • You can list the possible OIDC configurations available for your clusters that are associated with your user organization. Run the following command:

    $ rosa list oidc-config
    Example output
    ID                                MANAGED  ISSUER URL                                                             SECRET ARN
2330dbs0n8m3chkkr25gkkcd8pnj3lk2  true     https://dvbwgdztaeq9o.cloudfront.net/2330dbs0n8m3chkkr25gkkcd8pnj3lk2
233hvnrjoqu14jltk6lhbhf2tj11f8un  false    https://oidc-r7u1.s3.us-east-1.amazonaws.com                           aws:secretsmanager:us-east-1:242819244:secret:rosa-private-key-oidc-r7u1-tM3MDN

Parameter options for creating your own OpenID Connect configuration

The following options may be added to the rosa create oidc-config command. All of these parameters are optional. Running the rosa create oidc-config command without parameters creates an unmanaged OIDC configuration.

You are required to register the unmanaged OIDC configuration by posting a request to /oidc_configs through OpenShift Cluster Manager. You receive an ID in the response. Use this ID to create a cluster.
raw-files

Allows you to provide raw files for the private RSA key. This key is named rosa-private-key-oidc-<random_label_of_length_4>.key. You also receive a discovery document, named discovery-document-oidc-<random_label_of_length_4>.json, and a JSON Web Key Set, named jwks-oidc-<random_label_of_length_4>.json.

You use these files to set up the endpoint. This endpoint responds to /.well-known/openid-configuration with the discovery document and on keys.json with the JSON Web Key Set. The private key is stored in Amazon Web Services (AWS) Secrets Manager Service (SMS) as plaintext.

Example
$ rosa create oidc-config --raw-files
mode

Allows you to specify the mode to create your OIDC configuration. With the manual option, you receive AWS commands that set up the OIDC configuration in an S3 bucket. This option stores the private key in the Secrets Manager. With the manual option, the OIDC Endpoint URL is the URL for the S3 bucket. You must retrieve the Secrets Manager ARN to register the OIDC configuration with OpenShift Cluster Manager.

You receive the same OIDC configuration and AWS resources as the manual mode when using the auto option. A significant difference between the two options is that when using the auto option, ROSA calls AWS, so you do not need to take any further actions. The OIDC Endpoint URL is the URL for the S3 bucket. The CLI retrieves the Secrets Manager ARN, registers the OIDC configuration with OpenShift Cluster Manager, and reports the second rosa command that the user can run to continue with the creation of the STS cluster.

Example
$ rosa create oidc-config --mode=<auto|manual>
managed

Creates an OIDC configuration that is hosted under Red Hat’s AWS account. This command creates a private key that responds directly with an OIDC Config ID for you to use when creating the STS cluster.

Example
$ rosa create oidc-config --managed
Example output
W: For a managed OIDC Config only auto mode is supported. However, you may choose the provider creation mode
? OIDC Provider creation mode: auto
I: Setting up managed OIDC configuration
I: Please run the following command to create a cluster with this oidc config
rosa create cluster --sts --oidc-config-id 233jnu62i9aphpucsj9kueqlkr1vcgra
I: Creating OIDC provider using 'arn:aws:iam::242819244:user/userName'
? Create the OIDC provider? Yes
I: Created OIDC provider with ARN 'arn:aws:iam::242819244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/233jnu62i9aphpucsj9kueqlkr1vcgra'
edit

Creating an OIDC provider using the CLI

You can create an OIDC provider that is hosted in your AWS account with the Red Hat OpenShift Service on AWS (ROSA) CLI, rosa.

Prerequisites

  • You have installed the latest version of the ROSA CLI.

Procedure

  • To create an OIDC provider, by using an unregistered or a registered OIDC configuration.

    • Unregistered OIDC configurations require you to create the OIDC provider through the cluster. Run the following to create the OIDC provider:

      $ rosa create oidc-provider --mode manual --cluster <cluster_name>

      When using manual mode, the aws command is printed to the terminal for your review. After reviewing the aws command, you must run it manually. Alternatively, you can specify --mode auto with the rosa create command to run the aws command immediately.
      Command output
      aws iam create-open-id-connect-provider \
	--url https://oidc.op1.openshiftapps.com/<oidc_config_id> \(1)
	--client-id-list openshift sts.<aws_region>.amazonaws.com \
	--thumbprint-list <thumbprint> (2)
      1 The URL used to reach the OpenID Connect (OIDC) identity provider after the cluster is created.
      2 The thumbprint is generated automatically when you run the rosa create oidc-provider command. For more information about using thumbprints with AWS Identity and Access Management (IAM) OIDC identity providers, see the AWS documentation.

    • Registered OIDC configurations use an OIDC configuration ID. Run the following command with your OIDC configuration ID:

      $ rosa create oidc-provider --oidc-config-id <oidc_config_id> --mode auto -y
      Command output
      I: Creating OIDC provider using 'arn:aws:iam::4540112244:user/userName'
I: Created OIDC provider with ARN 'arn:aws:iam::4540112244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/241rh9ql5gpu99d7leokhvkp8icnalpf'
edit

Additional resources