Amazon Cognito

The Amazon Cognito connection

is a user provider that automatically imports your users and keeps them up-to-date in UserHub.

To enable the Amazon Cognito connection, you'll need access to an Amazon Cognito user pool and the ability to create an access key with the appropriate permissions.

Get Amazon Cognito user pool ID

Go to the Cognito dashboard
Switch to to the region with the user pool you want to connect to UserHub
Note the User pool ID, you'll need it for the Set up connection step

Create AWS access key

Go to the IAM users dashboard
Click Create user to add a new access key
Enter userhub for the User name and click Next
Select Attach policies directly
Search for the AmazonCognitoPowerUser policy name (you can also create a more restrictive custom policy, see the example policy)
Check the checkbox to the left of the policy name and click Next
Click Create user
Search for userhub and click on it
Click the Security credentials tab
Scroll down to the Access key section and click Create access key
Select Third-party service, check the Confirmation checkbox, and click Next
Click Create access key
Note the Access key and Secret access key, you'll need it in the next step

Set up connection

Next, you will need to set up the connection

in the UserHub Admin console.

Go to Connections from the Developers dropdown
Click the Setup button for Amazon Cognito
Enter your Amazon Cognito User pool ID
Enter the Region for your user pool
Enter the Access key ID and Access key secret you created above
Click Save
Make sure the status switches to Active

Make note of the connection ID (e.g. conn_obXdd...), as this will be used in a later step.

Set up Portal callback

Next, you will use Amazon Cognito's sign-in interface to authenticate users linked to the UserHub Portal

Alternatively, you have the option of implementing the Portal callback handler.

Create app for callback

Go to the Cognito dashboard
Click on your User pool name
Click App clients in the navigation menu
Click the Create app client button
Select Traditional web application for Application type
Enter Billing (or whatever you prefer) for Name your application
Enter https://<portal-domain>/signin for the Return URL (you can find this URL in the Admin console
Portal settings)
Click Create app client
Click the Login pages tab
Click Edit in the Managed login pages configuration section
Click Add sign-out URL and enter https://<portal-domain>/signout
Scroll to the bottom of the page and click Save changes
Note the Client ID and Client secret, you'll need it in the next step

Add app settings to connection

Go to Connections from the UserHub Admin console
Developers dropdown
Click Amazon Cognito
Click the Edit connection button
Click Enable Portal sign-in
Enter the Client ID and Client secret you noted above and click Save

You should now be able to open https://<portal-domain>/ in your browser and sign in.

Setting up a Lambda trigger ensures your users are immediately pushed to UserHub when they sign in.

To set up a trigger, you'll need the UserHub Amazon Cognito connection ID (see above) and an Admin API

key scoped to Amazon Cognito.

Alternatively, you have the option of calling report event directly from your app.

Create API key

Go to the Admin console
and click API keys via the Developers dropdown or Tenant settings
Click New API key
Enter Amazon Cognito hook for the Description
Select Admin API for the Type
Don't set an expiration
Click the Integrations dropdown and select Amazon Cognito
Click Create
Note the generated API key (e.g. userhub_admin_agX...), as this token will be used in the next step

Set up trigger

Next, you'll need to set up the trigger in Cognito:

Go to the Cognito dashboard
Click on your User pool name
Click Extensions under Authentication
Click the Add Lambda trigger button
Select Authentication for the Trigger type
Select Post authentication trigger for Authentication
Click the Create Lambda function button
In the new tab, click the Create function button
Select Author from Scratch
Enter userhubSignin for the Function name (or whatever you prefer)
Select Node.js 22.x (or higher) for the Runtime
Select x86_64 for Architecture
Click the Create function button
Enter the following code:
```
const baseUrl = "https://api.userhub.com";

export const handler = async event => {
  try {
    const userId = encodeURIComponent(event.userName);
    const connectionId = process.env.AMAZON_COGNITO_CONNECTION_ID;

    const response = await fetch(
      `${baseUrl}/admin/v1/users/${userId}@${connectionId}:event`,
      {
        method: "POST",
        headers: {
          authorization: `Bearer ${process.env.USERHUB_ADMIN_KEY}`,
          "user-agent": "UserHub-AmazonCognito/1.0",
        },
        data: JSON.stringify({ type: "SIGNIN" }),
        signal: AbortSignal.timeout(2 * 1000),
      },
    );
    if (!response.ok) {
      throw new Error(`${response.status}: ${await response.text()}`);
    }
  } catch (e) {
    console.log(`Failed to report signin to UserHub: ${e}`);
  }

  return event;
};
```
Click the Configuration tab
Click Environment variables from the side menu and the Edit button
Click the Add environment variable button
Enter USERHUB_ADMIN_KEY for the Key
Enter the Admin API key you generated above for the Value
Click Add environment variable again
Enter AMAZON_COGNITO_CONNECTION_ID for the Key
Enter the connection ID you noted in step 2 for the Value (e.g. conn_obXdd...)
Click Save
Click the Code tab
Click the Deploy button
Switch back to the "Add Lambda trigger" browser tab
Click the refresh icon
Select userhubSignin (or whatever you choose) for Assign Lambda function
Click Add Lambda trigger