---
title: "Setting Up Amazon Cognito for SSO in Express (OIDC)"
slug: "setting-up-amazon-cognito-for-sso-in-express-oidc-unqork-platform"
tags: ["authentication", "single-sign-on"]
updated: 2026-09-14T17:01:11Z
published: 2026-09-14T17:01:11Z
canonical: "docs.unqork.io/setting-up-amazon-cognito-for-sso-in-express-oidc-unqork-platform"
---

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

# Setting Up Amazon Cognito for SSO in Express (OIDC)

This guide walks through configuring Amazon Cognito as an OpenID Connect (OIDC) identity provider for Express SSO in Unqork. Amazon Cognito is a user directory service that provides authentication, authorization, and user management for web and mobile applications. By configuring Cognito as an SSO provider, end-users of your Unqork applications can authenticate through your existing Cognito user pool instead of managing separate Unqork credentials.

This guide covers Express SSO. For Designer SSO, the configuration steps are similar but use the Designer domain instead of Express.

## Prerequisites

Before you begin, ensure you have:

**In Amazon Cognito:**

- An AWS account with access to Amazon Cognito.
- Permissions to create and configure user pools and app clients.
- A Cognito user pool with at least one test user.

**In Unqork:**

- Administrator access to the Unqork environment.
- Access to Single Sign-On (SSO).
- At least one Express Role created in **Express Role Administration**.

**Knowledge:**

- Basic familiarity with Amazon Cognito user pools and app clients.
- Understanding of OIDC authentication flow.
- Awareness of which Unqork Express Role to assign as the default for SSO users.

## How Settings Map Between Amazon Cognito and Unqork

Understanding the mapping between Cognito configuration and Unqork SSO settings helps streamline the setup process.

### OIDC Configuration Fields

| Unqork Field | Amazon Cognito Source | Example Value |
| --- | --- | --- |
| **Issuer** | User Pool > App Integration > Domain > Issuer URL | `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123XYZ` |
| **Client ID** | App Client > App client ID | `7a8b9c0d1e2f3g4h5i6j7k8l9m` |
| **Client Secret** | App Client > App client (if confidential client) | `abc123xyz789secretkey` |
| **Redirect URI** | Configured in Unqork, then added to Cognito | `https://your-environment.unqork.io/auth/oidc/cognito/cb` |
| **Scope** | User Pool > App Client > OAuth 2.0 scopes | `openid email profile` |

### User Attribute Mappings

| Cognito Claim | Unqork Attribute | Typical Use |
| --- | --- | --- |
| `{{ sub }}` | `userId` | Unique user identifier (UUID from Cognito) |
| `{{ email }}` | `email` | User email address |
| `{{ cognito:username }}` | `userId` or `name` | Cognito username (if different from email) |
| `{{ name }}` | `name` | User display name |
| `{{ phone_number }}` | `phone` | User phone number |

**Note:** Cognito uses standard OIDC claims. The `sub` claim is a unique identifier (UUID) that Cognito assigns to each user and never changes. Use `sub` as the match attribute for reliable user matching.

## Setting Up Amazon Cognito

### Step 1: Create or Locate Your User Pool

1. Sign in to the **AWS Management Console**.
2. Navigate to **Amazon Cognito**.
3. Select **User pools**.
4. Click **Create user pool** to create a new pool, or select an existing user pool.

**Note:** If creating a new user pool, follow the wizard to configure sign-in options (email, username), password policies, and MFA settings. For testing purposes, a basic configuration with email sign-in and standard password policy is sufficient.

### Step 2: Configure a Domain for Your User Pool

Cognito requires a domain to host the OAuth endpoints.

1. In your user pool, navigate to **App integration** tab.
2. Scroll to **Domain** section.
3. Click **Actions** > **Create Cognito domain** or **Create custom domain**.
4. For **Cognito domain**:
  - Enter a unique domain prefix (for example, `mycompany-unqork`).
  - Domain becomes: `https://mycompany-unqork.auth.us-east-1.amazoncognito.com`.
5. Click **Create**.

**Save this domain URL:** You'll need it to construct the issuer URL.

### Step 3: Create an App Client

1. In your user pool, navigate to **App integration** tab.
2. Scroll to **App clients and analytics**.
3. Click **Create app client**.

**Configure the app client:**

**App type:**

- Select **Confidential client** (requires client secret for security).

**App client name:**

- Enter a descriptive name (for example, `Unqork Express SSO`).

**Client secret:**

- Leave **Generate a client secret** checked.

**Authentication flows:**

- Check **ALLOW_REFRESH_TOKEN_AUTH**.
- Check **ALLOW_USER_PASSWORD_AUTH** (for testing only).
- Uncheck other flows unless needed for other integrations.

**OAuth 2.0 grant types:**

- Check **Authorization code grant**.

**OpenID Connect scopes:**

- Check **OpenID** (required).
- Check **Email** (to retrieve user email).
- Check **Profile** (to retrieve user profile attributes).

**Allowed callback URLs:**

- Leave blank for now (you'll add this after creating the Unqork SSO configuration).

**Allowed sign-out URLs:**

- Leave blank unless you need custom logout redirect.

1. Click **Create app client**.

### Step 4: Note Your Configuration Values

After creating the app client, gather the following values:

**Issuer URL:**

1. Navigate to **User pools** > Your pool > **User pool overview**.
2. Note the **User pool ID** (for example, `us-east-1_ABC123XYZ`).
3. Construct the issuer URL:
  - Format: `https://cognito-idp.{region}.amazonaws.com/{user-pool-id}`.
  - Example: `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123XYZ`.

**Client ID and Secret:**

1. Navigate to **App integration** > **App clients and analytics**.
2. Click your app client name.
3. Note the **Client ID** (for example, `7a8b9c0d1e2f3g4h5i6j7k8l9m`).
4. Click **Show client secret** and note the **Client secret**.

**Keep these values secure:** The client secret is sensitive and should not be shared publicly.

## Configuring SSO in Unqork

### Step 1: Navigate to SSO Management

Navigate to Single Sign-On (SSO) in the UnqorkAI platform.

1. Click **Add SSO Configuration** and select **Express**.
2. On the configuration form, select **OIDC** as the protocol.

### Step 2: Configure Basic Information

**SSO Name:**

- Enter a unique name (for example, `Cognito Express`).
- This name identifies the configuration in Unqork.

**Default Role:**

- Select an Express Role to assign to users who authenticate through Cognito.
- Common choice: Create a role like `Authenticated User` with appropriate permissions.
- **Important:** Users will receive this role automatically on first login.

**Default Groups (Optional):**

- Select any Express Groups to assign to SSO users.
- Leave blank if you don't use groups.

### Step 3: Configure OIDC Protocol Settings

**OP Discovery URL / Issuer:**

- Paste the issuer URL from Step 4 above.
- Format: `https://cognito-idp.{region}.amazonaws.com/{user-pool-id}`.
- Example: `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123XYZ`.

**OP Client ID:**

- Paste the **Client ID** from your Cognito app client.

**OP Client Secret:**

- Paste the **Client secret** from your Cognito app client.

**Redirect URI:**

- Unqork provides a default redirect URI pattern: `https://<host>/auth/oidc/<name>/cb`.
- You can use the default or enter a custom value.
- Copy this URI to add to Cognito (for example, `https://your-environment.unqork.io/auth/oidc/cognito/cb`).

**Scope:**

- Enter: `openid profile email`.
- This requests the OpenID Connect ID token with email and profile claims.

**PKCE Code Challenge Method:**

- Select **SHA256** for enhanced security.
- PKCE protects against authorization code interception attacks.
- Cognito supports SHA256 PKCE by default.
- Options: Disable PKCE, SHA256, Plain.

**Store OIDC ID Token:**

- Check this if you need to access the ID token in workflows.
- Typically not required for standard authentication.

**Get claims from instead of UserInfo Endpoint:**

- Leave unchecked unless you have custom claims in the access token.
- Standard user claims come from the ID token.

### Step 4: Configure Attribute Mappings

Attribute mappings connect Cognito user claims to Unqork user attributes.

**Default mappings:**

1. **User ID mapping:**.
  - Claim: `{{ sub }}`.
  - Attribute: `userId`.
  - This maps Cognito's unique user identifier to the Unqork user ID.
2. **Email mapping:**.
  - Claim: `{{ email }}`.
  - Attribute: `email`.
  - This populates the user's email address.

**To add a mapping:**

1. Click **Add Mapping**.
2. In the **Claim** field, enter the claim in template format (for example, `{{ sub }}`).
3. In the **Attribute** drop-down, select the Unqork attribute.
4. Repeat for each attribute you want to map.

**Available Unqork attributes:**

- `userId`: Unique user identifier
- `email`: User email address
- `name`: User display name
- `phone`: User phone number

**Match Attribute:**

- Select `userId` or `email` as the match attribute.
- This determines how Unqork identifies returning users.
- **Recommendation:** Use `userId` with the `{{ sub }}` claim for stable matching.

**Require User Exists:**

- Leave unchecked to create new users automatically on first login.
- Check this if only pre-existing Unqork users should be allowed to authenticate.

### Step 5: Save the Configuration

1. Review all settings.
2. Click **Save Changes**.
3. Unqork creates the SSO configuration and displays the message: "SSO configuration created successfully".

## Completing the Cognito Configuration

After saving the SSO configuration in Unqork, complete the setup in Cognito.

### Add the Redirect URI to Cognito

1. Return to the **AWS Management Console**.
2. Navigate to **Amazon Cognito** > **User pools** > Your pool.
3. Click **App integration** tab.
4. Scroll to **App clients and analytics**.
5. Click your app client name.
6. Click **Edit** in the **Hosted UI** section.
7. Under **Allowed callback URLs**, add the redirect URI from Unqork.
  - Example: `https://your-environment.unqork.io/auth/oidc/cognito/cb`.
8. Click **Save changes**.

**Important:** The redirect URI in Cognito must match exactly what Unqork provides. Any mismatch will cause authentication to fail with a redirect_uri_mismatch error.

## Testing Your Configuration

### Step 1: Access the SSO Preview

Navigate to Single Sign-On (SSO) in the UnqorkAI platform.

1. Locate your Cognito configuration in the **Express** tab.
2. Click the **three-dot menu** for the configuration.
3. Select **Preview**.

This opens the Cognito-hosted login page in a new browser tab.

### Step 2: Authenticate with a Test User

1. On the Cognito login page, enter the credentials for a test user in your user pool.
2. Click **Sign In**.
3. If this is the user's first login, Cognito may prompt for:
  - Password change (if temporary password was used).
  - MFA setup (if MFA is required).
4. Complete any required prompts.

### Step 3: Verify Successful Authentication

After successful authentication:

1. Cognito redirects to Unqork with an authorization code.
2. Unqork exchanges the code for tokens.
3. You should be authenticated in the Unqork environment.

**If authentication succeeds:**

- You'll see the Unqork interface.
- Navigate to Express User Administration to verify the user was created.
- Verify the user has the correct default role and attributes.

**If authentication fails:**

- Review the error message (if displayed).
- Check the browser console for errors.
- Proceed to the Troubleshooting section below.

### Step 4: Verify User Attributes

Navigate to Express User Administration in the UnqorkAI platform.

1. Search for the test user by email or username.
2. Click the user to view their details.
3. Verify:
  - **Email**: Matches the Cognito user email.
  - **User ID**: Populated with the Cognito `sub` claim (UUID format).
  - **Role**: Assigned the default role from your SSO configuration.
  - **Groups**: Assigned default groups (if configured).

## Troubleshooting

### Issue: "redirect_uri_mismatch" Error

**Cause:** The redirect URI in Cognito does not match the URI Unqork provides.

**Solution:**

1. In Unqork, view the SSO configuration and copy the exact redirect URI.
2. In Cognito, navigate to your app client settings.
3. Verify the **Allowed callback URLs** includes the exact URI from Unqork.
4. Check for:
  - Trailing slashes (Cognito is strict about exact matches).
  - HTTP vs. HTTPS.
  - Typos in the domain or .
5. Save changes in Cognito and retry.

### Issue: "invalid_client" Error

**Cause:** Client ID or client secret is incorrect or the app client is misconfigured.

**Solution:**

1. Verify the **Client ID** in Unqork matches the Cognito app client ID exactly.
2. Verify the **Client secret** is correct (click **Show client secret** in Cognito to compare).
3. Ensure the app client is a **Confidential client** (not a Public client).
4. Verify the app client has **Authorization code grant** enabled.
5. Update the SSO configuration in Unqork if credentials were incorrect.

### Issue: "invalid_scope" Error

**Cause:** The requested scopes are not enabled in the Cognito app client.

**Solution:**

1. In Cognito, navigate to your app client.
2. Verify the following scopes are checked:
  - **OpenID** (required).
  - **Email** (if you map email).
  - **Profile** (if you map name or other profile attributes).
3. Save changes and retry.

### Issue: User Not Created on First Login

**Cause:** **Require User Exists** is enabled in the Unqork SSO configuration, or attribute mapping is incorrect.

**Solution:**

1. In Unqork, edit the SSO configuration.
2. Verify **Require User Exists** is unchecked (to allow automatic user creation).
3. Verify the **Match Attribute** is set to `userId` or `email`.
4. Verify the corresponding claim mapping exists:
  - If match attribute is `userId`, ensure `{{ sub }}` maps to `userId`.
  - If match attribute is `email`, ensure `{{ email }}` maps to `email`.
5. Save changes and retry.

### Issue: Missing User Attributes After Login

**Cause:** Attribute mappings are incomplete or claims are not included in the ID token.

**Solution:**

1. Verify the **Scope** includes `email` and `profile` if you need those claims.
2. In Unqork, verify attribute mappings are configured:
  - `{{ sub }}` → `userId`
  - `{{ email }}` → `email`
  - `{{ name }}` → `name` (if needed)
3. In Cognito, ensure the user pool has the attributes you're trying to map:
  - Navigate to **User pool properties** > **Sign-in experience**.
  - Verify attributes like email and name are required or optional.
4. Test with a user who has those attributes populated.

### Issue: "User pool client does not have a secret" Error

**Cause:** The Cognito app client is configured as a Public client instead of Confidential.

**Solution:**

1. In Cognito, navigate to your app client.
2. Verify **App type** is **Confidential client**.
3. If it's a Public client, you must create a new app client as a Confidential client.
  - Public clients cannot be converted to Confidential clients.
4. Update the Unqork SSO configuration with the new Client ID and Client secret.

### Issue: Claims Not Available in ID Token

**Cause:** Cognito requires explicit scope requests to include certain claims.

**Solution:**

1. Verify the **Scope** in Unqork includes the required scopes:
  - `openid`: Always required for OIDC
  - `email`: Required for email claim
  - `profile`: Required for name, phone_number, and other profile claims
2. If you need custom claims, add them as custom attributes in the user pool and request them through scope.

## Security Best Practices

### Use PKCE

Always set **PKCE Code Challenge Method** to **SHA256** in the Unqork SSO configuration. PKCE protects against authorization code interception attacks and is supported by Cognito without additional configuration.

### Rotate Client Secrets Regularly

Cognito lets you generate new client secrets. If a secret is compromised:

1. In Cognito, navigate to your app client.
2. Generate a new client secret.
3. Update the Unqork SSO configuration with the new secret.
4. Test authentication to verify the new secret works.

### Use Confidential Clients Only

Always use **Confidential clients** (with client secrets) for server-side authentication. Public clients (without secrets) are intended for mobile or browser-based applications and should not be used for SSO.

### Limit Scope to Required Claims

Only request scopes that you need. For basic authentication, `openid email profile` is sufficient. Avoid requesting unnecessary scopes or permissions.

### Monitor Failed Login Attempts

Cognito provides CloudWatch metrics for authentication attempts. Monitor for the following:

- Failed login attempts (potential brute-force attacks).
- Invalid client errors (potential misconfiguration or credential leaks).
- High redirect_uri_mismatch errors (potential phishing attempts).

## Next Steps

After successfully configuring Cognito for Express SSO:

1. **Test with multiple users**: Verify that different users authenticate correctly and receive appropriate roles.
2. **Configure role mappings**: If users should receive different roles based on Cognito groups or attributes, configure advanced attribute mappings.
3. **Update application modules**: Ensure your Unqork applications reference the correct Express roles for RBAC.
4. **Document the configuration**: Maintain a record of the SSO setup for your team and future administrators.
5. **Set up monitoring**: Configure CloudWatch alarms for Cognito authentication failures.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-07-10 | Initial publication. |

OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials.

Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services.

The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE.

Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

The client_id is a public identifier for apps

The client secret is a secret known only to the application and the authorization server. The client secret acts as the applications password to the server.

URI (Uniform Resource Identifier) identifies a resource by name, location, or both.

Scope is a tool that limits an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

OAuth, or Open Authorization, is an authorization protocol that lets users grant third-party access to their information without sharing their passwords. OAuth is an industry standard that's used by many companies, including Google, Amazon, and Microsoft.

Multi-factor authentication (MFA) is a security measure that requires users to provide multiple pieces of verification to access an account. Adding an extra layer of protection to prevent unauthorized access even if one credential is compromised. MFA is also known as two-step verification.

An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource.

An OpenID Provider (OP) is Identity Provider (IdP) that acts as a service for authenticating users, provide tokens, and confirm user consent. OIDC providers conform to OpenID Connect, using ID tokens to verify a user's identity.

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

Authentication secrets are a value of confidential information. For example, a password, security token, or cryptographic key, that is used to verify a user's identity during the authentication process to grant access to a system or application.

RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network.