AWS Security Blog

How to Use SAML to Automatically Direct Federated Users to a Specific AWS Management Console Page

Identity federation enables your enterprise users (such as Active Directory users) to access the AWS Management Console via single sign-on (SSO) by using their existing credentials. In Security Assertion Markup Language (SAML) 2.0, RelayState is an optional parameter that identifies a specified destination URL your users will access after signing in with SSO. When using SAML-based identity federation in AWS, you can use RelayState to redirect your signed-in, authenticated users to any AWS console page, such as the Amazon EC2 console in Tokyo or a specific Amazon S3 bucket page.

In this blog post, I will show you how to create a deep link for federated users via the SAML 2.0 RelayState parameter in Active Directory Federation Services (AD FS). By using a deep link, your users will go directly to the specified console page without additional navigation.

Note: If you are not using AD FS as your identity provider (IdP), check to see if your IdP supports the RelayState parameter. If it does, you can follow similar steps with your IdP to achieve the equivalent of my AD FS configuration.

Prerequisites

The solution in this blog post requires you to use RelayState with AD FS. Before proceeding, be sure to:

Summary of the federated user sign-in flow using RelayState with AD FS

By the end of this post, you will have created a few unique deep links starting from different AWS Management Console URLs. The following steps show the IdP-initiated SSO flow that occurs after a user clicks one of these links (the steps are also illustrated in the following diagram):

  1. The user clicks a deep link that redirects to the IdP for authentication with the information about the destination URL embedded in the RelayState parameter.
  2. Your IdP (AD FS in the case of this blog post) verifies the user’s identity in your organization.
  3. Your IdP generates a SAML authentication response that includes assertions that identify the user and attributes about the user. The IdP sends this response to the user’s browser.
  4. The user’s browser is redirected to the AWS SSO endpoint and posts the SAML assertion and the RelayState parameter.
  5. The endpoint calls the AssumeRoleWithSAML API action to request temporary credentials from the IAM role specified in the SAML assertion and creates a console sign-in URL that uses those credentials. If the SAML authentication response includes attributes that map to multiple IAM roles, the user is first prompted to select the role to use for access to the console. The console sign-in URL is the one specified by the RelayState parameter.
  6. AWS sends the sign-in URL that is based on the RelayState value back to the user’s browser as a redirect.
  7. The user’s browser is redirected to the AWS Management Console location defined by the RelayState parameter.

Diagram showing the steps of the IdP-initiated SSO flow that occurs after a user clicks one of these links

How to create SSO URLs that include RelayState

In order to provide a full SSO experience for the end users, the RelayState parameter includes the relying party’s Uniform Resource Name (URN) so that users are automatically redirected to that relying party (the AWS Management Console).

In addition to the URN, RelayState can be used to specify the AWS Management Console location you want to land to. RelayState is URL encoded and then appended to your existing AD FS sign-in URL.

Therefore, the first step to generate a fully working AD FS sign-in URL is to identify which specific AWS Management Console URL you want to use, and use it to craft the value of RelayState.

Microsoft provides a tool to help generate these SSO URLs for AD FS. The tool is called AD FS 2.0 RelayState Generator, and you can download this tool from CodePlex.

Identify the AWS Management Console URL for the deep link

In this example, I create a deep link for my EC2 console page, where I want to list just my EC2 instances. I work on the same AWS account with other team members, and I use a tag called Owner so that I can filter my instances by checking if the tag value matches my name, Alessandro.

I follow these steps to filter my instances:

  1. Go to the EC2 console.
    Image of the EC2 console
  2. Verify the region. In my case, the region is Ireland (eu-west-1)
    .Image of verifying the region
  3. In the search field, I type the name of the tag I want to filter my instances on. In my case, it is Owner. I select it from the results list.Image of selecting the tag from the list
  4. I then specify the tag value I want. Here, the value is Alessandro, and I select it from the results list.Image of selecting the tag value

After the tag filter is applied, I can see that the page URL reflects my filter information, as shown in the following screenshot.

Image of the page URL with filter information

In this example, an additional string is appended to the base EC2 console URL, and it contains the tag name and value I applied: Instances:tag:Owner=Alessandro

The following URL is the full URL I am going to use for my deep link:

https://eu-west-1.console.aws.amazon.com/ec2/v2/home?region=eu-west-1#Instances:tag:Owner=Alessandro;sort=instanceId

Create the deep link

To create a deep link for the URL I just identified in the previous section, I follow these steps:

  1. Download GenerateRelayState.html from CodePlex (direct link to the download). You can use it for AD FS 3.0 and 2.0.
  2. Open GenerateRelayState.html in a browser.
  3. Use the following parameters. Make sure you replace ADFSSERVER with your AD FS fully qualified domain name (FQDN) or DNS name, and that you specify the Uniform Resource Name (URN) exactly as shown below to match the value defined in the AWS federation metadata you used to configure the relying party in AD FS:

IDP URL String = https://ADFSSERVER/adfs/ls/idpinitiatedsignon.aspx

Relying Party Identifier = urn:amazon:webservices

Relay State/Target App = The AWS Management Console URL you want your authenticated users to access. In this case, it is:

https://eu-west-1.console.aws.amazon.com/ec2/v2/home?region=eu-west-1#Instances:tag:Owner=Alessandro;sort=instanceId

The following screenshot shows how the GenerateRelayState.html page looks for my configuration. When you open the page, it initially contains some default prepopulated values I replaced with my own. In my environment, the AD FS FQDN is adfs.example.com.
Image of GenerateRelayState.html page

  1. Click Generate URL to get the following result (note that this URL will not work in your setup because it has been created specifically for an AD FS server called adfs.example.com):

https://adfs.example.com/adfs/ls/idpinitiatedsignon.aspx?RelayState=RPID%3Durn%253Aamazon%253Awebservices%26RelayState%3Dhttps
%253A%252F%252Feu-west-1.console.aws.amazon.com%252Fec2%252Fv2%252Fhome
%253Fregion%253Deu-west-1%2523Instances%253Atag%253AOwner%253DAlessandro
%253Bsort%253DinstanceId

I can now save this URL and use it from anywhere I can reach my AD FS server. After I enter the URL in a browser, I first authenticate to AD FS, and then I am redirected to the specified EC2 console page. I have created a simple HTML page with the link to the EC2 instances in eu-west-1 that I have just generated. I generated a deep link for each AWS Management Console regional console to easily navigate to a specified region at authentication time. To do so, I used each regional AWS Management Console URL—one at a time—as the Relay State/Target App parameter for the GenerateRelayState.html page.

The resulting summary page is shown in the following image.

Image of resulting summary page

I can also share this page or an equivalent one with my team members, who have access to the same AWS account for which I created the links. The page could be a local HTML page you distribute or a page served by a web server of your choice, instead of the standard AD FS sign-in page (https://ADFSSERVER/adfs/ls/IdpInitiatedSignOn.aspx). Each regional console link redirects a user to AD FS first and, because Windows-integrated authentication is configured correctly, my colleagues will be authenticated and redirected to the page specified in the RelayState parameter.

Other uses of RelayState

RelayState can redirect users to any AWS console page. For example, I often work with other team members on shared AWS accounts, and we use federation to manage access. For our projects, I use deep links when writing technical documentation to point to specific AWS resources, such as EC2 instances. Using tags on EC2 instances, you can easily generate deep links that direct users to a list of specific instances. You can also generate a deep link from whatever URL you see in the AWS Management Console to redirect users to any AWS resources.

If you want to learn more about how to build the RelayState URL, see both AD FS 2.0 RelayState and Supporting Identity Provider Initiated RelayState. In addition, inspecting the GenerateRelayState.html source code will provide some insight into how to automatically generate your own URLs. You can also see AD FS 2.0 RelayState Generator and Description of Update Rollup 2 for Active Directory Federation Services (AD FS) 2.0 for more information about this topic.

If you have questions, or if you want to share some use cases that RelayState has enabled for you, feel free to post them on the IAM forum.

– Alessandro

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.