Skip to content

Keycloak SSO with Amazon Cognito

This guide explains how to connect a Keycloak realm to the Amazon Cognito user pool used by a self-hosted CloudAEye deployment.

CloudAEye uses Cognito for login. Keycloak acts as the SAML identity provider, and Cognito acts as the SAML service provider.

Prerequisites

  • A Keycloak realm with administrator access.
  • A deployed CloudAEye Cognito user pool and user pool app client.
  • A CloudAEye callback URL for the self-hosted deployment.
  • Access to update the Cognito app client's hosted UI settings.

The default CloudAEye Terraform stack creates the Cognito user pool and app client, but the callback URL, OAuth flow, scopes, and SAML provider enablement need to be configured in Cognito.

Values Needed

Collect these values before configuring Keycloak:

Value Format
AWS region <region>
Cognito domain <cognito-domain>
User pool ID <user-pool-id>
App client ID <app-client-id>

Use these Cognito SAML values in Keycloak:

Keycloak SAML field Value
ACS URL https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse
SP Entity ID / Client ID urn:amazon:cognito:sp:<user-pool-id>
Name ID format Email

Step 1: Create the Keycloak SAML Client

  1. In Keycloak, select the realm that should authenticate CloudAEye users.
  2. Go to Clients.
  3. Select Create client.
  4. Set Client type to SAML.
  5. Set Client ID to:
urn:amazon:cognito:sp:<user-pool-id>
  1. Enter a display name, for example CloudAEye.

Step 2: Configure the Keycloak SAML Client

Configure the client with these values:

Keycloak field Value
Client ID urn:amazon:cognito:sp:<user-pool-id>
Valid redirect URIs https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse
Master SAML Processing URL https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse
Name ID format Email
Force POST binding On
Sign documents On
Sign assertions On

Step 3: Configure Keycloak Attribute Mappers

Add SAML mappers for the user attributes Cognito will consume:

Mapper type User property SAML attribute name
User Property email email
User Property firstName firstName
User Property lastName lastName

Keep the emitted SAML attributes minimal. Cognito rejects SAML responses that contain more than one attribute with the same name.

Step 4: Copy Keycloak Metadata

Download the SAML IdP metadata(Keycloak SAML adapter.xml) for the realm or copy the metadata URL.

You will use this metadata when adding Keycloak as a SAML identity provider in Cognito.

Step 5: Add Keycloak as a SAML Provider in Cognito

In the Cognito user pool:

  1. Go to Sign-in experience.
  2. Go to Federated identity provider sign-in.
  3. Add a SAML identity provider.
  4. Set the provider name, for example Keycloak.
  5. Provide the Keycloak metadata URL or upload the Keycloak metadata XML.
  6. Configure attribute mapping.

Recommended attribute mapping:

Cognito attribute SAML attribute
email email
given_name firstName
family_name lastName

The CloudAEye Cognito template defines email, given_name, and family_name as mutable attributes, which allows Cognito to update these values during federated sign-in.

Step 6: Configure the Cognito App Client

In the Cognito app client used by CloudAEye:

  1. Open the app client's hosted UI settings.
  2. Enable the Keycloak identity provider.
  3. Configure the callback URL used by CloudAEye.
  4. Enable the authorization code grant.
  5. Enable the openid, email, and profile scopes.
  6. Save the app client changes.

The callback URL in Cognito must exactly match the redirect URI used by CloudAEye, including scheme, host, path, and trailing slash behavior.

Step 7: Test Sign-In

Open this URL in a browser:

https://<cognito-domain>.auth.<region>.amazoncognito.com/oauth2/authorize?client_id=<app-client-id>&response_type=code&scope=openid+email+profile&redirect_uri=<url-encoded-callback-url>&identity_provider=Keycloak

Replace Keycloak with the exact Cognito identity provider name if you used a different provider name.

Expected flow:

  1. Cognito redirects to Keycloak.
  2. The user signs in with Keycloak.
  3. Keycloak posts a SAML response to Cognito.
  4. Cognito redirects to the CloudAEye callback URL with an authorization code.
  5. CloudAEye exchanges the code and signs the user in.

Troubleshooting

Login option is not available

The Keycloak provider is not enabled on the Cognito app client, the provider name in the authorize URL does not match the Cognito provider name, or the wrong app client is being used.

SAML response contains duplicate attributes

Keycloak is emitting duplicate SAML attributes. Remove duplicate mappers and default client scopes that emit duplicate attribute names.

user.email: Attribute cannot be updated

The Cognito email attribute is mapped from SAML but is immutable in the user pool. The CloudAEye user pool template sets email as mutable; if this error appears, verify you are using the expected user pool.

invalid_grant during code validation

The authorization code may be stale, already used, or issued for a different redirect URI. Confirm the callback URL in Cognito exactly matches the redirect URI used by CloudAEye.