Amazon Cognito

Follow these guidelines to configure Amazon Cognito as an OAuth2 provider for your instance of Toolbox Enterprise.

Add Toolbox Enterprise to Amazon Cognito

To let your organization's users sign in to Toolbox Enterprise using Amazon Cognito, you need to add the application to the user pool configuration. For more details, refer to the official AWS documentation.

Create a new user pool

You can use an Amazon Cognito user pool to create and manage a user directory for Toolbox Enterprise. This allows users to sign up and sign in to the application.

Access the Amazon Cognito console.
Select User Pools.
In the top-right corner of the page, click Create a user pool.

Make sure the Federated identity providers checkbox is deselected.
In the Cognito user pool sign-in options section, select User name and Email.
Click Next.

Step 2: Configure security requirements

In the Password policy section, configure the password policy to meet the needs of your organization.
In the Multi-factor authentication section, configure multi-factor authentication to meet the needs of your organization.
In the User account recovery section, enable the self-service account recovery and select Email only as the delivery method for user account recovery messages.
Click Next.

In the Self-service sign-up section, deselect the Enable-self-registration checkbox.
In the Attribute verification and user account confirmation section, select the Allow Cognito to automatically send messages to verify and confirm checkbox.
In the Attributes to verify section, choose Send email message, verify email address.
In the Required attributes section, select given_name from the Additional required attributes drop-down list.
Click Next.

Step 4: Configure message delivery

In the Email section, select Send email with Cognito as a value of the Email provider field.
Click Next.

Step 5: Integrate your app

In the User pool name section, specify the name for your user pool.
In the Hosted authentication pages section, select the Use the Cognito Hosted UI checkbox.
In the Domain section, select the Use a Cognito domain checkbox and enter the domain prefix.
In the Initial app client section, select Public client as an app type. In the App client name field, specify Toolbox Enterprise.
In the Client secret section, select Generate a client secret.
In the Allowed callback URLs field, specify the redirect URL for your Toolbox Enterprise Server: https://<toolbox_enterprise_server_domain.com>/api/login/authenticated.
Expand the Advanced app client settings section and select the following scopes in OpenID Connect scopes: OpenID, Email, Profile.
Click Next.

Step 6: Review and create

Review the user pool details and click Create user pool.

After creating a user pool, save the following data that you will later need to configure the Toolbox Enterprise Server:

Client ID
Client secret
Login URL
Token URL
JWT certs URL

Open the user pool details and find the User pool ID value. You will need it for the JWT certificate URL: https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json.

To obtain Login and Token URLs, go to the App integration tab, and copy the Cognito domain. As a result, you will have the following URLs:

Login URL: https://<cognito domain>/oauth2/authorize
Token URL: https://<cognito domain>/oauth2/token

Scroll down to the App clients and analytics section and click the Toolbox Enterprise app name. There, copy the Client ID and Client secret.

Configure Amazon Cognito in application.yml

After adding Toolbox Enterprise to Amazon Cognito, you need to configure your application.yaml file and specify the OAuth2 provider properties there:

            tbe:
              auth:
                login-url: "https://<cognito domain>/oauth2/authorize"
                token-url: "https://<cognito domain>/oauth2/token"
                jwt-certs-url: "https://cognito-idp.<Region>.amazonaws.com/<userPoolId>/.well-known/jwks.json"
                client-id: "your_identifier"
                client-secret: "your_password"
                required-scopes: [ "email", "openid", "profile" ]
                root-admin-emails:
                    - "your.company.admin@example.com"
        

login-url: Provide a URL for logging in via Amazon Cognito.
token-url: Provide a URL for obtaining an authorization token on Amazon Cognito's side.
jwt-certs-url: Specify a URL to the JSON Web Key (JWK) set that is used to validate JSON Web Tokens (JWT).
client-id: Specify the public identifier for Toolbox Enterprise used Amazon Cognito.
client-secret: Specify the value of the client secret for Toolbox Enterprise.
required-scopes: Set the value to [ "profile", "email", "openid"].
root-admin-emails: List emails of users that will receive admin rights.

Last modified: 16 April 2024