OpenAM JavaScript Wrapper

OpenAM JavaScript Wrapper

A long time ago I started writing an example of a small web application that was using the OpenAM REST APIs. Once working on this task, I realised it was relatively easy to create wrappers around the ForgeRock APIs in any programming language. I decided to start with a JavaScript wrapper.

I am a bit rusted in this area, and since I was doing it only for fun and on my “idle” time, it took a while.  Anyway, here the openam.js wrapper and the openamUtils.js utility library.

This is a work in progress, and also a JavaScript coding exercise. Initially it is leveraging the Authentication and SSO API’s but with a little help of the community it can be extended to cover the whole set of APIs, inclulding Authorization, OAuth2, OIDC, UMA, STS, etc. It can also be an idea to start similar wrappers for the OpenIDM and OpenDJ REST APIs. It is NOT supported NOR endorsed by ForgeRock. If you feel it is useful, please contribute.

openam.js is a small library/wrapper of some of the REST APIs of OpenAM. The intention is to provide an easy way to integrate the calls in your Client JavaScript code without needing to implement the REST code yourself.

openamUtils.js is another wrapper to render configurable Login Buttons and Login Boxes. It uses openam.js and the css style contained in the github repository, of course you can adjust the css to your needs but it should work nicely out of the box. This wrapper does not need JQuery, but of course you can combine it with any other JS UI framework. In the future I would like to create another library combined with bootstrap.

Several examples are included together with the source code:

Each example is a single web page.

Before trying the library and examples be sure to configure your OpenAM to support CORS (see this blog entry for more info on CORS and OpenAM, hint it involves to modify the web.xml of OpenAM or modify your Web Container -Tomcat for example has CORS support-).

The documentation is available for both libraries here:

Here two videos showing how to use the libraries.

  1. OpenAM Configuration of the instance to be used with the examples.



  2. And here a video showing how the examples included in the github code work:



Give the libraries a try and send us your feedback. Again you are more than welcome to contribute.

OpenAM as a SAMLv2 IdP for the AWS Administration console. 2nd Part

OpenAM as a SAMLv2 IdP for the AWS Administration console. 2nd Part.

In a previous blog post, we defined a fixed role for the users federating to AWS, however if we want to add flexibility and allow each user to map to a different role, depending on the type of user, we can assign the role using a profile attribute.

Here a couple of configuration examples/use-cases.

a) Users wanting to have multiple federated logins for different roles in the same AWS account

In this case the AWS account will be the same, but the IdP account will be different depending on the role that the user wants to use. For example a user demo-dev with an attribute/role holding a “Dev” role can map to an account in AWS with a role with certain “development” permissions, while another account demo-prod can hold a different “Production” role in the same attribute/role and map to the same AWS account with a different role with “Production” permissions.

In this case we have two OpenAM IdP login names for the same user account in AWS, each with a different role. In our example we have “demo-dev” and “demo-prod”:

Screen Shot 2016-02-10 at 11.07.06

We are going to use one of the user’s profile attributes to set the Role for the user. In this example we will use the “User Alias List” attribute to set it up, but in a real case scenario you might want to set your own specific attribute for it, like for example “AWSRole”.

For this example (as in the previous post) the Attribute “mail” will be used to map the AWS user account and it contains the value The attribute “User Alias List” will be used to map the AWS Wole and it contains the Role value:

  • mail:
  • iplanet-am-user-alias-list: arn:aws:iam::123456789012:role/sso-Dev,arn:aws:iam::123456789012:saml-provider/forgerocklabs

Screen Shot 2016-06-06 at 11.04.30

For the “demo-prod” user we will use a different Role:

  • mail:
  • iplanet-am-user-alias-list: arn:aws:iam::123456789012:role/sso-Production,arn:aws:iam::123456789012:saml-provider/forgerocklabs

Screen Shot 2016-06-06 at 11.05.21

Now we need to map the attributes of the User Profile to the attributes in teh SAMLv2 ASsertion, this is easy. In the Federation tab, select the AWS Service Provider and go to the “Assertion Processing” sub tab (See previos post for more info on how to get there), and set the Attribute Mapper to:

So it looks like this:

Screen Shot 2016-06-06 at 10.16.22

That’s it, now if you use the IdP Inititated SSO and login as demo-dev in OpenAM, you will get logged in in AWS as and if you login in OpenAM as demo-prod you will be mapped into in the AWS console.

Now the other case.

b) Users wanting to have one federated login for different roles in the same AWS account

In this case the AWS account will be the same, and the IdP account will have multiple roles assigned, with a configuration like this then the user will need to select during login time what role to use.

The configuration in OpenAM is the same, except that the User Account should contain all the possible roles it can use. In this example we have the user “demo” with both roles sso-Dev and sso-Production assigned to the multivalued attribute “User Alias List” (as mentioned before this is just for the sake of the example).

Screen Shot 2016-06-06 at 11.07.45

The AWS SP Configuration remains the same, but now when using the IdP Initiated SSO URL and login in as “demo”, the user will see a selection menu from the AWS console, indicating he/she needs to select what role to use:

Screen Shot 2016-06-06 at 10.52.07

There are more options to configure the OpenAM to federate with the AWS console, the OpenAM flexibility allows to define Custom SP Attribute mappers (plug-ins) to for example construct values out of user profile attributes, session attributes or even external (3rd party) attributes. So depending on your needs there is always a solution using OpenAM.

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.