AWS Cognito

AWS Cognito Integration with Scalekit for Single Sign-On

Expand your existing AWS Cognito authentication system by integrating Scalekit as an OpenID Connect (OIDC) provider. This integration enables enterprise users to log into your application seamlessly using Single Sign-On (SSO).

Scalekit - AWS Cognito Integration

Here's a typical flow illustrating the integration:

1. User initiates login: Enterprise users enter their company email address on your application's custom login page (not managed by AWS Cognito) to initiate SSO.
2. Authentication via Scalekit: Based on identifiers such as the user's company email and Scalekit's connection identifier, users are redirected to authenticate through their organization's Identity Provider (IdP).

Prefer exploring an example app? Check out this Next.js example on GitHub

Configuring Scalekit as an OIDC Provider in AWS Cognito

To enable AWS Cognito to redirect users to Scalekit for SSO initiation, configure your Scalekit account as an OIDC provider within AWS Cognito:

1. Navigate to AWS Cognito and select your existing User Pool.
2. Under the Authentication section, choose Social and external providers.
3. Click Add identity provider > OpenID Connect (OIDC).

AWS Cognito will display a form requiring specific details to establish the connection with Scalekit:

AWS Cognito - Add Identity Provider

Field	Description
Provider Name	A recognizable label for Scalekit within the AWS ecosystem. This name is used programmatically when generating authorization URLs. For example: ScalekitIdPRouter.
Client ID	Obtain this from your Scalekit Dashboard under API Config.
Client Secret	Generate a secret from your Scalekit Dashboard (API Config) and input it here.
Authorized Scopes	Scopes defining the user attributes that AWS Cognito can access from Scalekit.
Identifiers	Identifiers instruct AWS Cognito to check user-entered email addresses during sign-in and direct users accordingly to the associated identity provider based on their domain.
Attribute Request Method	Method used to exchange attributes and generate tokens for users; ensure you map Scalekit's user attributes correctly to your user pool attributes in AWS Cognito.
Issuer URL	Enter your Scalekit environment URL found in the Scalekit Dashboard under API Config.

Scalekit's profile information includes various user attributes useful for your application requirements. Map these attributes between both providers using the attribute list found at Scalekit Dashboard > Authentication > Single Sign On.

This ensures standardized information exchange between your customers' identity providers and your application.

Scalekit - User Attributes

The same attribute names are considered OpenID Connect attributes within AWS Cognito, streamlining user profile synchronization between your app and identity providers.

AWS Cognito - Map Attributes

Click Add identity provider to complete adding Scalekit as an identity provider.

Implementing Single Sign-On in your application

Your application should use its own custom login page instead of the managed login page provided by AWS Cognito. This approach allows you to collect enterprise users' email addresses and redirect them appropriately for authentication via SSO.

Your App (example) - Custom Login Page

Generate an authorization URL with two additional parameters— identity_provider and login_hint — to redirect users seamlessly:

Example Code

import { Issuer, Client } from "openid-client";

const client = await getOidcClient();

const authUrl = client.authorizationUrl({
  scope: "openid email",
  state: state,
  nonce: nonce,
  identity_provider: "ScalekitIdPRouter", // Same as Provider name (above)
  login_hint: email, // User's company email address
});
console.log("authUrl", authUrl);
const response = NextResponse.redirect(authUrl);

Example Authorization Endpoint URL

Here's an example of a complete authorization endpoint URL incorporating the required parameters:

Example Authorization URL

https://[domain].auth.[region].amazoncognito.com/oauth2/authorize
  ?client_id=k6tana1l8b0bvhk9gfixkurr6
  &scope=openid%20email
  &response_type=code
  &redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback
  &state=-5iLRZmPwwdqwqT-A4yiJM6KQvCLQM0JRx9QaXOlzRE
  &nonce=sGSXePnJ0Ue5GZyTpKG4rRsVeWyfZloImbMWunUDbG4
  &identity_provider=ScalekitIdPRouter
  &login_hint=enterpriseuser%40example.org

For ease of development, Scalekit supports testing with @example.org and @example.com domains. Authorization endpoints generated using these domains as login_hint will redirect enterprise users to Scalekit's built-in IdP Simulator.

Scalekit - IdP Simulator

Treat the IdP Simulator as equivalent to an actual organization's IdP authentication step. For instance, if John belongs to Megasoft (using Okta as their IdP), logging in with john@megasoft.org would redirect him to Okta's authentication process (including MFA or other organizational policies).

Scalekit integrates seamlessly with major identity providers. Use Scalekit's admin portal to onboard enterprise customers, enabling them to set up connections between their identity providers and your application.

info

The domain of your enterprise customer should be added to the list of identifiers in the AWS Cognito > User Pool > Authentication > Social and external providers > [ScalekitIdPRouter] > Identifiers

Successful SSO response

Upon successful authentication via SSO, your application receives user profile details mapped according to AWS Cognito's configured user attributes:

Successful SSO response

{
"sub": "807c593c-d0c1-709c-598f-633ec61bcc8b",
"email_verified": "false",
"email": "john@example.com",
"username": "scalekitIdPRouter_conn_60040666217971987;a2c49d97-d36f-460f-97c2-87eb295095af"
}

Now that you've successfully integrated AWS Cognito with Scalekit for SSO, here are some recommended next step — Onboard Enterprise Customers using the Scalekit admin portal to help customers configure their identity providers.