AWS management console federation proxy sample use case

This sample is intended for developers who want to learn how to use the identity federation capabilities of AWS Identity and Access Management (IAM). Specifically, it illustrates how to create a federation proxy server that uses IAM roles to create temporary security credentials that can be used by Windows Active Directory users to SSO to the AWS Management Console.

(Please refer to the Readme included within the documentation of this package for detailed setup instructions.)

Prerequisites

To be able to run the sample you need the following:

• Administrative access necessary to create IAM user, roles and policies within your AWS account.

• Administrative access to a Microsoft Windows IIS server (we have tested using v 7.5) that is joined to an Active Directory domain with the following configuration:

  • .Net Framework 4.0 installed.

  • Web Server (IIS) Role with the following role services installed.

    • ASP.NET

    • Windows Authentication

  • The latest version of AWS SDK for .NET

  • Optional: A certificate to enable HTTPS support.

• A computer which is joined to the same Active Directory domain.

Optional - if you intend to compile and deploy the sample manually you will need

• A Windows development environment including:

  • .Net Framework 4.0.

  • The latest version of AWS SDK for .NET.

  • Visual Studio 2010 Professional, or later, with C# installed.

What is included?

The sample package includes the following components:

1. AWSConsoleFederationProxy.Installer - For customers interested in being able to quickly evaluate the proxy server, the sample includes a Microsoft Installer package (MSI). The MSI includes a setup wizard that will guide you through the process of deploying and configuring a proxy server so you can start testing the capabilities of the sample quickly.

2. AWSConsoleFederationProxy - This is a Microsoft Visual Studio solution containing the AWS Management Console Federation Proxy sample code that can be compiled and deployed as the proxy server. The solution includes the following C# projects:

• AWSConsoleFederationProxy.UI - The sample includes an Active Server Page (default.aspx) that acts as the federation proxy. The web page authenticates the user in AD, determines what roles the user can access in AWS by matching their AD group membership to IAM roles by name in the AWS account and finally uses AWS Security Token Service (STS) to retrieve temporary credentials by calling the AssumeRole API. These credentials are then used to SSO into the AWS Management Console.

• AWSConsoleFederationProxy.BL - Includes the main class for AWS Management Console federation proxy business logic such as: capturing the current Windows username, enumerating the roles available to the user, requesting a session, creating the temporary console URL, and redirecting the user to the console.

• Utilities - Includes a set of helper classes for example accessing AWS, Active Directory, Windows Cryptographic services, and other helper functions.

What does this sample do?

The proxy server is an ASP page that acts as the main entry point to access to the AWS Management Console. The following describes how the proxy server works. The sample implementation performs the following illustrative steps:

1. The user browses to the internal proxy server.

2. If the user is a logged into a computer joined to the AD domain and their web browser supports Windows authentication, they will be authenticated using Windows integrated authentication. If the user is not logged into a computer joined to the domain, they will be prompted for their Windows username and password. The proxy determines the Windows username from the web request and uses this when making the session request.

After an AD user is authenticated by the proxy the following occurs:

3. The proxy retrieves a list of the user's AD group membership.

4. The proxy retrieves IAM user credentials from a web configuration file (web.config) configured during setup. By default, the sample encrypts the secret access key using Windows Cryptographic Services. The proxy uses these credentials to call the ListRoles API requesting a list of all the IAM roles in the AWS account created during setup.

5. The response includes a list of all the IAM roles available within the AWS account.

6. The proxy determines user entitlements by taking the list of AD groups and the list of IAM roles and determines the intersection of these two lists based on name mapping. The proxy takes the intersection and populates a drop down box with all the available roles for the current user. The user selects the role they want to use while logging into the AWS management console. Note: if the user is not a member of any AD groups that match a corresponding IAM role, the user will be notified that no roles are available and access will be denied.

7. Using the Amazon Resource Name (ARN) of the selected role, the proxy uses the credentials of the IAM user to makes an AssumeRole request. The request includes setting the ExternalId property using the security identifier (SID) of the AD group that matches the name of the role. This adds an additional layer of verification in event the AD group is ever deleted and recreated using the same display name. By default the expiration is set to the maximum of 3600 seconds.

8. The proxy receives a session from STS that includes temporary credentials: access key, secret key, expiration and session token.

9. The proxy uses the session token along with the SignInURL and ConsoleURL from the web configuration file (web.config) to generate a temporary sign-in url.

10. Finally the user is redirected to the temporary sign-in url which automatically logs them into the AWS Management Console is valid until the session expires.

Seeing the application in action

1. A user signs in with their domain credentials, using a computer that is joined to the same Active Directory domain.

2. The user opens a web browser and browses to the url where the federation proxy is deployed (ex: https://yourservername/AWSConsoleFederationProxy) (use HTTP if SSL is disabled). You should be presented with a list of roles to choose from.

3. User selects a role from the dropdown and then, clicks Sign in to AWS Console to be redirected to the AWS Management Console.