Integrate Shibboleth with AWS Identity and Access Management

Sample Code & Libraries>Integrate Shibboleth with AWS Identity and Access Management
Community Contributed Software

  • Amazon Web Services provides links to these packages as a convenience for our customers, but software not authored by an "@AWS" account has not been reviewed or screened by AWS.
  • Please review this software to ensure it meets your needs before using it.

This article and code sample is targeted at system architects, system administrators, and security professionals who want to integrate Shibboleth with Amazon Web Services (AWS). It describes federation proxy approach to giving users Single Sign On (SSO) access to on-premises resources and the AWS Management Console.

Details

Submitted By: Larry Gilreath
AWS Products Used: AWS IAM, AWS Management Console
Language(s): C#, Powershell
License: Apache License
Created On: September 23, 2013 6:56 PM GMT
Last Updated: September 26, 2013 12:22 AM GMT
Download

This article and code sample is targted at system architects, system administrators, and security professionals who want to integrate Shibboleth with Amazon Web Services (AWS). It describes one approach to giving users Single Sign-On (SSO) access to on-premises resources and the AWS Management Console.

  1. Introduction
  2. Overview
  3. Configuring the Shibboleth Environment
  4. Configuring IAM
  5. Installing and Configuring the Federation Proxy
  6. Deploying the Sample
  7. Seeing the Sample in Action
 

Introduction

AWS Identity and Access Management (IAM) service can be integrated with Shibboleth using a federation proxy to provide users with SSO access to the AWS Management Console. Using this approach, system administrators can provide users with access to the AWS Management Console using Shibboleth user credentials. This can benefit systems administrators by reducing their administrative overhead and helping users by reducing their need for separate AWS credentials. Depending on configuration, users can be granted access to the full capabilities of the AWS Management Console, or have limited access, based upon their level of authorization. For many large enterprises, identity federation to provide SSO may already be commonplace. It's an approach used for authenticating users across multiple sites within a realm (i.e., intranet) and across independent and disparate domains (i.e., extranet) using known standards. Extending this model, the trust established with the federation proxy allows for temporary security credentials to be obtained from the AWS Security Token Service (STS) providing access to the AWS Management Console. The reference architecture described below provides an approach for integrating Shibboleth with the AWS Management Console. Readers interested in integrating Windows Active Directory can download the sample code from here.

The following diagram shows the network traffic flow of a federated proxy using Shibboleth.

Here are the steps represented in the diagram:

  1. User A browses to an intranet site (for example https://aws.exampleurl.edu)
  2. User A is redirected to authenticate
  3. SAML (Security Assertion Markup Language) token with IAM role names and External ID's is given to User A
  4. User A makes request to Sample proxy Server using the SAML Token
  5. AWS Proxy Service calls the AWS STS API List Roles to get the list of roles defined for the AWS Account
  6. STS returns a list of IAM roles for the user to assume, user selects a role from drop down
  7. Sample proxy server makes an "Assume Role" request to STS using the role selected in the previous step
  8. STS responds with temporary security credentials (Access Key ID, Secret Access Key, and Session Token)
  9. The sample proxy server requests a sign-in token and generates a sign-in URL.  The proxy then redirects User A to the sign-in URL providing SSO to the AWS Management Console
  10. User A can now access authorized AWS services from AWS Management Console

 

Let's dive into the configuration details of the components.

Overview

With IAM, you can create and manage IAM users and groups, and specify permissions to allow and deny them access to AWS resources. You can also enable identity federation to allow existing identities (i.e., users from an internal directory) to access the AWS Management Console, call AWS APIs, and access resources. Using identity federation, you don't have to create a separate IAM user for each identity.

You enable identity federation by requesting temporary security credentials that can be used to sign requests to AWS. The temporary security credentials are comprised of short-lived access keys and session tokens associated with the keys. Federated users can use the access keys the same way as before, as long as they pass the token along in the calls that they make to the AWS APIs.

The permissions associated with temporary security credentials are at most equal to those of the IAM role being assumed. You can further restrict the credentials by specifying explicit permissions (as a policy) as part of the assumeRole request. There is no limit on the number of temporary security credentials you can request.

There are three high-level steps to integrating Shibboleth with IAM:

  • Configure Shibboleth.
  • Configure IAM.
  • Install and configure the federation proxy application.

Let's dive into more detail for each step.

Configuring Shibboleth

Your Shibboleth IDP needs to release at least one attribute to the AWS Management Console Shibboleth Proxy with all the AWS roles relevant for the user. It is up to you, or the IDP administrator, to determine what attribute you would like to use. The AWS Management Console Shibboleth Proxy will search all assertions for any items that start with "AWS:".

In our test environment we used the Street Address attribute to release the appropriate assertions and then configured our IDP to release the attributes by doing the following:

  1. Using an LDAP (Lightweight Directory Access Protocol) editor we used the existing Street Address attribute (you could also create a new attribute, if you like) to add roles in the following format: AWS:<rolename>:<external id>.

    2. Note: The external ID is an additional validator that you choose. Name-based matching for AWS Roles is not guaranteed to be unique, because claim values can be deleted, recreated, or simply guessed. The external ID adds additional validation that only administrators, who have access to LDAP, will know. The external ID can be any combination or letters and numbers; its up to you to choose.

    The following screenshot, uses the Street Address attribute to add two roles, CSResearch with an External ID of 0421977 and AWSS3Users with an External ID of 06301977.
    AWS Claims2

  2. In the attribute-filter.xml file on the Identity Provider (IDP), use a file editor to include the Street Address attribute in the SAML token. 
    <afp:AttributeRule attributeID="street"> 
     <afp:PermitValueRule xsi:type="basic:ANY" />
    </afp:AttributeRule>
    3. Within the attribute-resolver.xml file on the IdP, the Street Address attribute is mapped to the correct LDAP attribute:
     <resolver:AttributeDefinition xsi:type="ad:Simple" id="street" sourceAttributeID="streetAddress">
     <resolver:Dependency ref="myLDAP" />
     <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:street" />
     <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:2.5.4.9" friendlyName="street" />
     </resolver:AttributeDefinition>
You've successfully configured Shibboleth. The next step is to configure IAM.

Configuring IAM

Within the appropriate AWS account, you must create IAM roles to be assumed by your federated users and one IAM user that will be utilized by the proxy server. The names of the roles must match the names of the SAML assertions in the user's SAML token. To ensure the same group is always used, you configure the role trust policy to include a condition that checks that the External ID matches the ID in the user's AWS External ID SAML assertion.

The federation proxy also requires a set of long-term credentials from the IAM user that can call the ListRoles and AssumeRole APIs, so you create an IAM user and generate long-term security credentials (that is, an AWS access key and a secret access key) for this user. This IAM user will not have any other purpose; so it doesn't need a password.

  1. Open the AWS Management Console, click the IAM tab, and then click Roles.
  2. Click the Create New Role button to create a new role called CSResearch. Be sure to use the same name that you used when you created the Role Name assertion for the SAML token.

    [image]
  3. Select Roles for cross-account access under Select Role Type and then select Provide access to a 3rd party AWS account. (Here you are providing access to your own account. Using this option allows you to set a condition that checks that the External ID matches the ID in the user's AWS External ID SAML assertion.

    [image]
  4. Set the Account ID and External ID to the following:
    • Account ID. Use your 12-digit AWS account ID number. (Replace 111122223333 with your account number in the following example, using only numbers, no dashes.)
    • External ID. Use the SAML assertion External ID of the same name (the external ID CSResearch in this case), which you created in the previous step.
    [image]
  5. Select the Administrator Access policy template.

    [image]
  6. Name the policy and then click Continue.

    [image]
  7. Review your final settings and then click Create Role to create and save your new role. 

    [image]
  8. Repeat the previous steps to create another new role, this one named AWSS3Users. Use the following information:
    • Name: AWSS3Users
    • RoleType: Roles for cross-account access using Provide access to a 3rd party AWS account
    • Account ID: Your 12-digit AWS account ID
    • External ID: 06301977 (make sure you use the external ID you choose in the previous step)
    • Policy Template: Amazon S3 Full Access
  9. Create the IAM user with long-term credentials required by the federation proxy. The policy should  allow the user to do the following:
    • Call ListRoles to list all the IAM roles in the AWS account
    • Call AssumeRole for any of the of IAM roles in the AWS account
  10. For Resource, use your 12-digit AWS account ID number.
    The policy should look something like the following example. (Replace 111122223333444 in the example, using your 12-digit AWS account ID number, without dashes.) 
    { "Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"iam:ListRoles",
				"sts:AssumeRole"
				],
			"Resource": "arn:aws:iam::111222333444:role/*"
		}
	]
}
  11. Generate and download the access keys for the new IAM user. (You will need the access keys in the following steps, but they won't be available after you close the Create User Wizard.

Installing and Configuring the Federation Proxy

Download the Sample code from by clicking the Download button above.

Pre-requisites

This sample is a Shibboleth extension to a previously released sample that leveraged Active Directory. To run the sample, you need the following permissions and software:

  • Administrative access required to create IAM user, roles, and policies within your AWS account.
  • Administrative access to a Windows 2012 Server running IIS server (tested with v7.5) with the following configuration:
  • Note: The script used to compile the sample expects both components to be installed in the default locations of:
    - C:\WIF Extension for SAML 2.0 Protocol CTP Release
    - C:\Program Files (x86)\AWS SDK for .NET
  • The following items need to be downloaded and installed:
    • Windows Identity Foundation Extensions - LOCATED HERE
    • The latest version of the AWS SDK for .Net
    • Web Server (IIS) Role with the following role services installed:
      • ASP.NET
      • .Net Framework 3.5 Features (includes .Net 2.0 and 3.0)
      • .Net Framework 4.5 Features
        • .Net Framework 4.5
        • ASP.net 4.5
      • Windows Identity Foundation 3.5
      • A certificate to enable HTTPS support.
    • Optional: Visual Studio 2012 Express Edition for Web (available here) with C# installed.

Installing the Sample

  1. You must configure a certificate in IIS to ensure that the requests are signed. For information about for setting up SSL certificates in IIS, see http://www.iis.net/learn/manage/configuring-security/how-to-set-up-ssl-on-iis.
    Changes need to be made to the web.config file to enable listing roles in AWS. By default, the sample stores the secret access key as an encrypted value using Windows Cryptographic Services. To begin you will need to encrypt your secret access key into a hex-encoded string. The sample includes a Windows PowerShell script (AWSConsoleFederationProxy SecretKey Encryptor.ps1) to help you generate the string. Note: By default, your server might lock running unsigned scripts. If so, perform the following steps as an administrator:
    • Launch PowerShell as administrator.
    • Right-click Windows PowerShell and choose Run as administrator.
    • Use the following command to change the execution policy on the computer to remote signed set-executionpolicy Unrestricted.
    • Press Y to accept.
    Run the AWSConsoleFederationProxy SecretKey Encryptor.ps1 found in the bootstrap folder:
    From the PowerShell command line, change to the bootstrap folder. Run the script using your secret access key as the input, within quotes, as follows:
    AWSConsoleFederationProxySecretKeyEncryptor.ps1' "myawssecretkeymyawssecretkey"

    Note: You might get a warning about untrusted scripts. If so, choose [R]. Run once.

  2. You must configure the following settings in web.config before you run the federation proxy sample. Replace the text with your values.
    • AWSSecretKey. Get this from the IAM user. This value was encrypted in the previous steps.
    • AWSAccessKey. Get this from the IAM User.
    (Optional) By default, sessions are valid for 1 hour (3600 seconds), but valid settings range from 900 seconds (15 min) to 3600 seconds) By default, sessions are valid for 1 hour (3600 seconds), but valid settings range from 900 seconds (15 min) to 3600 seconds (1 hour).
  3. Run the InstallShibbExt.ps1 found in the root of the Shibboleth Extension folder.

    Note: You might get a warning about untrusted scripts. If so, choose [R]. Run once.

    Note: The InstallShibbExt.ps1 script expects the following components to be installed in the default locations of:

    • - C:\WIF Extension for SAML 2.0 Protocol CTP Release
    • - C:\Program Files (x86)\AWS SDK for .NET
  4. Close PowerShell.

    5. Note: After you've done this, you can set the server back to the default state by using the following command: set -executionpolicy Default. Press Y to accept.

Configuring Federation Trust

Use the SamlConfigTool (part of the WIF Extension download) to establish the federation trust between the service provider and identity provider. The tool will need to be compiled, by following the instructions included in the WIF Extension download.

Note: If Visual Studio is not installed the SamlConfigTool can be compiled by copying the BuildSAMLConfigTool.rsp file from the bootstrap folder to the C:\WIF Extension for SAML 2.0 Protocol CTP Release\Common\SamlConfigTool folder and invoking the C# compiler from a Command prompt with the response file as the only option. Also ensure that the Microsoft.IdentityModel.Protocols.dll is in the same directory. For example: "C:\WIF Extension for SAML 2.0 Protocol CTP Release\Common\SamlConfigTool>c:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe @BuildSAMLConfigTool.rsp"

This tool generates the metadata documents of the service provider and the identity provider with which it establishes federation trust. These metadata documents are fed into the configuration file of the service provider. This tool also generates an .xml file that lists the changes to be made to the Shibboleth Extension web.config file.

  1. Copy the SamlConfigTool.exe file to the Shibboleth Extension directory that contains the web.config file.
  2. Run SamlConfigTool.exe (ensure that the web.config, Microsoft.IdentityModel.Protocols.dll, and the SAMLConfigTool.exe are in the same directory)
    While you're entering inputs to the tool, keep the following tips in mind:
    • The trailing slash is required when you enter the SAML endpoint in Part 1 if the path is the same as the application root directory.

    • When you are prompted for signing and encryption certificates after you enter the SAML endpoint, select them or click Cancel to have the tool create a self-signed certificate. Then, after selecting the certificate created by the tool, click OK.
    • Follow the on-screen instructions provided by the tool. Here are example entries that you would use to configure the sample. 
      Example entries 

      Part 1: Relying Party Information
      Enter your entity ID [urn:contoso.com]: 
      https://mywebserver/ServiceProvider

      Enter your SAML endpoint [https://www.contoso.com/MyApp/saml/]: 
      https://myWebserver/ServiceProvider/ 

      NOTE: A signing certificate is needed to support logout.

      Would you like to generate a self-signed certificate for signing?[Y/n] 

      Y

      Part 2: Identity Provider Information 
      Enter your partner's metadata URL [sts.contoso.com, or blank if done]:
      myFedserver.booksarecool.com 

      Attempting to download https://myADFSserver.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml...

      Enter your partner's metadata URL [sts.contoso.com, or blank if done]:       
      <enter>

      Part 3: Update web.config. Open the Changes_To_Web_Config.xml file in your preferred XML reader to view the changes that need to be made.
  3. Open the Changes_To_Web_Config.xml file in your preferred XML reader to view the changes that need to be made. Update the web.config file with the additional changes.
  4. Copy the Microsoft.IdentityModel.Protocols.dll to the bin directory of the Shibboleth Extension

Deploying the Sample

To deploy the project to your IIS server, take the following steps:
  1. Open the IIS Management Console (Refer to MSDN for steps specific to the operating system and IIS version running on your system.)
  2. Browse to your application pools and make sure you have an application pool for the .NET Framework 4.0. If you do not have an application pool, create a new one with the following settings:
    • Name: AWSFedProxy
    • .NET Framework version: .NET Framework version 4.0.30319
    • Managed pipeline mode: Integrated
  3. Start application pool immediately.


  4. Modify the Application Pool to run as LocalSystem by selecting the AWSFedProxy Application Pool and clicking "Advance Settings" on the far right. In the "Advance Settings" change "Identity" to LocalSystem
  5. Select Default Web Site node under the server node.
  6. Click Add Application and then, in the Physical path box, enter the location where Shibboleth Extension project resides on your local disk, for example C:\inetpub\Shibboleth Extension\Src\Shibboleth Extension.
  7. Type the website name AWSConsoleFederationProxy in the Alias box.
  8. Set the Application Pool to AWSFedProxy.

  9. Click OK to finish deploying the website.
To ensure the confidential transfer of security credentials, we strongly recommended enabling SSL so that the client and server communicate over HTTPS. To enable SSL, do the following:
  1. In IIS Manager, select the website (in our example, Default Web Site) in the leftmost tree view, and then click Bindings in the Actions pane on the rightmost side of the screen. 

    2. [image]

    A dialog box lists all of the binding rules.

  2. To enable SSL for the site, click Add. The Add binding dialog box opens, in which you can add HTTPS protocol support.
  3. Select https in the Type drop-down list, and then select an appropriate SSL certificate.

    4. [image]

  4. Click Ok to enable SSL for the site.

Seeing the Sample in Action

Here's what happens when you run the sample:
  1. User A browses to the proxy URL and is prompted to log in with Shibboleth credentials.  



  2. After the user's credentials are validated, all roles that match assertions are listed in a drop-down box.

    >

  3. The user selects the appropriate role and then clicks Sign in to the AWS Management Console.



  4. The proxy retrieves the necessary information from the SAML token and then calls AssumeRoleRequest. The proxy server assumes the role, generates a sign-in URL, and then the user is redirected to the AWS Management Console.


This article has demonstrated using a federated proxy approach to integrate IAM with Shibboleth and give users SSO access to the AWS Management Console with Shibboleth user credentials.

©2013, Amazon Web Services, Inc. or its affiliates. All rights reserved.