OpenAM as a SAMLv2 IdP for the Amazon Web Services (AWS)

OpenAM as a SAMLv2 IdP for the AWS Administration console.

AWS can use third party Identity Providers so that users can perform AWS management in the AWS administration console.
AWS can integrate with IdP’s that support SAMLv2 or OpenID Connect. OpenAM supports both protocols and can act as the Identity Provider for the AWS management console.

Why integrating AWS with OpenAM as an IdP?

If you want to enable advanced authentication, such as MFA or a third-party authentication service or if you already own an installation of OpenAM, and you  want to leverage the users defined in OpenAM/OpenDJ so they can access AWS. Or maybe you don’t want to manually add the users into AWS since you already have OpenIDM dealing with provisioning into OpenDJ/OpenAM and you don’t want AWS in its own user-silo.

To define OpenAM as the IdP we need to define trust between AWS and OpenAM.  Let’s first work on a configuration that uses SAML2. In a later entry I will describe how to use OpenID Connect.

Step 1. First you need your OpenAM to provide SAML2 IdP Services. 

Create a SAML2 IdP in OpenAM if you don’t already have one.
There are several ways to create an IdP, but for the sake of this example we will use the Common Tasks wizard.
In the common tasks tab select “Create a Hosted Identity Provider”
Screen Shot 2016-02-01 at 11.15.37
In the “Create a SAMLv2 Identity Provider on this Server” screen, fill in the needed parameters to create the IdP.
Note: In this example we have previously created a signing key and imported it into the OpenAM Java Key Store, in this example the alias identifying this key is forgerocklabs. In this steps it is not shown how to change and generate your own signing key, but you can take a look here, on how to do it. It is strongly recommended not to use the “test” alias that comes with OpenAM as an example.
Screen Shot 2016-02-01 at 11.16.23
Create the IdP. After a message indicating that the creation was successful you can go and verify that the entity was created successfully in the Federation Tab:
 Screen Shot 2016-02-01 at 16.13.06
You should see a new Circle of Trust (if that is what you indicated in the wizards screen).
Screen Shot 2016-02-01 at 11.17.33
And the Hosted IdP Should appear in the list of Entity Providers:
Screen Shot 2016-02-01 at 11.17.42

Step 2. Export your Identity Provider metadata

Let us now export the metadata of the IdP into a file. Again there are several ways to do this, but for this example we are going to do it manually. It can be done from the web browser using the exportmetadata URL or it can be done using wget from your command line, here an example of both:
a) Using the web browser:
Screen Shot 2016-02-01 at 12.07.06-blured
You would need to copy and paste the XML above into a file that we will use later in the AWS Console.
b ) Using wget in Unix and Unix-like systems:
$ wget -O idp.forgerocklabs.org.xml https://idp.forgerocklabs.org/openam/saml2/jsp/exportmetadata.jsp?role=idp&realm=/&entityid=idp.forgerocklabs.org

Resolving idp.forgerocklabs.org… xx.xxx.xxx.xxx.xxx
Connecting to idp.forgerocklabs.org|xxx.xxx.xxx.xxx|:yyy... connected.
HTTP request sent, awaiting response... 200 OK
Length: 4743 (4.6K) [text/xml]
Saving to: 'idp.forgerocklabs.org.xml'

idp.forgerocklabs.o 100%[=====================>]   4.63K  --.-KB/s   in 0.002s

2016-02-01 12:06:12 (2.38 MB/s) - 'idp.forgerocklabs.org.xml' saved [4743/4743]

$ ls
idp.forgerocklabs.org.xml
So far, we are done with the second step. Let’s now go and configure things in the AWS administration console, and let’s get back to OpenAM later.

Step 3. Configure AWS to use a third party SAMLv2 IdP

Login into your AWS Console as an Administrator
Screen Shot 2016-02-01 at 10.52.41
Click the “Identity & Access Management” option. That will take you to the area where we can define a third-party IdP.
 Screen Shot 2016-02-01 at 10.59.40
Let’s configure the OpenAM IdP that we created in the first step. Select “Identity Providers” from the options listed above.
Screen Shot 2016-02-01 at 11.43.52
Now let’s select the Create Provider option and select SAML as Provider Type, select a name to the Provider Name (it can be anything that makes sense to you) and Choose the file that contains your IdP Metadata which we saved in step 1:
Screen Shot 2016-02-01 at 12.15.04
We are then presented with a screen to verify, if everything is correct click the Create button:
Screen Shot 2016-02-01 at 12.15.21
After the successful creation you should see the following screen:
Screen Shot 2016-02-01 at 12.15.39

Step 4. Create the Roles that will be associated with the users that will use the OpenAM

The next step is to create an AWS IAM role that establishes a trust relationship between IAM and OpenAM as a Federate IdP.
The role can also define what users authenticated by the OpenAM are allowed to do in AWS. One can use the IAM console to create this role.
Screen Shot 2016-02-01 at 13.51.30
Let’s select “Create New Role” and specify a “Role Name” again this can be anything that makes sense to you, in this example we are using the name “sso”:
Screen Shot 2016-02-01 at 13.51.45
Then Click next to select the “Role for Identity Provider Access” and click the “Grant Web Single Sign-On (WebSSO) access to SAML providers” option:
Screen Shot 2016-02-01 at 13.57.59
If you have more than one SAML provider, select the one you want to configure. In our example, we have just created previously the forgerocklabs IdP. Click Next Step:
Screen Shot 2016-02-01 at 14.00.18
The “Verify Role Trust” screen appears and you can review it. Notice the “Condition” in the role. This will determine what users can do SSO with AWS. In the example above, the Audience in the SAML assertion must contain “https://signin.aws.amazon.com/saml” (this condition is added by default by AWS). Additional attributes can be added to filter what users can do SSO with AWS, for example you can specify that only uses with a SAML attribute of “organiztionName” containing the name of your organization will be allowed to sig in. . In this example we are leaving it just like that, no additional attributes.  Verify that it looks correct, write down the “Federated” value attribute, because that is the ARM for our IdP, in our example: “arn:aws:iam:123456789012:saml-provider/forgerocklabs”.  Click “Next Step”:
Screen Shot 2016-02-01 at 14.01.02-blur
Now, we need now to attach the policy/policies that will be associated with the Authenticated users. This is basically mapping permissions. In this example we will add Full Access to the console, but in your case you need to decide what Policies you want to attach to users that will be doing SSO with the OpenAM Identity Provider.
Screen Shot 2016-02-01 at 14.02.09
 In this example let’s scroll down and select AmazonEC2FullAccess, but for your specific case you would need to select the permissions you wish to assign to the roleScreen Shot 2016-02-01 at 14.02.42
Click “Next Step” and make a note of the Role ARN, we will needed when configuring the SP in the OpenAM. In this example arn:aws:idm::123456789012:role/sso  and click “Create Role”:
Screen Shot 2016-02-01 at 14.02.52-blur
The role gets created and we see it listed. If you need to create more roles you can repeat the Step 4.
Screen Shot 2016-02-01 at 14.03.16

Step 5. Configuring the AWS SAMLv2 SP into OpenAM

Let’s now import the AWS SAML SP Configuration into the OpenAM
Login into OpenAM as the administrator. Navigate to the Federation tab.
Screen Shot 2016-02-01 at 16.13.06
Navigate to the Entity Providers section and click the “Import Entity” button:
Screen Shot 2016-02-01 at 16.12.58
In the “Import Entity Provider” screen fill in the AWS Metadata URL “https://signin.aws.amazon.com/static/saml-metadata.xml”:

Screen Shot 2016-02-01 at 16.14.02

Once you click “OK” and everything goes fine, you should see a message like this:
Screen Shot 2016-02-01 at 16.14.50
and a new Remote SP Entity should appear in the list of “Entity Providers”:
 Screen Shot 2016-02-01 at 16.15.06
Now we need to add the “urn:amazon:webservices” remote service provider to the Circle of Trust where our “idp.forgerocklabs.org” IdP has been defined (notice that you may have more than one CoT).
Screen Shot 2016-02-01 at 16.15.22
Select the aws Circle of Trust, and in the “Edit Cicle of Trust” screen add the urn:amazon:webservices SP:
 Screen Shot 2016-02-01 at 16.16.03
Click “Save” and then the Back button to return to the Federation screen, where now we should see the was CoT containing our IdP and the SP:
Screen Shot 2016-02-01 at 16.33.04
We are almost there, we still need to edit our “urn:amazon:webservices” remote SP to map some attributes that AWS needs.
Click on the urn:amazon:webservices Service Provider and navigate to the “Assertion Processing” sub tab:
Screen Shot 2016-02-01 at 16.45.14
Add the following two mappings in the Attribute Mapper Attribute Map configuration:
Mapping 1: A mapping of the Role attribute in the assertion to the Role ARN and the IdP ARN. Remember we wrote down the Role ARN in a previous step and the IdP ARN, we separate them with commas, like this:
https://aws.amazon.com/SAML/Attributes/Role="arn:aws:iam::123456789012:role/sso,arn:aws:iam::123456789012:saml-provider/forgerocklabs"
Screen Shot 2016-02-02 at 11.39.38
Mapping 2: The mapping of the name used for the session, in our example we will use the email address of the user profile in the User Store used in OpenAM. It can however be any other attribute identifying uniquely the user:
https://aws.amazon.com/SAML/Attributes/RoleSessionName=mail
Screen Shot 2016-02-02 at 11.40.25
Save your mappings:
 Screen Shot 2016-02-01 at 16.49.28-NEW
We are done with the configuration, now we need to test.  Go back to the Federation tab and log out from the OpenAM Console.

Step 6. Test the configuration

 
We need to use the IdP Initiated SSO URL. In our case:
https://idp.forgerocklabs.org/openam/saml2/jsp/idpSSOInit.jsp?metaAlias=/idp1&spEntityID=urn:amazon:webservices
Notice that the URL is composed of some URL parameters, these are:
  • metaAlias: The metaAlias of your Identity Provider. In this example is /idp1, but this can be something different (like /idp). You can verify it from your IdP Configuration in your console or from your metadata.
  • spEntityID: This is the name of the entity describing the AWS Service Provider, for AWS this is “urn:amazon:webservices” though Amazon can decide to change this, it might be that this will remain fixed for a long time.
Give it a shot and try the URL in your browser.  You should see the OpenAM login page. I will try with my user demo and its password, just be sure that your user has a valid email address configured, this is because in this example we are using the attribute mail to be passed in the SAMLv2 assertion:
Screen Shot 2016-02-01 at 19.28.49
After login we will see we are redirected to AWS and we get logged in. Notice the session name in this example, it corresponds to the email address of our “demo” user:
Screen Shot 2016-02-01 at 19.25.34
And that’s it. This is the manual procedure, the good thing is that the whole stuff can be scripted using both OpenAM ssoadm and the AWS CLI. But that is something we need to write in a different blog entry.