AWS IAM Identity Center

Use these instructions to set up AWS IAM Identity Center as your SSO provider for Tonic Structural.

This integration uses a combination of SAML 2.0 and the AWS Identity Store API to resolve group names. If you do not require groups, you can also use the SAML integration.

AWS configuration

You complete the following configuration steps within IAM Identity Center.

Create the SAML application

On the Applications page, click Add application.

Applications page in IAM Identity Center

On the Add application page, under Select application type:

1. Click I have an application I want to set up.
2. Click SAML 2.0.
3. Click Next.

Add a custom SAML 2.0 application on the Add application page

On the Configuration application page, in the Display name field, enter a name for the application.

Configure application page with application name and description fields

Under IAM Identity Center metadata, copy the IAM Identity Center SAML metadata file URL.

You set this as the value of a Structural environment setting.

Alternatively, you can download the file to provide in your Structural configuration. However, the URL is preferred.

IAM Identity Center metadata

Under Application properties, set Application start URL to your Structural URL.

Application properties for the SAML application

Under Application metadata:

1. Click Manually type your metadata values.
2. Set Application ACS URL to your Structural URL followed by /api/sso/samllogin.
3. Set Application SAML audience to Tonic.

Application metadata for the SAML application

To create the application, click Submit.

Configure attribute mappings for Structural

Next, you configure the attribute mappings that Structural requires.

For your new Structural application, click Actions, then select Edit attribute mappings.

Actions menu for the Structural application

On the Attribute mappings tab, set up the following mappings:

• Map Subject to ${user:subject}
• Map GivenName to ${user:givenName}
• Map Email to ${user:email}
• Map FamilyName to ${user:familyName}
• Map Groups to ${user:groups}

Structural attribute mappings

Structural configuration

In the Structural web server container, set the following Structural environment settings:

• TONIC_SSO_PROVIDER - Set to AWS
• TONIC_SSO_IDENTITY_PROVIDER_ID - Set to the value of Identity store ID from the Settings page in IAM Identity Center.

Getting the Identify store ID from IAM Identity Center

• TONIC_SSO_SAML_IDP_METADATA_XML_URL- Set to the IAM Identity Center SAML metadata file URL that you saved earlier. You can alternatively provide the file directly. To do this:

  1. base64 encode the contents of the downloaded metadata XML file.
  2. Set TONIC_SSO_SAML_IDP_METADATA_XML_BASE64 to the base64 encoded string.
• TONIC_SSO_SAML_ENTITY_ID - The entity ID to use to send SAML requests from Structural. If this is not set, the entity ID is determined from the identify provider metadata. You also use this as the value of Audience in the SAML provider configuration.
• TONIC_SSO_GROUP_FILTER_REGEX - Identifies the allowed groups for Structural. For details, go to Synchronizing SSO groups with Structural.

IAM role configuration

IAM Identity Center makes the ${user:groups} attribute available. However, it is not an officially supported attribute. The values returned are group ID GUIDs instead of group names.

Structural uses the Identity Store API to enrich the group attribute that SAML provides with the group name.

Structural must have permission to use the identity store API to retrieve the group information.

On a self-hosted instance, Structural gets the AWS credentials from the environment. Structural uses either:

• The credentials set in the following environment settings:

  • TONIC_AWS_ACCESS_KEY_ID - An AWS access key that is associated with an IAM user or role.
  • TONIC_AWS_SECRET_ACCESS_KEY - The secret key that is associated with the access key.
  • TONIC_AWS_REGION - The AWS Region to send the authentication request to.
• The credentials for the IAM role on the host machine.

The policy that is associated with your IAM role or IAM user must allow the identitystore:DescribeGroup action. Your policy should be similar to:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "identitystore:DescribeGroup",
            "Resource": "*"
        }
    ]
}