Enable Single Sign-On

📘

Before You Begin

Before you enable single sign-on (SSO) as a Site Admin, you must deploy the Tetra Data Platform (TDP) by using either one of these deployment options: Customer Hosted and Tetra Managed or Customer Hosted. If you choose the Tetra Hosted deployment option, then TetraScience will enable SSO for you, if you want. For more information, see Tetra Data Platform Deployment Options.

Single sign-on (SSO) is an optional feature in the Tetra Data Platform (TDP) that uses the Amazon Cognito service to connect with your identity provider (IdP) and manage authenticated users.

📘

NOTE

SSO is configured at the tenant level and is applied to all organizations within a single TDP tenant. You can’t set up SSO for one organization within a tenant without applying SSO to all of the organizations within that tenant.

To activate SSO for a TDP tenant, you must do the following with Site Admin permissions:

• Set up the Identity Provider
• Use the Amazon Cognito Service to create a user pool
• Use the Amazon Cognito Service to configure the Cognito domain and app client
• Configure the app client and domain name
• Configure the identity provider and enable SAML
• Set up environment variables
• Configure your organizations to enable SSO

Set Up the Identity Provider

Configure an identity provider of your choice.

Create an Amazon Cognito User Pool

The user pool manages the overhead of handling the tokens that are returned from Security Assertion Markup Language (SAML) IdPs.

To create a user pool, do the following:

1. Navigate to the Amazon Cognito console and select User pools.

2. In the top-right corner of the page, select Create a user pool.

3. Choose the Configure sign-up experience tab, and then configure the providers that are available to users when they sign in by doing the following:

   a. To have your users sign in through a federated third-party IdP, select Federated identity providers.
   b. To set email as the required attribute used for the user pool sign-in, select Email. This determines how new users will be prompted to verify their identities when signing in to the TDP.
   c. Choose Save changes.

4. From the Sign-up experience tab, do the following:

   a. Locate Federated sign-in and select Add an identity provider. You must select at least one third-party IdP. Select SAML as the IdP:

b. For Self-service sign-up, make sure that the Enable self-registration option is deactivated (unchecked). New users must be created by administrative API actions using IAM API credentials or by sign-in with federated providers.
c. In the Custom attributes - optional section, select Add custom attributes.
d. Add a new custom attribute with the following:
- Name = groups
- Type = String
- Mutable is selected (provides users permission to change the value of a custom attribute after they set the initial value):

e. Choose Save changes.

5. Set up SAML configuration with the user pool by using the values provided by the third-party IdP:

a. For Provider name, enter SAML.
b. Select the Add sign-out flow option to have Amazon Cognito send signed sign-out requests to your provider when a user logs out.

📘

Sign-Out Flow Option

If you selected this option and your SAML IdP expects a signed logout request, then you must also configure the signing certificate provided by Amazon Cognito with your SAML IdP. The SAML IdP will process the signed logout request and sign out your user from the Amazon Cognito session.

You must configure your SAML IdP to send sign-out responses to the https://<*your Amazon Cognito domain*>/saml2/logout endpoint that is created when you configure the hosted TDP UI. The saml2/logout endpoint uses POST binding.

c. Select Enter metadata document endpoint URL as the metadata document source, and then enter that public URL in the field. This allows Amazon Cognito to refresh metadata automatically. Typically, metadata refresh occurs every six hours, or before the metadata expires (whichever is earlier).
d. Map your required attributes in your user pool to the equivalent SAML provider attributes. Each attribute you add must be mapped to a SAML attribute.
e. Click Save changes.

Configure the Amazon Cognito Domain and App Client

To configure the Amazon Cognito domain and app client, do the following:

1. In AWS Cognito, select App clients under the General settings menu section.
2. The App client id now displays below the pool name. Copy the App client id value to a text editor. You will use this value as the environment variable for the SSO_CLIENT_ID.
3. Select Show Details. The App client secret displays on the page. Copy the App client secret value to a text editor. You will use this value as the environment variable for the SSO_CLIENT_SECRET.
4. From the left side of the page, select App client settings under the App integration menu section.
5. From the App client settings page, do the following:
   a. Enter a URL in the Callback URL(s) field, for example: <platform_url>/login.
   b. Enter a URL in the Sign out URL(s) field, for example: <platform_url>/logout.
   c. In the OAuth 2.0 section, do the following:
   • In the Allowed OAuth Flows section, select Authorization code grant.
   • In the Allowed OAuth Scopes section, select: email, openid, and profile.
   • Click Save changes to continue.
6. From the left side of the page, select Domain name, under the App integration menu section.
7. Enter the domain name in the Domain prefix field, for example: ts-demo-tetrascience. Select Check availability. If the domain is available, then a message displays at the top of the page confirming its availability.
8. Copy the full URL address to a text editor. You will use this value as the environment variable for the SSO_DOMAIN.
9. Choose Save changes to continue.

To continue with the SSO process and configure the AWS Cognito service, go to Configure the Identity Provider and Enable SAML.

Configure the Identity Provider and Enable SAML

To configure the identity provider and enable SAML, do the following:

1. In AWS Cognito, select Identity providers under the Federation menu section.
2. Select SAML. You need to define the attributes (email, family name, given name, and custom:groups) that you want to export in the identity provider's software (for example, Duo, Idaptive, Keycloak, and so on).
3. The identity provider's software should allow the export of SAML configuration as either an XML file, or with a URL address. Click Select file to upload the XML file, or enter the URL address in the Provide metadata document endpoint URL field.
4. Click Create provider.
5. From the left side of the page, select Attribute mapping under the Federation menu section.
6. Select the SAML tab. This is a configuration example for Duo:

7. You must provide the actual name of the attribute that the identity provider sends to AWS Cognito. In the User pool attribute column, select the AWS Cognito attributes.
8. Define mappings for the four attributes that you used: given name, family name, custom:groups and email.
9. Click Save changes.
10. From the left side of the page, select App client settings under the App Integration menu section.
11. In the Enabled Identity Providers section, select the identity provider you just created (for example, Duo). Verify that all of the other values that you previously defined also display: Callback URL(s), Sign out URL(s), and OAuth 2.0 selections.
12. Click Save changes.

📘

Identity Provider Managed by a Different Team

If your identity provider is managed by a different team, then you must provide these AWS Cognito user pool parameters and values to them:

• Assertion Consumer Service (ACS) URL - Locate the domain name under the the App Integration menu section, and then add this suffix: https://<domain>/saml2/idpresponse
• URN - Locate the Pool Id under the General settings menu section, and then add this prefix: urn:amazon:cognito:sp:<Pool Id>

To continue with the SSO process, go to Set Up Environment Variables.

Set Up Environment Variables

The TDP uses Amazon Cognito to help users to log in to the TDP using single sign-on (SSO). With TDP release (v3.1.0/v3.1.2), SSO works only in Customer Hosted deployments, because environment variables ts-service-user-org and ts-service-web services were used for implementation.

You can define these variables by using a AWS CloudFormation template or by using AWS Systems Manager.

The following environment variables use the Joi schema and are described by using example values:

• ts-service-user-org

{
  SSO_DOMAIN: Joi.string().optional(), // value configured in AWS Cognito (for example, https://ts-dev.auth.us-east-2.amazoncognito.com)
  SSO_REDIRECT_URI: Joi.string().optional(), // TDP SSO login page to be redirected from AWS Cognito (for example, https://tetrascience-dev.com/login/sso)
  SSO_CLIENT_ID: Joi.string().optional(), // AWS Cognito client ID - public available (for example, 5tus3nieu9sgv02aaq7f28hhir)
  SSO_CLIENT_SECRET: Joi.string().optional(), // AWS Cognito client secret - hidden (for example, 1c0fdvv63caat3e7r2v9unuj3fl5k344j1pqpfc0lkhdacc8k1i3)
  SSO_GROUPS_ATTRIBUTE: Joi.string() // AWS Cognito client groups mapping
    .optional()
    .default('custom:groups')
}

• ts-service-web

{
  SSO_DOMAIN: Joi.string() // value configured in AWS Cognito (for example, https://ts-dev.auth.us-east-2.amazoncognito.com)
    .allow('')
    .optional(),
  SSO_CLIENT_ID: Joi.string() // AWS Cognito client ID - public available (for example, 5tus3nieu9sgv02aaq7f28hhir)
    .allow('')
    .optional(),
  LOGIN_REDIRECT_PATH: Joi.string() // redirect path for login (for example, /login/sso)
    .optional()
    .allow('', null)
    .empty(['', null])
    .default('/login')
}

AWS Systems Manager attributes

The following table describes where to find attribute values and what their corresponding parameter names should be in AWS Systems Manager.

📘

NOTE

After you create AWS Systems Manager parameters, you must restart both ts-service-user-org and ts-service-web services.

Configure Your Organizations to Enable SSO

After setting up SSO at the tenant level, you must assign SSO roles for each organization within that tenant. Then, configure an active directory (AD) group to the Tetra Data Platform (TDP) role mapping.

For instructions, see Assign Single Sign-On (SSO) Roles in an Organization.