I recently worked on a project that required integration with Okta as an external identity provider via SAML 2.0. For the purpose of future-proofing this project and making it easier to change identity provider, we use opted for using AWS Cognito as the authentication. It took several weeks of research to have the integration down as documentation about this is very thin on the interwebs. After fully getting the integration down, I thought it was worth making a note of it and hopefully save someone else a ton of time.
Okta Setup
Okta is a widely spread identity provider for application authentication and user management. It’s particularly popular because of its smooth integrated with Active Directory (AD). In our context, Okta can be regarded as an external Identity Provider (IdP), given that the actual user management is carried out.
AWS Cognito
AWS Cognito provides authentication, authorisation and user management for applications. It can be linked to Facebook, Amazon, Google, and Apple as well as through OpenID Connect (OIDC) and SAML Identity Providers. For this integration, we will be linking Okta to Cognito via SAML 2.0. The process will require a back and forth.
AWS Cognito Configuration
- Sign in to your AWS Account and locate the Cognito Service.
- Create a User Pool.
- Under Attributes -> Add Custom Attributes
OKTA_ID
- Under App Clients -> Create an App Client
- Under Attributes -> Add Custom Attributes
- Note the ClientId and ClientSecret.
- After creating the User Pool locate App integration -> App Client Settings.
- Configure the settings like below:
- Under Domain -> Specify a Unique Domain Name. This domain will host AWS Cognito’s sign-up and sign-in pages. Note this down.
- Note the UserPool ID under General settings.
Okta Configuration
- Log in to a newly created or existing Okta Developer Account.
- Switch layout to Classic UI by clicking on the Developer Console dropdown on the top left-hand side of the page and selecting Classic UI. See below:
- Click on Dashboard.
- On the shortcuts sidebar, click on the Add Application button and it will bring you to the applications page.
- On the top right-hand side, click on the Create New App button, a dialogue will open.
- Select the platform as the Web, Sign-on method as SAML 2.0 and create the app.
- Enter the App Name of your choice and click Next.
Now you need to configure the following fields:
- Single Sign-on URL: https://<specified domain url> .auth.<aws-region>.amazonCognito.com/saml2/idpresponse i.e. https://www-the-jbp-com.auth.eu-west-1.amazonCognito.com/saml2/idpresponse
- Audience URI (SP Entity ID) : urn:amazon:Cognito:sp:<UserPool> i.e urn:amazon:Cognito:sp:eu-west-1_DEMOPOOLID
- Name ID format: Persistent
- Application Username: Email (see below as ref.). The values in the figure below are examples. Please update with appropriate values.
- Configure Attribute Statements Section as follows (see below as ref.)
- Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- Value: user.email
- oktaFirstName: user.firstName
- oktaLastName: user.lastName
- oktaId: user.id
- Click Next.
- For the question “Are you a customer or partner?” select “I’m an Okta customer adding an internal app” and click Finish.
- Click the Sign-on tab.
- Locate the section Settings -> SIgn-on Methods.
- Locate and click on with title Identity Provider Metadata.
- Copy and note the Identity Provider Metadata URL somewhere safe. It looks like https://dev.oktapreview.com/app/exkppfps144qEuvax0h7/sso/saml/metadata.
AWS Cognito Update
- Sign in to your AWS Account and locate the Cognito Service.
- Locate the previously created User Pool.
- Locate Federation -> Identity providers.
- Select SAML and paste Identity Provider metadata URL in the empty text box like below:
- Enter the Provider Name.
- Make sure to check the box for Enable IdP sign out flow.
- Click on Create Provider.
- Under Active SAML Providers, click Show Signing Certificate to see the certificate value.
- Copy the template below into a text file and replace the <CERTIFICATE VALUE> with the certificate value from the previous response. Save the text file as Cognito.crt.
-----BEGIN CERTIFICATE-----
<CERTIFICATE VALUE>
-----END CERTIFICATE------ Locate App Integration -> App Client Setting.
- Check the box for the newly create Identity Provider and Save changes.
Okta Configuration Update
- Log in to a newly created or existing Okta Developer Account.
- Switch layout to Classic UI by clicking on the Developer Console dropdown on the top left-hand side of the page and selecting Classic UI. See below:
- From the Console Page, click on Applications and click on the App created earlier and then the general tab.
- Under SAML Settings, click Edit and Next to the SAML Settings page.
- Click Show Advanced Settings and update the section with the following:
- Check the box for Enable Single Logout.
- Enter Single Logout URL as https://<CognitoDomainPrefix>-<Environment>.auth.<aws-region>.amazonCognito.com/saml2/logout e.g. https://orbithr-prod.auth.eu-west-1.amazonCognito.com/saml2/logout.
- SP Issuer: urn:amazon:Cognito:sp:<UserPool> i.e urn:amazon:Cognito:sp:eu-west-1_DEMOPOOLID (Same value as the Audience URI (SP Entity ID)).
- Signature Certificate: upload the saved Cognito.crt file.
- Click Next and Finish.
To test the configuration:
https://<aws-domain>.auth.<aws-region>.amazonCognito.com/oauth2/authorize?clientId=<clientid>&response_type=code&scope=email+openid+phone+profile&redirect_uri=<redirect_url>&identity_provider=<identity_provider_name>
i.e
Where:
<clientId> is App client ID
<redirecturl> is the previously configured redirect URL in AWS Cognito
<identity_provider_name> is the provider name
NOTE: AWS Cognito user pools does not support an IDP initiated flow as at writing this post. if you require that functionality, I suggested to hide the Okta SAML app from the users and create a Bookmark App as a workaround for this.
