13 May 2016

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.

NB - the appropriate classes and also the primitive byte[], need to be added the the Java white list for the policy engine, within the global configuration,

3 March 2016

In flight Authorization Management

Access request, or authorization management is far from new.  The classic use case is the use of a workflow process that, via approval, updates a profile or account with a persisted attribute/group/permission in a target system.  At run time, when a user attempts to perform an action on the target system, the system locally checks the profile of the user and looks for particular attributes that have been persisted.

A slight variation on this theme, is to provide a mechanism to alter (or at least request to alter) the persisted permissions at near run time.  An example of this, is to leverage OAuth2 and use of a tokeninfo endpoint that can convert access_token scope data into scope values, that are used by resource server to handle local authorization.  Dependent on the content of the scope values, the resource server could provide a route for those persisted entries to be updated - aka an access request.


In the above example, we have a standard OAuth2 client-server relationship on the right hand side - it just so happens we're also using the device flow pin and pair paradigm that is described here. Ultimately the TV application retrieves user data using OAuth2 - one of the attributes we send back to the TV, is an attribute called waterShedContent - this is a boolean value that governs whether the user can access post 9pm TV shows or not.  If the value is false, the TV player does not allow access - but does then provide a link into OpenIDM - which can trigger a workflow to request access.

Above flow goes something like this:

  1. User performs OAuth2 consent to allow the TV player access to certain profile attributes (0 is just the onboarding process for the TV via pin/pair for example)
  2. OpenAM retrieves static profile data such as the waterShedContent attribute and makes available via the ../tokeninfo end point accessible using the OAuth2 access_token
  3. Client interprets the data received from the ../tokeninfo endpoint to perform local authorization (if waterShedContent == true || false for example) providing a link into OpenIDM that can trigger an access request
  4. The BPMN workflow in IDM searches for an approver and assigns them a basic boolean gateway workflow - either allow or deny.  An allow triggers an openidm.patch that updates the necessary attribute that is then stored in OpenDJ
  5. The updated attribute is then made available via the ../tokeninfo endpoint again - perhaps via a refresh_token flow and the updated attribute is available in the client
Triggering a remote workflow (step 3) is pretty trivial - simply call /openidm/workflow/processinstance?_action=create with the necessary workflow you want to trigger.  To work out who to assign the workflow to, I leveraged the new relationship management feature of IDM and used the execution.setVariable('approver', approver) function within the workflow.  The approver was simply an attribute within my initial user object that I set when I created my managed/object.

The code for the PoC-level TV-player with the necessary OAuth2 and workflow request code is available here.

3 February 2016

Set Top Box Emulator and OAuth2 Device Flow

This is really an extension to a blog I did in October 2015 - Device Authorization using OAuth2 and OpenAM, with an application written in Node.js using the newly released OpenAM 13.0.

The basic flow hasn't really changed. Ultimately there is a client - the TV emulator - that communicates to OpenAM and the end user, with the end user also performing out-of-band operations via a device which has better UI capabilities - aka a tablet or laptop.


The app boots and initiates a request to OpenAM to get a unique user and device code, prompting the user to hit a specific URL on their tablet.


The user authenticates with the OpenAM resource server as necessary, enters the code and performs a consent dance to approve the request from the TV to be paired and retrieve data from the user's profile - in this case, overloading the postaladdress attribute in DJ to store favourite channel data.



In the meantime, the TV client is performing a polling operation - checking with the OpenAM authorization service, to see if the end user has entered the correct user_code and approved the request.  Once completed the TV retrieves a typical OAuth2 bearer payload, including the refresh_token and access_token values that can be used to retrieve the necessary attributes.



Future requests from the TV now no longer need to request password or authorization data.  By leveraging a long live refresh_token access can be managed centrally.


For more information on OAuth2 Device Flow see here.