# 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](https://docs.tonic.ai/app/admin/tonic-user-access/single-sign-on/saml).

## AWS configuration

You complete the following configuration steps within IAM Identity Center.

### Create the SAML application

On the **Applications** page, click **Add application**.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FpGBtjurKQTy4d1XfrTel%2Fimage.png?alt=media&#x26;token=b82c77fe-4640-4e43-8c60-efa2baad1e79" alt=""><figcaption><p>Applications page in IAM Identity Center</p></figcaption></figure>

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**.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FDScnc71ElJSjuq2N91o6%2Fimage.png?alt=media&#x26;token=7d52fb2e-f706-4a28-bd0c-f646178414a5" alt=""><figcaption><p>Add a custom SAML 2.0 application on the Add application page</p></figcaption></figure>

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

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FIEmBMnb9rYQoo4g2nWrU%2Fimage.png?alt=media&#x26;token=fa10a24e-3ccd-4fa1-b778-2cce4d012eaf" alt=""><figcaption><p>Configure application page with application name and description fields</p></figcaption></figure>

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.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FvwA7xFjV7Y7OKDcW6XlO%2Fimage.png?alt=media&#x26;token=ec97efa0-7e2e-47b8-9ce5-abaf0f15c695" alt=""><figcaption><p>IAM Identity Center metadata</p></figcaption></figure>

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

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2F0wNimXEWsJCpIbdrrUJf%2Fimage.png?alt=media&#x26;token=ade5ab68-1077-47b5-9002-0976a53ab306" alt=""><figcaption><p>Application properties for the SAML application</p></figcaption></figure>

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`.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FFf1NzxVXCTzIFqiJ3zJd%2Fimage.png?alt=media&#x26;token=d3cd4289-d25f-4113-a5a4-a96eea6e1f4f" alt=""><figcaption><p>Application metadata for the SAML application</p></figcaption></figure>

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**.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2Faxz9ndE2wvj3X10mTkjy%2Fimage.png?alt=media&#x26;token=867c6ca3-b353-4e50-812e-6d01d307e568" alt=""><figcaption><p>Actions menu for the Structural application</p></figcaption></figure>

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}`

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2F5bBw7xblduVt2cjDzt5F%2Fimage.png?alt=media&#x26;token=bbf2131a-1e47-425e-85aa-a6918894f019" alt=""><figcaption><p>Structural attribute mappings</p></figcaption></figure>

## Structural configuration

In the Structural web server container, set the following [Structural environment settings](https://docs.tonic.ai/app/admin/environment-variables-setting):

* `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.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FG0P8soj9UCsPhUO6Izr8%2Fimage.png?alt=media&#x26;token=4e504207-472c-4006-9353-2f338194c994" alt=""><figcaption><p>Getting the Identify store ID from IAM Identity Center</p></figcaption></figure>

* `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 [sso-limit-groups](https://docs.tonic.ai/app/admin/tonic-user-access/single-sign-on/sso-limit-groups "mention").

## IAM role configuration

IAM Identity Center makes the `${user:groups}` attribute available. However, it is not an [officially supported attribute](https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html#supportedssoattributes). 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](https://docs.tonic.ai/app/admin/environment-variables-setting):
  * `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": "*"
        }
    ]
}
```