Post-Deployment (Single Tenant)

📘

Before You Begin

Before you complete these post-deployment tasks, you must complete the deployment procedure.

This page describes the tasks you should perform after you have deployed the Tetra Data Platform (TDP).

You can perform these post-deployment tasks:

  • (Required) Confirm alert email subscriptions
  • (Optional) Determine if you want to disable the [email protected] user and enable Single Sign-On (SSO) using the AWS Cognito service

(Required) Confirm Alert Email Subscription

Alert emails are sent through AWS SNS to the email address you configured during the Data Layer deployment. SNS sends an email with the Subject of "AWS Notification - Subscription Confirmation" and requires that you confirm the subscription. You must click the link in that email for notifications to work properly.

(Optional) Disable the [email protected] User

🚧

Cannot Re-Enable Using the Portal

Once you complete these instructions to disable the [email protected] user, you cannot re-enable the [email protected] user in the portal. However, you can re-enable the [email protected] user by updating the user's status directly in the database.

The [email protected] user account is created by default and can access all organizations in the setup. For security issues, you may want to disable this user account.

To disable this user account:

  1. Log in with the [email protected] user account.
  2. Switch to the TetraScience organization.
  3. Locate the [email protected] user from the user list.
  4. Disable the [email protected] user account. You are logged out automatically and cannot log back in with that user account.

(Optional) Enable Single Sign-On with the AWS Cognito Service

To enable SSO, the Tetra Data Platform uses the AWS Cognito service to connect with your identity provider.

To enable SSO, you use the AWS Cognito service to:

Create a User Pool

  1. Navigate to AWS Cognito and click Manage User Pools.
  2. Click Create a user pool in the top right corner.
  3. Enter a pool name in the Pool name field, for example: ts-demo. Click Step through settings to continue.
  4. From the Attributes page:
    • In the Which standard attributes do you want to require? section, select these attributes as required: email, family name, and given name.
    • In the Do you want to add custom attributes? section, add a new custom string attribute using these settings: Type = string, Name = groups, Min length = 1, Max length = 2048, and the Mutable check box is selected.
    • Click Next step to continue.
  5. From the Policies page, accept the default settings (unless your company enforces other password policy rules). Click Next step to continue.
  6. From the MFA and verifications page, accept the default settings (unless MFA is required). Click Next step to continue.
  7. Continue to accept the default settings for these pages: Message customizations, Tags, and Devices. Click Next step to continue to the App clients page.
  8. From the App clients page, select Add an app client. Enter a name in the App client name field (for example, tdp). Accept the default settings unless you require a different configuration.
  9. Select Set attribute read and write permissions. For both the Readable Attributes and Writable Attributes attribute columns, make sure to select these attributes in each: email, family name, given name, and custom:groups.
  10. Click Create app client to create the app client. A message displays indicating that the app client id and secret will be available after you save this user pool. Click Next step to continue.
  11. From the Triggers page, accept the default settings and click Next step to continue.
  12. From the Review page, select Create pool at the bottom of the page. Two new menu sections display on the left side of the page: App Integration and Federation:
User Pools - Menu ItemsUser Pools - Menu Items

User Pools - Menu Items

To continue the post-deployment instructions and the AWS Cognito configuration, go to Configure the App Client and Domain Name.

Configure the App Client and Domain Name

After you create a user pool, you configure the app client:

  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:
    • Enter a URL in the Callback URL(s) field, for example: <platform_url>/login/sso.
    • Enter a URL in the Sign out URL(s) field, for example: <platform_url>/logout.
    • In the OAuth 2.0 section:
      • 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. Click Save changes to continue.

To continue the post-deployment instructions and the AWS Cognito configuration, go to Configure the Identity Provider and Enable SAML.

Configure the Identity Provider and Enable SAML

To configure the identity provider and enable SAML:

  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:
SAML Attribute MappingSAML Attribute Mapping

SAML Attribute Mapping

  1. You must provide the actual name of the attribute that identity provider sends to AWS Cognito. In the User pool attribute column, select the AWS Cognito attributes.
  2. Define mappings for the four attributes that you used: given name, family name, custom:groups and email.
  3. Click Save changes.
  4. From the left side of the page, select App client settings under the App Integration menu section.
  5. 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.
  6. 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 the post-deployment instructions, go to Set Up Environment Variables.

Set Up Environment Variables

The Tetra Data Platform uses AWS Cognito to enable users to log in to the TDP using Single Sign-On (SSO). With the current TDP release (v3.1.0/v3.1.2), SSO works only in single-tenant deployments because environment variables ts-service-user-org and ts-service-web services were used for implementation.

The environment variables using the Joi schema are described 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')
}

You can define these variables using a AWS CloudFormation template or by using AWS Systems Manager. This table describes where to find attribute values and what their corresponding parameter names should be in AWS Systems Manager.

Attribute Name

Where to Find the Attribute

AWS Systems Manager Parameter Store Location

SSO_DOMAIN

Navigate to:
Cognito > App Integration > Domain name

/tetrascience/{environment}/ECS/ts-service-user-org/SSO_DOMAIN

/tetrascience/{environment}/ECS/ts-service-web/SSO_DOMAIN

SSO_CLIENT_ID

Navigate to:
Cognito > General Settings > App Clients > App client Id

/tetrascience/{environment}/ECS/ts-service-user-org/SSO_CLIENT_ID

/tetrascience/{environment}/ECS/ts-service-web/SSO_CLIENT_ID

SSO_REDIRECT_URI

Navigate to:
Cognito > App Integration > App Client Settings > Callback URL

/tetrascience/{environment}/ECS/ts-service-user-org/SSO_REDIRECT_URI

SSO_CLIENT_SECRET

Navigate to:
Cognito > General Settings > App Clients > App client Secret

/tetrascience/{environment}/ECS/ts-service-user-org/SSO_CLIENT_SECRET

Set this parameter as SecureString.

SSO_GROUPS_ATTRIBUTE

Navigate to:
Cognito > General Settings > Attributes > Custom Attributes

/tetrascience/{environment}/ECS/ts-service-user-org/SSO_GROUPS_ATTRIBUTE

After you create AWS Systems Manager parameters, you must restart both ts-service-user-org and ts-service-web services. To continue the post-deployment instructions, go to Set Organization to Enable SSO.

Set Organization to Enable SSO

Initially, a System Admin user or Organization Admin user must enable SSO for the organization, and then configure an active directory (AD) group to the Tetra Data Platform role mapping.

📘

Tetra Data Platform Quick Reference

To learn more about TDP and its basic features, see:

  1. Log in to the Tetra Data Platform as user with an Organization or System Admin account.
  2. Navigate to Account > Organization.
  3. Select Single Sign-on.
  4. From the Single Sign-on configuration page, define the group mappings between the TDP roles on the left (Admin role, Member role, and Read-only role) and the AD groups on the right.
  5. Click Save when completed.

If a user belongs to certain AD group and that group is mapped to a TDP role, after the user logs in, the user will be added to the organization that matches the TDP role. All group information is stored in a user object in AD and in an attribute that is known and defined as the SSO_GROUPS_ATTRIBUTE environment variable. This attribute can have more than one value, however, when a user logs in, the TDP will select the highest role available.

Sample SAML Assertion

This is a sample SAML assertion returned from an identity provider:

...
<saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml:NameID>
    ...
</saml:Subject>
...
<saml:AttributeStatement>
    <saml:Attribute Name="email">
        <saml:AttributeValue>[email protected]</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="family_name">
        <saml:AttributeValue>Bar</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="given_name">
        <saml:AttributeValue>Foo</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute Name="custom:groups">
        <saml:AttributeValue>admins</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>
...

(Optional) Deploy IoT Layer

If you would like to deploy the IoT Layer, see the instructions here.


Did this page help you?