How to read and write shared state in the OpenAM Scripted Module

If you’ve used OpenAM for a while, you will probably know that it has a concept of shared state; a map of values that can be passed from one authentication module to the next in an authentication chain. You can use the iplanet-am-auth-store-shared-state-enabled and iplanet-am-auth-shared-state-enabled keywords to direct modules to put credentials into shared state, or read the credentials from shared state and try to use them.

If you have a scripted module in your OpenAM authentication chain,  you may want to pass credentials from the scripted module to other modules in the chain. Or you may want to access credentials that have been set in a preceding authentication module.

To read the username and password entered in a previous module in the authentication chain, you can use the following javascript in your server side authentication script:

//get username and password from shared state var someUserName = sharedState.get(""); var somePassword = sharedState.get("");

And to put a username and password into shared state:
//set the username and password for other authentication modules to use sharedState.put("",someUserName); sharedState.put("",somePassword);

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

Federated Authorization Using 3rd Party JWTs

Continuing on the theme of authorization from recent blogs, I’ve seen several emerging requirements for what you could describe as federated authorization using an offline assertion.  The offline component pertaining to the fact that the policy decision point (PDP), has no prior or post knowledge of the calling user.  All of the subject information and context are self contained in the PDP evaluation request. Eg a request that is using a JSON Web Token for example.

A common illustration could be where you have distinct domains or operational boundaries that exist between the assertion issuer and the protected resources. An example could be being able to post a tweet on Twitter with only your Facebook account, with no Twitter profile at all.

A neat feature of OpenAM, is the ability to perform policy decision actions without having prior knowledge of the subject, or in fact having the subject have a profile in the AM user store.  To do this requires a few neat steps.

Firstly let me create a resource type – for interest I’ll make a non-URL based resource based on gaining access to a meeting room.

For my actions, I’ll add in some activities you could perform within a meeting room…

Next step is to add in a policy set for my Meeting Room #1 and a policy to allow my External Users access to it.

My subjects tab for my policy is the first slight difference to a normal OpenAM policy.  Firstly my users who are accessing the meeting are external, so will not have a session or entry in the OpenAM profile store. So instead of looking for authenticated users, I switch to check for presented claims.  I add in 3 claims – one to check the issuer (obviously only trusted issuers are important to me….but at this step we’re not verifying the issuer, that comes later..), the audience and a claim called Role.  Note the claims checks here are simply string comparators not wild cards and no signature checks have been done.

I next add in some actions that my external users can perform against my meeting room.  As managers, I add in the ability to order food, but they can’t use the white board!

So far pretty simple.  However, there is one big thing we haven’t done.  That is to verify the presented JWT.  The JWT should be signed by the 3rd party IDP in order to provide authenticity of the initial authentication.  For further info on JWT structure see RFE7519 –  but basically there are 3 components, a header, payload and signature.  The header contains algorithm and data structure information, the payload the user claims and the signature a crypto element.  This creates a base64 encoded dot-delimited payload.  However…we need to verify the JWT is from the issuer we trust.  To do this I create a scripted policy condition that verifies the signature.

This simply calls either a Groovy or JavaScript that I create in the OpenAM UI or upload over REST.

The script basically does a check to make sure a JWT is present in the REST PDP call, strips out the various components and creates a corresponding signature based on a shared secret.  If the reconstructed signature matches the submitted JWT signature we’re in business.

The script calls in the ForgeRock JSON, JSE, JWS and JWT libraries that are already being used throughout the product, so we’re not having to recreate anything new here.

To test the entire flow, you need to create a JWT with the appropriate claims from a 3rd party IDP. There are lots of online generators that can do this.  I used this one to build my JWT.

Note the selection of the algorithm and key.  The key is needed in the script on the AM side.

I can now take my newly minted JWT and make the appropriate REST call into OpenAM.

The call sends a request into ../json/policies?_action=evaluate with my payload of the resource I’m trying to access and my JWT (note this is currently submitted both within the subject.jwt attribute and also the environment map due to OPENAM-8893).  In order to make the call – remember my subject doesn’t have a session within OpenAM – I create a service account called policyEvaluator that I use to call the REST endpoint with the appropriate privileges.

A successful call results in access to the meeting room, once my JWT has been verified correctly:

If the signature verification fails I am given an advice message:

Code for the policy script is available here.

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

Scripted OpenID Connect Claims and Custom JWT Contents

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

OpenID Connect has been the cool cat on the JSON authorization cat walk for some time.  A powerful extension to the basic authorization flows in OAuth2, by adding in an id_token. The id_token is a JWT (JSON Web Token, pronounced ‘jot’ but you knew that) that is cryptographically signed and sometimes encrypted – depending on the contents.

The id_token is basically separate to the traditional access_token, containing details such as which authorization issued the token, when the user or entity authenticated and when the token will expire.

OpenAM has supported implementations for OpenID Connect for a while, but a more recent feature is the ability to add scripting support to the returnable claims.  Adding scripting here, is a really powerful feature.  Scripts can be either Groovy or JavaScript based, with a default Groovy script coming with OpenAM 13 out of the box.

The script is basically allowing us to creatively map scopes into attribute data, either held on the user’s identity profile, or perhaps dynamically created at run time via call outs or via applied logic.

A quick edit of the of the out of the box OIDC claims script, allows me to add a users status from their profile held in OpenDJ, into the data available to presented scopes.  I’ve used the inetuserstatus attribute simply as it’s populated by design.  By adding “status” to the scopes list on my OIDC client profile, allows it to be called and then mapped via the script.

So pretty simply I can add in what is made available from the user’s identity profile, which could include permissions attributes or group data for example.

Another neat feature (which isn’t necessarily part of the OIDC spec), is the ability to add claims data directly into the id_token – instead of making the extra hop to the user_info endpoint with the returned access_token.  This is useful for scenarios where “offline” token introspection is needed, where an application, API, device or service, wants to perform local authorization decision making, by simply using the information provided in the id_token.  This could be quite common in the IoT world.

To add the claims data into the signed JWT id_token, you need to edit the global OIDC provider settings (Configuration | Global | OAuth2 Provider).  Under this tab, use the check box “Always return claims in ID Tokens

Now, when I perform a standard request to the ../access_token endpoint, including my openid scope along with my scripted scope, I receive an id_token and access_token combination the same as normal.


So I can either call the ../user_info endpoint directly, with my access_token to check my scope values (including my newly added status one) or use a tool or piece of code to introspect my id_token.  The website is a quite a cool tool to introspect the id_token by doing the decode and signing verification automatically online.  The resulting id_token introspect would look something like this:
Note the newly added “status” attribute is in the verified id_token.