One-time setup of a direct IAM federation application with ADFS - Amazon IAM Identity Center
PrerequisitesPlan your Active Directory group naming conventionAmazon configurationActive Directory configurationTest the configurationUpdate default SAML assertion endpoint in ADFS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

One-time setup of a direct IAM federation application with ADFS

This guide describes the one-time setup process for configuring direct IAM federation with ADFS to enable emergency access to Amazon Web Services accounts when IAM Identity Center is unavailable.

Prerequisites

If you plan to configure ADFS with Amazon Managed Microsoft AD, we recommend that you first configure Multi-Region replication and continue with the following steps in the additional Region and not in the primary Region for resiliency.

Plan your Active Directory group naming convention

Create AD groups using a specific naming pattern that enables automated matching between group names and Amazon IAM roles.

Group naming format: AWS-<AccountNumber>-<RoleName>

For an illustration, see the emergency account in the diagram under How to design emergency role, account, and group mapping . When a user is assigned to this group, they are granted access to the EmergencyAccess_Role1_RO role in account 123456789012. If a user is associated with multiple groups, they see a list of available roles by Amazon Web Services account and can choose which role to assume.

Amazon configuration

The complete setup includes configurations in an emergency access account and the workload accounts. For an illustration of the overall setup, see How to design emergency role, account, and group mapping .

  1. Create a SAML identity provider

  2. Create emergency access roles

  3. Configure workload account roles

Create a SAML identity provider

In the emergency access account, create a SAML identity provider in IAM by following the steps in Create a SAML identity provider in IAM. Download the required metadata from your ADFS server:

https://<yourADFSserverFQDN>/FederationMetadata/2007-06/FederationMetadata.xml

Create emergency access roles

Create emergency access roles in the emergency account using SAML 2.0 Federation as the trusted entity type. Select the SAML 2.0 provider you created in the previous step.

Considerations:

  • Include all Regions where you operate — select every Region in which you have active workloads to ensure federation remains available during a Regional disruption.

  • Configure at least one additional Regional endpoint, even if you operate in a single Region — for example, if you operate only in us-east-1, add us-west-2 as a secondary endpoint. You can fail over your IdP to the us-west-2 SAML sign-in endpoint and still access your us-east-1 resources, even without any workloads in us-west-2.

  • Enable both the non-regional endpoint and regional endpoints — Although the non-regional endpoint (https://signin.aws.amazon.com/saml) is highly available, it is hosted in a single Amazon Web Services Region, us-east-1, while regional endpoints (https://<region>.signin.aws.amazon.com/saml) improve resiliency by reducing dependency on a single global endpoint.

Configure trust policy

Refer to One-time setup of a direct IAM federation application in Okta for an example trust policy with multiple sign-in regional endpoints. Replace the sample regional endpoints and SAML provider ARNs with yours.

Configure permissions policies

Refer to One-time setup of a direct IAM federation application in Okta for an example permissions policy that you attach to the emergency access roles.

Configure workload account roles

For the workload account roles, configure a custom trust policy that allows the emergency access roles in the emergency access account to assume them. Refer to One-time setup of a direct IAM federation application in Okta for an example trust policy, where account 123456789012 is the emergency access account.

Active Directory configuration

The following steps describe how to configure Active Directory and ADFS for emergency access.

  1. Create groups

  2. Create a relying party

  3. Create claim rules

Create groups

Create emergency groups in Active Directory according to the naming convention described earlier (for example, AWS-123456789012-EmergencyAccess_Role1_RO). Assign users to these groups through your existing provisioning mechanisms.

Create a relying party

ADFS federation requires a relying party configuration. The relying party is Amazon Security Token Service (Amazon STS), which outsources authentication to ADFS as the identity provider.

  1. In the ADFS Management console, use the Action menu and select Add Relying Party Trust. Select Claims aware when adding a relying party.

  2. For federation metadata, enter the Metadata URL from the identity provider metadata info on the IAM console. For example:

    https://signin.aws.amazon.com/static/saml/SAMLSPXXXXXX/saml-metadata.xml

  3. Set the display name for the relying party (for example, Amazon Account Access) and then choose Next.

  4. Select who you want to enable to access Amazon. You can select specific groups and define requirements like MFA.

  5. Choose Close on the Finish page to complete the Add Relying Party Trust Wizard. Amazon is now configured as a relying party.

Create claim rules

ADFS uses Claims Rule Language to issue and transform claims between claims providers and relying parties. You need to create four claim rules: NameId, RoleSessionName, Get AD Groups, and Roles for Amazon Access.

Right-click on the relying party and then choose Edit Claim Issuance Policy. Choose Add Rule to add rules.

1. NameId

  1. Select Transform an Incoming Claim and then choose Next.

  2. Use the following settings:

    • Claim rule name: NameId

    • Incoming claim type: Windows Account Name

    • Outgoing claim type: Name ID

    • Outgoing name ID format: Persistent Identifier

    • Pass through all claim values: checked

  3. Choose OK.

2. RoleSessionName

  1. Choose Add Rule.

  2. In the Claim rule template list, select Send LDAP Attributes as Claims.

  3. Use the following settings:

    • Claim rule name: RoleSessionName

    • Attribute store: Active Directory

    • LDAP Attribute: E-Mail-Addresses

    • Outgoing Claim type: https://aws.amazon.com/SAML/Attributes/RoleSessionName

  4. Choose OK.

3. Get AD Groups

  1. Choose Add Rule.

  2. In the Claim rule template list, select Send Claims Using a Custom Rule and then choose Next.

  3. For Claim Rule Name, enter Get AD Groups, and then in Custom rule, enter the following:

    c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> add(store = "Active Directory", types = ("http://temp/variable"), query = ";tokenGroups;{0}", param = c.Value);

    This custom rule uses a script in the claim rule language that retrieves all the groups the authenticated user is a member of and places them into a temporary claim named http://temp/variable.

    Note

    Ensure there's no trailing whitespace to avoid unexpected results.

4. Role Attributes

  1. Choose Add Rule.

  2. In the Claim rule template list, select Send Claims Using a Custom Rule and then choose Next.

  3. For Claim Rule Name, enter Roles, and then in Custom rule, enter the following:

    c:[Type == "http://temp/variable", Value =~ "(?i)^AWS-([\d]{12})"]
=> issue(Type = "https://aws.amazon.com/SAML/Attributes/Role", Value = RegExReplace(c.Value, "AWS-([\d]{12})-", "arn:aws:iam::$1:saml-provider/<ADFS>,arn:aws:iam::$1:role/"));

    This custom rule uses regular expressions to transform each of the group memberships of the form AWS-<Account Number>-<Role Name> into the IAM role ARN and IAM federation provider ARN form that Amazon expects.

    Note

    In the example rule language above, ADFS represents the logical name given to the SAML identity provider in the Amazon identity provider setup. Change this based on the logical name you chose in the IAM console for your identity provider.

Test the configuration

Test that the solution works by authenticating at https://<yourADFSserverFQDN>/adfs/ls/IdpInitiatedSignOn.aspx. Select the name of the relying party you created from the dropdown list of the sites.

Update default SAML assertion endpoint in ADFS

Important

When configuring relying party trust in ADFS, the SAML Assertion endpoint defaults to https://signin.aws.amazon.com/ which is not a global endpoint and is located in us-east-1. We recommend that you modify the default endpoint to a regional endpoint different from where your IAM Identity Center is configured for resiliency. For example, if your IAM Identity Center is deployed in us-east-1 and you also operate in us-west-2, change the default SAML Assertion consumer endpoint to https://us-west-2.signin.aws.amazon.com/saml.

  1. Choose Properties on the relying party trust and go to the Monitoring tab. Clear the checkbox Automatically Update relying party.

  2. Go to the Endpoints tab, select your preferred sign-in endpoint, and choose Edit.

  3. Select the checkbox Set the trusted URL as default. Choose OK and Apply for the setting to take effect.

Note

Most IdPs enable you to keep an application integration deactivated until required. We recommend that you keep the direct IAM federation application deactivated in your IdP until required for emergency access.