Choose Your Own SAML Adventure: A Self-Directed Journey to AWS Identity Federation Mastery

Use SAML attributes to enforce role assumption conditions, a.k.a. MFA-for-SAML (Microsoft variant)

When you use SAML federation with AWS, the Identity Provider (IdP) is solely responsible for the authentication and coarse grained authorization of users. As we've covered already during this workshop, this model is tremendously beneficial in a large number of ways. However, it does preclude the use of a small number of AWS features, most notably the ability to use AWS Multi-Factor Authentication. Many customers use AWS MFA as a simple best practice that adds an extra layer of protection on top of username and password authentication, and enjoy the benefits of this higher level of assurance. What's important to note however, is that what's precluded is only the use of AWS MFA, not MFA in general. You can (and should) require the use of your own MFA solution within your IdP, particularly for the set of users who are authorized for highly privileged AWS roles. AWS is then able to consume this additional context in the form of additional SAML assertion attributes, and use these attributes as required conditions for IAM role assumption. These two elements, customer side MFA & AWS role assumption conditions, combine to give you the desired elevated level of assurance.

In this advanced use case, you will walk through how to implement additional role assumption conditions within AWS that can be used to ensure that these types of conditions (e.g. multi-factor authentication) have been met. Since the specific MFA configurations are highly dependent on your choice of MFA provider and are time prohibitive, this exercise uses an Active Directory attribute as a surrogate for an actual MFA implementation. This approach allows us to focus on the configurations necessary within the IdP and the AWS IAM role assumption conditions. However, towards the conclusion of this use case, we'll show you the specific modifications necessary to adapt what you've learned to an actual MFA implementation. As a side benefit of this surrogate approach, we're teaching you a more generic implementation of the concept; how to pass additional information about your users through the IdP and use that information within AWS.

Prerequisites

The following list identifies the prerequisites for this exercise. If you have not completed these tasks, please take the time to do so now.

• Successful completion of all steps from the Microsoft version of the first hour exercise. If you are having trouble with the first hour exercise, please seek help from one of the AWS workshop facilitators.

Configuring the MFA surrogate attribute

As described above, you will use the Active Directory attribute EmployeeType as a surrogate for MFA authentication during this exercise. You will set this attribute on both federated users, bob and alice, as follows:

• bob == LowTrust (representing a user authenticated with username and password only).
• alice == HighTrust (representing a user authenticated with a customer MFA solution).

Login to your Domain Controller via RDP

To get started, log in using RDP to your Domain Controller (DC) instance using the public IP address that you noted in the first exercise. Use the Example\Administrator credential. See directions for how to use connect according to your client platform.

Note: Recall that the password for Example\Administrator has been set to the password you provided in the AdminPassword input parameter during the 1st hour exercise.

To verify the RDP certificate, choose Continue as shown in the following screenshot.

Load surrogate attribute

To start loading the surrogate attribute, choose the Start Menu, type user, and choose Active Directory Users and Computers.

Choose View, and then choose Advanced Features as shown in the following screenshot. This allows you to see and manipulate a broader set of Active Directory attributes compared to what is enabled by default.

Next, choose Users, then right click on alice, and choose Properties.

Choose Attribute Editor, find employeeType, and choose Edit. Type HighTrust and choose OK. You now see the HighTrust value reflected for employeeType as shown in the following screenshot.

Repeat the process above for bob. Set employeeType to LowTrust on bob's account.

Update AD FS Configuration

Now that you've modified the back-end directory, you will modify the AD FS configuration as well. The updated configuration sends the additional attribute to AWS through the SAML assertion.

Login to AD FS via RDP

Log in using RDP to your AD FS instance using the public IP address. You can obtain the public IP address from the Output tab from the FederationWorkshopADFS CloudFormation stack you deployed in the first exercise. Log in using the EXAMPLE\Administrator credential.

Note: Recall that the password for the EXAMPLE\Administrator account is set to the password you provided in the AdminPassword input parameter during the 1st hour exercise.

Update AWS claim rules

To get started updating the claim rule, choose the Start menu, type ad fs, and choose AD FS Management.

Choose Relying Party Trusts, then choose signin.aws.amazon.com, and finally choose Edit Claim Rules as shown in the following screenshot.

Choose Add Rule, and then choose Send LDAP Attributes as Claims. Finally, choose Next.

On the Configure Claim Rule page, type the following settings, and choose Finish, as shown in the following screenshot.

Configuration Element	Value
Claim rule name	EmployeeType
Attribute store	Active Directory
LDAP Attribute	Employee-Type
Outgoing Claim Type	urn:oid:1.3.6.1.4.1.5923.1.1.1.11

This claim rule maps the source attribute of EmployeeType into a SAML specific URI that AWS understands. This specific URI maps to an AWS context key of eduPersonAssurance. Refer to the documentation for information regarding the specific URI values that AWS expects.

Note: The translation from EmployeeType to eduPersonAssurance is necessary because EmployeeType is not included within the set of assertion attributes that specifically map to AWS Trust Policy Context Keys. Similarly, while eduPersonAssurance carries a more relevant context for this use case, it is not available within the standard Active Directory schema. In order to avoid schema edits to support a surrogate attribute, we have chosen to translate the attribute through the claim rule. The use of this mapping will become clearer as you progress through the use case.

Add additional trust policy conditions to IAM roles

At this point, you've fully configured AD FS to send the additional attribute, EmployeeType, to AWS through the SAML assertion attribute eduPersonAssurance. Now, you will configure additional conditions within the trust policy of the IAM roles for federation that you configured in the initial exercise. In a federated scenario AWS fully trusts the IdP to properly authenticate and authorize the user into a given IAM role, so this configuration principally serves as a defense in depth protection. These conditions firmly ensure that users cannot assume the role if they do not meet the necessary conditions, even if an error in the IdP configuration exists which prevents the multi-factor authentication from occurring.

Start by logging in to the AWS Management Console, and select Identity & Access Management.

Choose Roles from the left pane, and then choose the FederationWorkshop-ReadOnly role, as shown in the following screenshot.

On the role Summary page, choose the Trust Relationships tab, and then choose Edit Trust Relationships.

When the Edit Trust Relationship opens, you will see the default trust policy that was generated during the role creation workflow you performed during the initial exercise. Locate the condition within the policy that specifies that AWS must be the intended audience of the presented SAML assertion. It looks like the following snippet.

"StringEquals": {
  "SAML:aud": "https://signin.aws.amazon.com/saml"
}

Immediately following this condition, add a second condition using the following snippet. This snippet requires that the SAML:eduPersonAssurance trust policy context key is set to HighTrust in the SAML assertion. Be sure to add a comma at the end of line 13 to maintain properly formed json, and then choose Update Trust Policy to save your changes.

"ForAnyValue:StringEquals": {
  "SAML:eduPersonAssurance": "HighTrust"
}

Note: When an IAM policy specifies more than one condition, the conditions are evaluated using a logical AND.

Note: These context keys are only available for use within trust policies, and not within the standard permission policies.

Testing

You are now ready to test your enhanced trust policy. To do so, open a new browser window, and open the SAML tracer add on. We'll use SAML tracer to inspect the contents of the SAML assertions as they flow from the IdP to AWS, which allows you to see the results of your configurations and understand the information that AWS is consuming from your identity provider. See the following screenshot for help enabling SAML tracer.

With SAML tracer enabled, switch back to the main browser window and enter the IdP initiated login URL for AD FS.

https://idp1.example.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices

We'll start by testing the success condition of our configurations, so after AD FS returns the login page, log in using alice's credentials.

Note: Recall that alice's password has been set to a random value exposed as an output variable in the 1st hour CloudFormation template.

After you log in, you see the AWS role chooser page. Before making your selection, switch back to the SAML tracer window, and scroll upwards until you find the entry for https://signin.aws.amazon.com/saml. Choose that entry, and select the SAML tab in the lower pane. As you look through the assertion, look for the <AttributeStatement>. This allows you to see how the configurations you applied above translate into the additional eduPersonAssurance SAML attribute. See the following screenshot for reference.

After you've finished inspecting the assertion, switch back to your main browser window, select the FederationWorkshop-ReadOnly role within your main AWS account and choose Sign In.

Because alice was configured for High Trust, she can assume the role.

Now let's test the deny condition of our configurations. Open another private browser window, and enter the IdP initiated login URL for AD FS.

https://idp1.example.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices

After AD FS returns the login page, log in using bob's credentials.

Note: Recall that bob's password has been set to a random value exposed as an output variable in the 1st hour CloudFormation template.

After you log in, you see the AWS role chooser page. Select the FederationWorkshop-ReadOnly role within your main AWS account and choose Sign In. Because you configured Bob for Low Trust, he does not meet the eduPersonAssurance condition and receives a not authorized message, as shown in the following screenshot.

Adapting for true MFA

After you've implemented the configurations above, adapting this pattern for use with an actual MFA solution is relatively straight forward. First, you must configure AD FS to perform multi-factor authentication, using the MFA solution of your choice. This process is dependent on your choice of MFA provider. Refer to the appropriate product documentation for instructions.

Once these steps have been performed, replace the claim rule configured above, with the a new transform an incoming claim rule using the following values, as shown in the following screenshot.

Configuration Element	Value
Claim rule name	Authentication Method
Incoming claim type	Authentication Method
Outgoing claim type	urn:oid:1.3.6.1.4.1.5923.1.1.1.11

This claim rule populates the eduPersonAssurance attribute you used above with the URI of the authentication method used to authenticate the user. For example, a user that is authenticated via username and password over a secure connection receives a value of urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport. Use SAML tracer to understand the specific URIs that correspond to each authentication method.

Next, you need to adjust the IAM role trust policy. Update the required value for the SAML:eduPersonAssurance context key according to the value that's being passed from AD FS. In the following example, AD FS is passing the standard URI for a time based token, urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken.

"ForAnyValue:StringEquals": {
  "SAML:eduPersonAssurance": "urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken"
}

Finally, test out your new configuration, using SAML tracer to help ensure that your assertions are properly formed in both the success and deny conditions.

Key take-aways

In summary, there are three key take-aways from this use case:

• AWS provides a wide range of SAML attributes that are mapped to AWS trust policy context keys. You can use these keys to provide additional conditions for role assumption according to your requirements.
• These additional attributes are configured and populated within your IdP and consumed by AWS through the SAML assertion.
• To implement MFA-for-SAML, consider mapping the eduPersonAssurance attribute to the principal authentication method, and use standard URIs within your trust policy conditions.

Exercise complete

Congratulations! You have successfully completed the use SAML attributes to enforce role assumption conditions (also known as MFA-for-SAML) advanced use case.

With this use case complete, you are now ready to continue your journey through more of the advanced use cases. To continue, return to the index of advanced use cases.