Integrating Enterprise SSO with Cognito

If you’re already using Cognito for authentication, but now need to support SAML or Enterprise-level Single Sign-On (SSO), this guide is for you.

PropelAuth Configuration

Since you're already integrated with Cognito, we're assuming you already have a login page. In this guide, we’ll be extending Cognito to allow enterprise customers to sign in with their IdP via your login page.

We’ll start with making some changes in the PropelAuth dashboard.

1. Update Login Methods - Let’s navigate to the Signup / Login page. Here we can enable SAML but, since you already have other login methods enabled through Cognito, we can disable every other login method. While we’re here, let’s disable the Allow public signups setting by navigating to the Settings tab.

2. Organization Settings - Head over to the Organization Settings page and disable the Users can create their own orgs setting.

3. (Optional) Setup User Properties - If you have user properties such as name, username, and profile picture that you would like to collect from the IdP, head over to the User Properties page to enable them. You can also create a Custom User Property if you don’t see what you’re looking for.

4. (Optional) Enable Roles - If you already have orgs, you likely have roles as well. If you setup that same role structure with us, then your users can specify role information in the SAML connection and will show up with that role information after they login. If you’re wanting to use roles, navigate to the Roles & Permissions page and edit or create roles to match your own.

Creating Orgs for your Users

Since SAML is setup on an org to org basis, we need to make sure each user belongs to an org. This can be done manually through the PropelAuth dashboard (via the Organizations page) or programmatically through the PropelAuth API.

When creating an org, it’s essential that we also set the org’s domain (for example, “acme.com”).

We can then enable SAML for the org. We can do this either in the org’s Settings page or through the API.

Allowing your users to set up their SAML connection

Since SAML is the only enabled login method, we need a way for employees of an organization to set up their SAML connection. To do this, navigate to the Organizations page in your PropelAuth dashboard, find the org, click Settings, and click on the Generate Link button.

This button will generate a link to allow an employee of an organization to set up SAML. This link does not require authentication to access and is intended to be used by an employee of the org, such as a member of their IT team.

Cognito Configuration

Now that we have everything prepared on the PropelAuth side, let's add a provider to your Cognito account. This provider will then allow us to create a "Login With Enterprise SSO" button to your login page.

Create a New User Pool

Head over to your Cognito account and click on Create user pool. On the next menu, select Federated identity providers as the Provider Type.

Under Cognito user pool sign-in options select Email.

Towards the bottom of the page under Federated sign-in Options select OpenID Connect (OIDC).

Continue configuring the user pool settings as you'd like until you reach the Connect federated identity providers page. If you're using Cognito's hosted pages, the Provider Name is what your users will see when logging in. Because of this, you might want to name it something like Enterprise Login.

You can find the Client ID and Client Secret by heading over to the Frontend Integration page, clicking on Advanced Settings followed by Edit OAuth Config. Here, we can generate a Client ID and Client Secret. We'll soon come back here to enter a Redirect URI.

In the Authorized Scopes section type openid profile email.

In the Retrieve OIDC endpoints section, select Manual input. We'll then be prompted to populate five fields. Each URL will start with your Issuer URL, which can be found in the Backend Integration page in your PropelAuth dashboard.

1. Issuer URL: {YOUR_ISSUER_URL}
2. Authorization endpoint: {YOUR_ISSUER_URL}/propelauth/oauth/authorize
3. Token endpoint: {YOUR_ISSUER_URL}/propelauth/oauth/token
4. UserInfo endpoint: {YOUR_ISSUER_URL}/propelauth/oauth/userinfo
5. Jwks_uri endpoint: {YOUR_ISSUER_URL}/.well-known/jwks.json

When mapping attributes, make sure to match the user pool attribute email field to email in the Open ID Connect attribute section. You can also map other attributes as you'd like. For example, we recommend creating a custom attribute called orgs where you can store your org and role information, like so:

Refer to the example user object below for guidance:

{
  "can_create_orgs": false,
  "created_at": 1711127287,
  "email": "test@propelauth.com",
  "email_confirmed": true,
  "enabled": true,
  "first_name": "Anthony",
  "has_password": true,
  "last_active_at": 1712328977,
  "last_name": "Edwards",
  "locked": false,
  "metadata": null,
  "mfa_enabled": false,
  "org_id_to_org_info": {
      "35905720-f22a-4f36-b082-7f35bb32463f": {
          "org_id": "35905720-f22a-4f36-b082-7f35bb32463f",
          "org_name": "PropelAuth",
          "url_safe_org_name": "propelauth",
          "user_role": "Owner",
          "inherited_user_roles_plus_current_role": [
              "Owner",
              "Admin",
              "Member"
          ],
          "org_metadata": {},
          "user_permissions": [
              "propelauth::can_invite",
              "propelauth::can_change_roles",
              "propelauth::can_remove_users",
              "propelauth::can_setup_saml",
              "propelauth::can_manage_api_keys"
          ]
      }
  },
  "picture_url": "https://img.propelauth.com/2a27d237-db8c-4f82-84fb-5824dfaedc87.png",
  "properties": {
    "favoriteSport": "Basketball"
  },
  "sub": "0497bbe6-49c1-4bc7-9e9c-c75846722c73",
  "update_password_required": false,
  "user_id": "0497bbe6-49c1-4bc7-9e9c-c75846722c73"
}

On the next page under the Initial app client section, select Other and set a callback URL to your app.

Expand the Advanced app client settings and make sure the OpenID Connect scopes are set to OpenId, Email, and Profile.

Once you're done creating the user pool, click on the App integration tab to get your Cognito Domain. We'll use this + /oauth2/idpresponse as a Redirect URI in your Edit OAuth Config page in PropelAuth. For example, if your Cognito Domain is https://propelauthpool.auth.us-east-1.amazoncognito.com, then we'll enter:

https://propelauthpool.auth.us-east-1.amazoncognito.com/oauth2/idpresponse

in PropelAuth as a Redirect URI.

Installation

There are a lot of different ways to integrate with Cognito. We'll walk through a version where we create a new button in your custom login page. However, if you use Cognito's hosted UI, you should now see a button like so:

Creating a Sign in Page

If you're not using Cognito's hosted pages, you can create a button that redirects the user straight to PropelAuth's SAML login flow. The URL will use the Cognito Domain from the previous step as well as your App Client's Client ID found in Cognito.

{YOUR_COGNITO_DOMAIN}/oauth2/authorize?client_id={YOUR_APP_CLIENT_CLIENT_ID}&response_type=code&scope=email+openid+profile&redirect_uri={YOUR_CALLBACK_URL}

Whether the user clicks this button or navigates to PropelAuth from the Cognito hosted page, they'll see the following:

If they enter an email that has a domain linked to an org with SAML enabled, they'll automatically be redirected to login via their IdP. Once they complete the login process, they'll be redirected to your app with a code query parameter, like so:

https://localhost:3000/callback?code=0c2a4743-a6c6-47fb-af28-5305a812d605

You can then exchange that code for a Cognito Access Token via the Token Endpoint. Here's an example:

curl --location '{YOUR_COGNITO_DOMAIN}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'redirect_uri={YOUR_CALLBACK_URL}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={CODE_FROM_QUERY_PARAMETER}' \
--data-urlencode 'client_id={YOUR_APP_CLIENT_CLIENT_ID}'

This will then return an access_token which you can use to get the user's information, such as the userInfo endpoint which will contain the user and org information we mapped in Cognito.

And that’s it! Your users can now:

• Setup SAML
• Login via SAML
• Show up with org details, roles, and user properties when they login

You’re now all set and ready to managing your users with Enterprise SSO!