Okta SSO with Amazon Cognito¶
This guide explains how to connect Okta to the Amazon Cognito user pool used by a self-hosted CloudAEye deployment.
CloudAEye uses Cognito for login. Okta acts as the SAML identity provider, and Cognito acts as the SAML service provider.
Prerequisites¶
- An Okta organization with administrator access.
- A deployed CloudAEye Cognito user pool and user pool app client.
- 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 OAuth flow, scopes, and SAML provider enablement need to be configured in Cognito.
Values Needed¶
Collect these values before configuring Okta:
| 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 Okta:
| Okta SAML field | Value |
|---|---|
| Single sign-on URL | https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse |
| Audience URI / SP Entity ID | urn:amazon:cognito:sp:<user-pool-id> |
| Name ID format | EmailAddress |
| Application username | Okta email or username |
Step 1: Create the Okta SAML App¶
- In Okta, go to Applications.
- Select Create App Integration.
- Choose SAML 2.0.
- Enter an app name, for example
CloudAEye.
Step 2: Configure Okta SAML Settings¶
Set the SAML fields as follows:
| Okta field | Value |
|---|---|
| Single sign-on URL | https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse |
| Recipient URL | https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse |
| Destination URL | https://<cognito-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse |
| Audience URI | urn:amazon:cognito:sp:<user-pool-id> |
| Name ID format | EmailAddress |
| Application username | Email |
Add only the SAML attributes Cognito needs:
| Name | Name format | Value |
|---|---|---|
email |
Unspecified | user.email |
firstName |
Unspecified | user.firstName |
lastName |
Unspecified | user.lastName |
Do not emit duplicate attributes with the same name. Cognito rejects SAML responses that contain duplicate attribute names.
Step 3: Assign Okta Users or Groups¶
Assign the CloudAEye SAML app to the Okta users or groups that should be allowed to sign in.
Only assigned users can complete the Okta side of the SSO flow.
Step 4: Copy Okta Metadata¶
After saving the Okta SAML app, copy the IdP metadata URL or download the metadata XML.
You will use this metadata when adding Okta as a SAML identity provider in Cognito.
Step 5: Add Okta as a SAML Provider in Cognito¶
In the Cognito user pool:
- Go to Sign-in experience.
- Go to Federated identity provider sign-in.
- Add a SAML identity provider.
- Set the provider name, for example
Okta. - Provide the Okta metadata URL or upload the Okta metadata XML.
- 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:
- Open the app client's hosted UI settings.
- Enable the Okta identity provider.
- Configure the callback URL used by CloudAEye.
- Enable the authorization code grant.
- Enable the
openid,email, andprofilescopes. - 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=Okta
Replace Okta with the exact Cognito identity provider name if you used a different provider name.
Expected flow:
- Cognito redirects to Okta.
- The user signs in with Okta.
- Okta posts a SAML response to Cognito.
- Cognito redirects to the CloudAEye callback URL with an authorization code.
- CloudAEye exchanges the code and signs the user in.
Troubleshooting¶
Login option is not available¶
The Okta 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¶
Okta is emitting duplicate SAML attributes. Remove duplicate attribute statements and keep one attribute per name.
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.