> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon Cognito

> Configure Amazon Cognito as an OpenID Connect identity provider for Modelcode

This guide walks through configuring **Amazon Cognito** as an OIDC identity provider for Modelcode SSO. Cognito User Pools natively support OpenID Connect.

## Prerequisites

* Admin access to your Modelcode organization, **signed in with email and password** — the SSO settings page is not available to users who signed in with a social provider (GitHub, GitLab, Microsoft)
* An AWS account with access to Amazon Cognito
* Privileges to create and edit app clients and policies in your Cognito User Pool

## Step 1: Create an App Client in Cognito

1. In the AWS Console, navigate to **Amazon Cognito → User Pools**
2. Select your User Pool (or create a new one)
3. Go to **App integration → App clients and analytics**
4. Click **Create app client**
5. Configure the app client:

| Field                        | Value                                     |
| ---------------------------- | ----------------------------------------- |
| **App type**                 | Confidential client                       |
| **App client name**          | `Modelcode SSO` (or any descriptive name) |
| **Generate a client secret** | Yes                                       |

6. Under **Hosted UI settings**, configure:

| Field                     | Value                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Allowed callback URLs** | The **Callback URL** from the Modelcode SSO settings page (displayed when you select OpenID Connect) |
| **Allowed sign-out URLs** | `https://morph.modelcode.ai` (optional)                                                              |
| **Identity providers**    | Select the providers enabled in your User Pool                                                       |
| **OAuth 2.0 grant types** | Authorization code grant                                                                             |
| **OpenID Connect scopes** | `openid`, `email`, `profile`                                                                         |

<Tip>
  The Callback URL is displayed on the Modelcode SSO settings page when you select OpenID Connect.
</Tip>

7. Click **Create app client**
8. After creation, note the **Client ID** and **Client Secret** from the app client details

## Step 2: Find Your Cognito Issuer URL

The Cognito Issuer URL follows this format:

```
https://cognito-idp.<region>.amazonaws.com/<user-pool-id>
```

To find your values:

1. In the Cognito console, go to your User Pool
2. The **User Pool ID** is displayed on the overview page (e.g., `us-east-1_aBcDeFgHi`)
3. The **Region** is the AWS region where your User Pool is hosted (e.g., `us-east-1`)

For example, if your User Pool ID is `us-east-1_aBcDeFgHi`, the Issuer URL is:

```
https://cognito-idp.us-east-1.amazonaws.com/us-east-1_aBcDeFgHi
```

You can verify the discovery document is available by visiting:

```
https://cognito-idp.<region>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration
```

## Step 3: Configure OIDC in Modelcode

1. In Modelcode, navigate to **Single Sign-On** in the sidebar
2. Click **Setup SSO** (or **Edit** if updating)
3. Select **OpenID Connect** as the protocol
4. Enter the following:

| Field             | Value                                                       |
| ----------------- | ----------------------------------------------------------- |
| **Issuer URL**    | `https://cognito-idp.<region>.amazonaws.com/<user-pool-id>` |
| **Client ID**     | The Client ID from your Cognito app client                  |
| **Client Secret** | The Client Secret from your Cognito app client              |
| **Scopes**        | `openid email profile` (default)                            |

5. Click **Verify & Save**

Modelcode validates the configuration by fetching the Cognito OIDC discovery document.

## Step 4: Update the Callback URL in Cognito

After configuring, verify the **Callback URL** displayed on the Modelcode SSO settings page matches the **Allowed callback URL** in your Cognito app client. Update the Cognito app client if needed.

## Step 5: Invite Users and Share the Portal Link

Before users can sign in via SSO, they must be invited to Modelcode:

1. In Modelcode, go to the [Members](https://morph.modelcode.ai/user-roles?tab=users) page and invite each user who needs SSO access
2. Copy the **Portal Link** from the SSO settings page and share it with your team:

```
https://morph.modelcode.ai/sso-portal/<your-organization-id>
```

When team members visit this link, they are redirected to the Cognito hosted UI (or your custom UI domain) to sign in, then returned to Modelcode with an active session.

## Troubleshooting

### "Verification failed" during setup

* Confirm the Issuer URL follows the format `https://cognito-idp.<region>.amazonaws.com/<user-pool-id>`
* Verify the User Pool ID and region are correct
* Access the discovery URL in your browser to confirm it returns a JSON document

### Users see "redirect\_mismatch" error

* The Callback URL in Cognito must exactly match the Callback URL shown in Modelcode — including the protocol, domain, and path
* Check for trailing slashes or other differences

### Users authenticate but are not recognized in Modelcode

* Ensure the user's email in Cognito matches their Modelcode account email
* Verify the `email` attribute is configured and populated for users in the Cognito User Pool
* Confirm the `email` scope is included in the app client's allowed scopes
* Ensure users are accessing Modelcode through the **Portal Link**, not the standard login page

### Users see the Cognito hosted UI instead of a custom login page

* If you've configured a custom domain for your Cognito User Pool, it should work automatically with OIDC
* The Cognito hosted UI is the default authentication interface when no custom UI is configured