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 Administration > Environment > 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

User Attribute Mappings

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.

4. 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 Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

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 Access Token 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 Administration > Environment > Single Sign-On (SSO) in the Unqork IDE.

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 Administration > Express Permissions > 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 Administration > Express Permissions > Express User Administration in the Unqork IDE.

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 path.
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.