What is Amazon Cognito?

Amazon Cognito can add user sign-up and sign-in features and control access to your web and mobile applications. Amazon Cognito provides functionalities that scale to millions of users, and offers advanced security features to protect your customers and business. Amazon Cognito also supports various compliance regulations.

In Countly, Amazon Cognito provides both authentication and authorization. It verifies users' identities during the login process and assigns them specific roles and permissions that determine what they are allowed to do within the system. To deploy this, contact your account manager.

Getting Started with Amazon Cognito

Step 1: Configuration file changes

After you upload and extract the AWS Cognito feature to the feature directory in all Countly servers, you need to copy config.sample.js into config.js within the Cognito directory.

Afterwards, modify the following values inside the config.js file. All the values are of string type.

• baseUrl, the URL that you access Countly from

• globalAdminGroup, global admin group id for Countly
• encryptionKey, arandom encryption key, will be used to encrypt the redirection URL payload

Step 2: Enable AWS Cognito feature

In order to enable the feature go to Management > Feature Management and click on the enable switch for AWS Cognito feature. Then apply your changes.

If your deployment includes multiple Countly servers remember to turn on “Sync feature states” from Management > Settings > API or manually enable the feature from the command line on each server. Also, note that configuration in Step 1 needs to be done for all instances regardless of enabling “Sync feature states” configuration.

When the AWS Cognito feature is enabled, Countly will bypass its regular authentication and user management, and authentication can only be done via the new API endpoint the AWS Cognito feature exposes.

Step 3: Using the new login path

Once you enable the AWS Cognito feature and make the configuration changes, you are ready to use the new login path /cognito-login.

This new path accepts the following headers via a GET request.

• sub, will be used as an internal Countly user identifier (required).

• email, will be used as user email (required).

• custom-role, needs to contain group id that the user should belong to (required).

• name, full name of the user (optional).
• username, the user name of the user, if not present email will be used instead (optional).

In the success case (HTTP 200), this new path returns a URL parameter inside a JSON object. You need to redirect the user to the given URL value in order to log her into the dashboard.

In order to get a successful response, you need to send a valid custom-role header value to this path (either the global admin group id you configured in Step 1 or a group id for a group you created via Management > Users) together with the other required headers.

In the error case, this new path will return an HTTP 400 or 422 error code.