AWS Security Blog

How to Use Shibboleth for Single Sign-On to the AWS Management Console

Update from January 17, 2018: The techniques demonstrated in this blog post relate to traditional SAML federation for AWS. These techniques are still valid and useful. However, AWS Single Sign-On (AWS SSO) provides analogous capabilities by way of a managed service. If you are just getting started with federating access to your AWS accounts, we recommend that you evaluate AWS SSO for this purpose.

In a previous blog post (Enabling Federation to AWS using Windows Active Directory, ADFS, and SAML 2.0), we described how you can enable single sign-on (SSO) to the AWS Management Console using Active Directory Federation Services (ADFS) 2.0 and Security Assertion Markup Language (SAML) 2.0. SAML-based federation eliminates the need to maintain separate user identities in both Active Directory (AD) and AWS, so that end users need to remember only a single username and password.

In this blog post, I use the same scenario that we did in the earlier post, but here I use Shibboleth as the identity provider instead of ADFS. Shibboleth is an open-source identity federation solution that’s used in research and education communities worldwide. If you’re already using Shibboleth, this post will show you how to configure it for single sign-on to AWS. If you’re new to Shibboleth, the post will help you set up a demonstration environment to try out single sign-on to AWS using Shibboleth. 

As we did in the previous blog post, I’m using AD as the source for user identities. However, the configuration settings for Shibboleth and AWS would be the same even if you were to use a different identity provider, such as OpenLDAP. You can see the basic flow depicted in the following diagram.

Diagram of the process flow

The following sections cover how you can set this up. I cover Shibboleth-specific sections in greater detail, since the previous post already covered the AD and AWS requirements.

1. Set up Active Directory as the identity store

If you want to quickly create a demonstration environment in Amazon EC2, you can take advantage of the AWS CloudFormation single-server AD template. This template will do the heavy lifting of deploying a Microsoft Window Server 2008 R2 instance and configuring it as an AD domain controller. This step takes about 15 to 20 minutes to complete.

To use the template, you must already have an EC2 key pair. If you don’t, see the EC2 documentation for instructions.

When you click the link to the template, it starts the CloudFormation wizard with the appropriate Amazon S3 URL already loaded; you can just click Next Step to proceed. If you’re not sure what values to use in the wizard, we suggest the following:

  • DomainDNSName. Use corp.example.com.
  • DomainnetBIOSName. Use CORP. This will be the domain for the Administrator user that the template creates (CORPAdministrator).
  • KeyPairName. Enter the name of a key pair in EC2. (Don’t enter a .pem file name; use the name as reported by EC2.) You’ll use the private key in the key pair to decrypt the password for logging in to the EC2 instance.
  • SourceCidForRDP. Enter the IP address (with a 32-bit prefix, e.g. /32) for the computer from which you’ll use Remote Desktop Connection to access the EC2 instance.

After the CloudFormation stack creation is complete, sign in to the EC2 instance as domain administrator and do the following:

  1. Using Server Manager, select the topmost node.
  2. Under Security Information, click Configure IE ESC.
  3. Under Administrators, select Off to disable Internet Explorer Enhanced Security Configuration.

Next, using the Active Directory Users and Computers, create an AD user named Bob Smith. In the User logon name box, enter Bob. After that, create two AD groups named AWS-Production and AWS-Dev and add Bob to these two groups.

Right-click the name Bob Smith, and then click Properties. In the General tab of the Properties window, enter bob@example.com in the E-mail text box.

Note   Be sure that you assign an email address to Bob and that you use AWS-Production and AWS-Dev as group names as described here. Later parts of this walkthrough assume these settings.

2. Set up Shibboleth as the identity provider

Shibboleth comes with a wizard-based setup that takes care of installing and configuring Shibboleth. You can set up Shibboleth on the EC2 instance that’s running your AD domain by following the IdPQuickInstall instructions on the Shibboleth website. To work through this blog post, download Shibboleth 2.x. The last release that includes a Windows .msi installer is Shibboleth 2.4.3.

In the wizard, you must complete two specific values:

  • For DNS Name Host, specify the full computer name (for example, win-p7ifu0exxxx.corp.example.com) of your EC2 instance. This name is listed under Full computer name in Control Panel > System and Security > System. However, it’s important that you use an all lowercase version of the full computer name.
  • For the Username and password boxes, enter the username (Administrator) and password that you used when you connected to the EC2 instance.

You can leave the default values for other prompts in the wizard.

If all goes well, you’ll see a web page confirming the setup was successful. Skip the instructions listed under Next Steps on this page, because you need to make few configuration changes first.

In a production environment, the next step would be to acquire a public key certificate from a certifying authority (CA) and use it to secure the communication between Shibboleth and AD. For demonstration purposes and because both AD and Shibboleth are running on the same EC2 instance, you can disable the need for a certificate by modifying the Shibboleth configuration using these steps:

  1. Go to the following folder:
    C:/Program Files (x86)/Internet2/Shib2IdP/conf
  2. In the login.config file, set tls=”false”.
  3. In the attribute-resolver.xml file, set useStartTLS=”false”.
  4. At the command line in the EC2 instance, run the following two commands: 
    sc stop tomcat6
sc start tomcat6

Shibboleth is now ready to act as the identity provider.

3. Set up Amazon Web Services as the service provider

Now you can configure AWS as the service provider. For this you need the metadata document of the identity provider. On the EC2 instance, open a browser and navigate to https://hostname/idp/profile/Metadata/SAML, replacing hostname with the full computer name of your EC2 instance (for example, win-p7ifu0exxxx.corp.example.com).

You will see a message about a problem with the website’s security certificate; this is expected, because you are not using a public key certificate from a CA when you access the identity provider. Click Continue to this website.

The browser displays the metadata document from Shibboleth. Save the document on your computer.

Next, go to the AWS Management Console and create a SAML provider named Shibboleth, using the instructions in the IAM User Guide. Be sure you use the name Shibboleth, because later parts of this walkthrough assume that name. As part of that process, you’ll upload the identity provider metadata document.

The next step is to create IAM roles that define permissions that federated users will have. You’ll create two roles—Shibboleth-Production and Shibboleth-Dev. Be sure to use these names, because later parts of this walkthrough assume these names. The idea is that you’ll establish a one-to-one mapping between the AD groups you created earlier and IAM roles in your AWS account; the mapping will be based on a naming convention. When everything is configured, a user in AWS-Production group will be able to perform only AWS actions permitted by a role named Shibboleth-Production, and users in AWS-Dev group will have the permissions defined in the Shibboleth-Dev role.

Follow the instructions in the IAM User Guide to create roles for identity provider access (Web SSO) named Shibboleth-Production and Shibboleth-Dev. For the Shibboleth-Production role, use the Administrator Access policy template to give the role permissions. For the Shibboleth-Dev role, use the Read Only Access policy template.

4. Configure Shibboleth to use AWS as a relying party

The identity provider does not know about the service provider yet, so the next step is to add AWS as a relying party in Shibboleth. In the EC2 instance, open the following file:

C:/Program Files (x86)/Internet2/Shib2IdP/conf/relying-party.xml

Inside the metadata:MetadataProvider element with id=”ShibbolethMetadata”, add the following snippet:

<metadata:MetadataProvider
  id="AWS"
  xsi:type="metadata:FileBackedHTTPMetadataProvider"
  metadataURL="https://signin.thinkwithwp.com/static/saml-metadata.xml"
  backingFile="C:/Program Files (x86)/Internet2/Shib2Idp/metadata/aws.xml" />

This entry tells Shibboleth that AWS is a relying party and its metadata is available at https://signin.thinkwithwp.com/static/saml-metadata.xml.

After the rp:DefaultRelyingParty element—that is, after the </rp:DefaultRelyingParty> tag—add the following snippet, replacing hostname with the full computer name (lowercase) of your EC2 instance:

<rp:RelyingParty id="urn:amazon:webservices" provider="https://hostname/idp/shibboleth" defaultSigningCredentialRef="IdPCredential">
     <rp:ProfileConfiguration
       xsi:type="saml:SAML2SSOProfile"
       includeAttributeStatement="true"
       assertionLifetime="PT5M" assertionProxyCount="0"
       signResponses="never" signAssertions="always"
       encryptAssertions="never" encryptNameIds="never"
       includeConditionsNotBefore="true"
       maximumSPSessionLifetime="PT1H" />
</rp:RelyingParty>

5. Configure Shibboleth to generate AWS-specific assertions

The final step is to set some additional attributes that AWS will look for in the SAML assertion: awsRoles and awsRoleSessionName. Open the following file:

C:/Program Files (x86)/Internet2/Shib2IdP/conf/attribute-resolver.xml

Add the following snippet just before the resolver:DataConnector element, replacing accountid with your AWS account ID. (There are two instances of accountid.)

<resolver:AttributeDefinition id="awsRoles" xsi:type="ad:Mapped" sourceAttributeID="memberOf">
  <resolver:Dependency ref="myLDAP"/>
  <resolver:AttributeEncoder
    xsi:type="enc:SAML2String"
    name="https://thinkwithwp.com/SAML/Attributes/Role" friendlyName="Role" />
  <ad:ValueMap>
    <ad:ReturnValue>arn:aws:iam::accountid:saml-provider/Shibboleth,arn:aws:iam::accountid:role/Shibboleth-$1</ad:ReturnValue>
    <ad:SourceValue>CN=AWS-([^,]*),.*</ad:SourceValue>
  </ad:ValueMap>
</resolver:AttributeDefinition>

<resolver:AttributeDefinition id="awsRoleSessionName" xsi:type="ad:Simple" sourceAttributeID="mail">
    <resolver:Dependency ref="myLDAP"/>
    <resolver:AttributeEncoder
      xsi:type="enc:SAML2String"
      name="https://thinkwithwp.com/SAML/Attributes/RoleSessionName"
      friendlyName="RoleSessionName" />
</resolver:AttributeDefinition>

The first attribute definition (id=”awsRoles”) configures Shibboleth to parse the memberOf attribute of the authenticated user to look for groups starting with “AWS-” (ad:SourceValue tag). Based on this, Shibboleth sets the awsRoles attribute in the assertion to include the corresponding role name that starts with “Shibboleth-” (ad:ReturnValue tag). For example, if authenticated user Bob is a member of AD group AWS-Production, the awsRoles attribute in the assertion will include a role with the following name: arn:aws:iam::accountid:role/Shibboleth-Production.

The second attribute definition (id=”awsRoleSessionName”) configures Shibboleth to use the mail attribute of the authenticated user to set the value of the awsRoleSessionName attribute in the assertion. This is why it’s essential for the AD user to have an email address defined in AD, so that this value is not empty in the assertion.

Now that Shibboleth is configured to generate the required AWS attributes, you need to ensure that these attributes get included in assertions. Open the following file:

C:/Program Files (x86)/Internet2/Shib2IdP/conf/attribute-filter.xml

Add the following snippet just before the closing tag of the afp:AttributeFilterPolicy element with id=”releaseToAnyone”. (The snippet you’re adding must follow the existing content that’s already inside the afp:AttributeFilterPolicy element.)

<afp:AttributeRule attributeID="awsRoles">
    <afp:PermitValueRule xsi:type="basic:ANY"/>
</afp:AttributeRule>
<afp:AttributeRule attributeID="awsRoleSessionName">
    <afp:PermitValueRule xsi:type="basic:ANY"/>
</afp:AttributeRule>

6. Sign in using identity provider-initiated flow

In order for all the configuration changes to take effect, you need to restart Tomcat. At the command line in the EC2 instance, run the following two commands:

sc stop tomcat6
sc start tomcat6

After that, on your EC2 instance, point your web browser to the following URL. Replace hostname with the full computer name of your EC2 instance.

https://hostname/idp/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices

As before, you’ll see a message about a problem with the website’s security certificate. Click Continue to this website.

You will see the default Shibboleth login page as shown in the following screenshot. Enter the user name and password for Bob and then click Login.

Screenshot of the default Shibboleth login page

If you don’t see this (for example, if you see a 404 message), do this:

  • Double-check that you updated the configuration files correctly, as described in the previous section.
  • Check the Shibboleth log file (C:/Program Files (x86)/Internet2/Shib2IdP/logs/idp-process.log). For example, an “invalid content” error might indicate that a configuration file could not be parsed correctly.

If everything is working, you’ll see a page similar to the following. Because you made Bob a member of both the AWS-Production and AWS-Dev AD groups, you will see two roles. Select one and then click Sign In.

Screenshot showing two roles that include Bob

From here, you’re taken to the AWS Management Console directly, without having to enter any other credentials. This is single sign-on as a federated user! You (as Bob) will be able to perform only those AWS actions that are permitted by the role you selected in the previous step—for example, if you selected Shibboleth-Dev role, you will not be able to perform any write actions.

Screenshot showing being signed in to the AWS Management Console as Bob

To summarize, you used AD as an identity store and Shibboleth as an identity provider to configure SAML-based federation to the AWS. This enabled your AD users to get single sign-on access to AWS Management Console.

If you have questions, comments, or suggestions, you can post them below or start a thread in the IAM forum.

-Shon

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