Configure Amazon Cognito

If your organization uses Amazon Cognito for user authentication, you can configure Rancher to allow login using Amazon Cognito credentials. The following instructions describe how to configure Rancher to work with Amazon Cognito:

Prerequisites

• In Rancher:
  • Amazon Cognito is disabled.

note

Consult the Amazon Cognito documentation to configure the user pool.

• In Amazon Cognito:
  • Create a new user pool or use an existing one.
  • In the App client settings, set the redirect URL to https://yourRancherHostURL/verify-auth. Replace yourRancherHostURL with the actual hostname of your Rancher instance (e.g., https://rancher.example.com/verify-auth).

Configuring Amazon Cognito in Rancher

1. In the upper left corner of the Rancher UI, click ☰ > Users & Authentication.

2. In the left navigation bar, click Auth Provider.

3. Select Amazon Cognito.

4. Complete the Configure an Amazon Cognito account form. For help with filling the form, see the configuration reference.

5. Click Enable.

   Rancher will redirect you to the Amazon Cognito login page. Enter your Amazon Cognito credentials to validate your Rancher configuration.

   note

   You may need to disable your popup blocker to see the Amazon Cognito login page.

Result: Rancher is configured to work with your Amazon Cognito using the OIDC protocol. Your users can now sign into Rancher using their Amazon Cognito logins.

note

User and group search is not supported for Amazon Cognito. When assigning permissions to a Project or Cluster, you must manually enter the UserID generated by Cognito if the user has not yet logged in to Rancher. However, if the user has previously logged in, you can assign permissions using their username or email address.

Configuration Reference

Field	Description
Client ID	The Client ID of your Amazon Cognito App Client.
Client Secret	The generated Secret of your Amazon Cognito App Client.
Issuer	The Issuer URL of your Amazon Cognito App Client. It follows the format https://cognito-idp.{region}.amazonaws.com/{userPoolId}, and can be found in the App Client settings page. Rancher uses the Issuer URL to fetch all of the required URLs.

Troubleshooting

You are not redirected to your authentication provider

If you fill out the Configure an Amazon Cognito account form and click on Enable, and you are not redirected to Amazon Cognito, verify your Amazon Cognito configuration.

Configuring OIDC Single Logout (SLO)

Rancher supports the ability to configure OIDC Single Logout (SLO). Options include logging out of the Rancher application only, logging out of Rancher and registered applications tied to the external authentication provider, or a prompt asking the user to choose between the previous options.

Prerequisites

Before configuring OIDC SLO, ensure the following is set up on your IdP:

• SLO Support: The Log Out behavior configuration section only appears if your OIDC IdP allows for OIDC SLO.
• Post-Logout Redirect URI: Your Rancher Server URL must be configured as an authorized post-logout redirect URI in your IdP's OIDC client settings. This URL is used by the IdP to redirect a user back to Rancher after a successful external logout.

OIDC SLO Configuration

Configure the SLO settings when setting up or editing your OIDC authentication provider.

1. Sign in to Rancher using a standard user or an administrator role.

2. In the top left corner, select ☰ > Users & Authentication.

3. In the left navigation menu, select Auth Provider.

4. Under the section Log Out behavior, choose the appropriate SLO setting as described below:

   Setting	Description
   Log out of Rancher and not authentication provider	Choosing this option will only logout the Rancher application and not external authentication providers.
   Log out of Rancher and authentication provider (includes all other applications registered with authentication provider)	Choosing this option will logout Rancher and all external authentication providers along with any registered applications linked to the provider.
   Allow the user to choose one of the above in an additional log out step	Choosing this option presents users with a choice of logout method as described above.

5. If you choose to log out of your IdP, provide an End Session Endpoint. Rancher uses this URL to initiate the external logout.

How to get the End Session Endpoint

The end_session_endpoint is one of the specific URLs published within a standardized JSON object containing the IdP's metadata and is retrieved from the OIDC Discovery URL. To get the end_session_endpoint from the OIDC Discovery URL, follow these steps:

1. Obtain the Discovery URL by appending the IdP Issuer URL with the well-known path (.well-known/openid-configuration).

2. Send an HTTP GET request to the Discovery URL.

3. In the JSON object, look for the key named end_session_endpoint and retrieve the URL.

   You can also use a curl command to retrieve end_session_endpoint:

   curl -s <ISSUER_URL>/.well-known/openid-configuration | jq '.end_session_endpoint'