Skip to main content

AWS Cognito OIDC Configuration Guide

This guide explains how to configure AWS Cognito as an OIDC identity provider for Kargo.

important

The forms you will complete to enable Kargo to authenticate users against Cognito are different depending on whether you are:

  • Registering Kargo as a new application client for an existing user pool.

  • Creating a brand new user pool.

Be certain to follow the steps below that are appropriate to your scenario.

Using an Existing User Pool​

  1. Navigate to Cognito in your AWS dashboard.

    The left sidebar may be collapsed by default. If it is, expand it by clicking the "hamburger" icon in the upper left corner of the page.

    Cognito Home Page

  2. Select User pools.

  3. Select the pool to which you would like to add Kargo as a client.

  4. Select App clients from the left sidebar.

  5. Click the Create app client button on the upper right of the page.

  6. Complete the Create app client form:

    Create App Client

    1. Under Application type, select Single-page application (SPA).

    2. Complete the Name your application field with a descriptive name, such as kargo.

    3. Complete the Return URL field with a URL of the form https://<kargo-hostname>/login.

    4. Click Create app client.

  7. Skip ahead to the Configuring the App Client section of this page.

Creating a New User Pool​

  1. Navigate to Cognito in your AWS dashboard.

    The left sidebar may be collapsed by default. If it is, expand it by clicking the "hamburger" icon in the upper left corner of the page.

    Cognito Home Page

  2. Select User pools.

  3. Click the Create user pool button in the upper right of the page.

  4. Complete the Set up resources for your application form:

    Create User Pool and App Client

    important

    This single form asks you to both configure the user pool and register an app client.

    Also note that you have no control over the name of the user pool. A unique name will be generated for you upon submission of this form.

    1. Under Application type, select Single-page application (SPA).

    2. Complete the Name your application field with a descriptive name, such as kargo.

    3. Under Options for sign-in identifiers, select one or more identifiers for users to use when signing in.

      note

      This is a feature of the user pool and not the client app.

    4. Under Required attributes for sign-up, select all pieces of information you will require from users included in this user pool. At minimum, email must be selected.

      info

      Kargo is unopinionated about how users actually authenticate to OIDC, identity providers (e.g. with username/email and password, social login, etc.) however, Kargo does depend on the user's email address being available in the standard claim email of the user's OIDC identity token.

    5. Complete the Return URL field with a URL of the form https://<kargo-hostname>/login.

    6. Click Create user directory.

      This creates the user pool and the app client.

  5. Navigate to your newly created client app:

    1. Select User pools from the left sidebar.

    2. Select the user pool you just created.

    3. Select App clients from the left sidebar.

    4. Select the app client you just created.

  6. Continue on to the Configuring the App Client section of this page.

Configuring the App Client​

After completing the steps from either the Using an Existing User Pool or Creating a New User Pool section:

  1. Select the Login pages tab.

  2. In the Managed login pages configuration section, click Edit.

  3. Complete the Edit managed login pages configuration form:

    Edit Managed Login Pages Configuration

    1. Under URL, include both of the following:

      • https://<kargo-hostname>/login

        This is where users of the Kargo UI will be redirected to after logging in.

      • https://localhost/auth/callback

        This is where users of the kargo CLI will be redirected to redirected to after logging in. (The CLI launches a server to serve the request and complete the login process.)

    2. Under OAuth 2.0 grant types, ensure Authorization code grant is selected.

    3. Under OpenID Connect scopes, ensure that, at a minimum, Email, OpenID, and Profile are all selected.

      You may additionally select any other scopes that permit access to other user information you'd like to make available to Kargo.

    4. Click Save changes.

Configure Kargo​

After Kargo has been registered as a client application for your Cognito user pool, all that remains is to retrieve relevant details and use them in installing or updating Kargo. The details you will require are:

  • The user pool's issuer URL

  • The client app's client ID

The unofficial, but most convenient way to locate both of these is in the React code sample in the Quick setup guide:

Retrieve Client Config

After making note of these values, use them as the values of the api.oidc.issuerURL and api.oidc.clientID settings when installing or updating Kargo using its Helm chart as documented here.

info

Using Cognito as an identity provider, there is no need to create separate client apps for the Kargo UI and the kargo CLI, and as such, the same client ID should be used for both the api.oidc.clientID and api.oidc.cliClientID settings.