SAML2 IDP Automated Certificate Management in FR AM

ForgeRock AM 5.0 ships with Amster a lightweight command line tool and interactive shell, that allows for the automation of many management and configuration tasks.

A common task often associated with SAML2 identity provider configs, is the updating of certificates that are used for signing and the possible encryption of assertions.  A feature added in 13.0 of OpenbAM, was the ability to have multiple certificates within an IDP config.  This is useful to overcome the age old challenge of how to handle certificate expiration.  An invalid cert can brake integrations with service providers.  The process to remove, then add a new certificate, would require any entities within the circle of trust to retrieve new metadata into their configs – and thus create downtime, so the timing of this is often an issue.  The ability to have multiple certificates in the config, would allow service providers to pull down meta data at a known date, instead of specifically when certificates expired.

Here we see the basic admin view of the IDP config…showing the list of certs available.  These certs are stored in the JCEKS keystore in AM5.0 (previously the JKS keystore).

So the config contains am1 and am2 certs – an export of the meta data (from the ../openam/saml2/jsp/exportmetadata.jsp?entityid=idp endpoint) will list both certs that could be used for signing:

The first certificate listed in the config, is the one that is used to sign.  When that expires, just remove from the list and the second certificate is then used.  As the service provider already has both certs in their originally downloaded metadata, there should be no break in service.

Anyway….back to automation.  Amster can manage the the SAML2 entities, either via the shell or script.  This allows admins to operationally create, edit and update entities…and a regular task could be to add new certificates to the IDP list as necessary.

To do this I created a script that does just this.  It’s a basic bash script that utilises Amster to read, edit then re-import the entity as a JSON wrapped XML object.

The script is available here.

For more information on IDP certificate management see the docs here.

This blog post was first published @, included here with permission from the author.

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

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

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

2016-02-01 12:06:12 (2.38 MB/s) - '' saved [4743/4743]

$ ls
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 “” (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 “”:

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 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:"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:
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:
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.

Using SAML Assertion Attributes in ForgeRock OpenAM – Episode 03/04 : Configuring Transient Federation in ForgeRock OpenAM

This blog post was first published @, included here with permission.

This is the third episode from a four part video made on using SAML v2 Assertion attributes in an application protected by ForgeRock OpenAM. In the interest of continuity and also to get the context accurately, it may make sense to read/view the blog posts in the following order:

1. Protecting a J2EE Application with ForgeRock OpenAM
2. Configuring Federation in ForgeRock OpenAM
3. Configuring Transient Federation in ForgeRock OpenAM
4. Using SAMLv2 Assertion Attributes

Let me throw a picture at you:


The diagram is a slightly modified version of the one that you would have seen in my earlier blog entry. It has one additional user in the Identity Provider (which of course seems like a world famous detective and that’s no coincidence), but no corresponding entry in the Service Provider. In the Identity Federation Configuration earlier, we saw how a user with an id ‘demo’ in the Identity Provider linked her account with her id in the Service Provider. But there can be situations, when we may want to use Federation with identities only at the IDP, still gaining access to the applications protected by the SP. That’s where Transient Federation comes into play. It maps the identities from IDP to an anonymous user in the SP (many to one mapping).


ForgeRock OpenIG as SAML 2.0 Service Provider

This blog post was first published @, included here with permission.

This post is based on the ForgeRock Documentation on configuring OpenIG as SAML 2.0 Service Provider. The video logs embedded just below this write up is a visual representation of what is already there in the document that I mentioned above. For a detailed study, please read through the documentation and then sit back, relax and watch the demonstration in the screen-cast below

SAML 2.0 as you probably know is a standard to exchange information between a SAML authority (a Identity Provider a.k.a IDP) and a SAML Consumer (a Service Provider a.k.a SP). In the demonstration that follows ForgeRock OpenAM acts as an Identity Provider and ForgeRock OpenIG acts as a Service Provider. So the authentication of a user is done by the IDP, who will then send a piece of information (Assertion) to the SP that could contain the attributes of user from the user’s profile in the IDP DataStore. SP will then use the information thus obtained (Assertion) to take further action (like giving access to the user etc.)

There are two ways of getting this done:
(i) SP initiated SSO
(ii) IDP initiated SSO

In simple words, in a SP initiated SSO, the user contacts the Service Provider, who in turns gets in touch with the Identity Provider, who would validate the user credentials and then exchange a piece of information (Assertion) that could contain the user attributes to the Service Provider. Whereas a IDP initiated SSO, the IDP will authenticate the user, and would then send an unsolicited message (Assertion) to the SP, who would then take further action (like giving access to the user etc.)

The following two illustrations might give a rough idea:


In our story (above in the illustration and below in the video), a user authenticates against ForgeRock OpenAM (IDP), who will send then an assertion (containing user’s mail and employeenumber attribute) to ForgeRock OpenIG (Service Provider), who will apply filters (like extracting the attributes from assertion and posting it as username and password) to post the user’s credentials to a protected application (Minimal HTTP Server)

If you’ve got a vague picture on what’s discussed above, I’d believe it’ll be clearer after watching the video below: