Using OpenAM as a REST based PDP

OpenAM has a powerful policy decision point functionality (PDP) that can be leveraged entirely over the REST endpoints provided out of the box.  These endpoints allow for nice decoupling between the PDP and authentication infrastructure and your app.  A few things to setup first...

Policies - policies map to the resource URL's that you want to protect, along with additional data such as the subjects (users) the policy will affect, as well as conditions such as IP address, time, authentication level requirements and so on.

Authentication Modules - an obvious component, but the modules can also be configured with an authentication level (an arbitrary numeric value) that provides an assurance level once a user has used a particular chain / module.  The auth level can then be leveraged via the policy.

Authentication

Authenticating the user over REST in v11 has changed slightly.  There is now the use of JSON based callbacks that allow for more flexible authentication scenarios.  For example, say the user is not authenticated but wants a session with an assurance level to be able to access app.example.com/examples.  The following could be called:

http://openam.example.com:8080/openam/json/authenticate?authIndexType=resource&authIndexValue=http%3A%2F%2Fapp.example.com%3A8081%2Fexamples

OpenAM will then return a JSON and associated JWT, either with a choice callback to choose a module that has the appropriate auth level, or the attributes and value placeholders for the module that matches. Sending the JSON back to OpenAM with the necessary username, password or other attributes filled in will result in a token and success URL for redirection:

{
      tokenId: "AQIC5wM2LY.......QtMzg2NzM4NzAwMjEwMDc2NzIyMQ..*"
      successUrl: "/openam/console"
}

Now comes the authorization part.  There are few avenues to take here.  Either taking the attribute and querying OpenAM for other attributes associated with it to help make an authorization decision natively, or performing policy queries.

Attribute Query

Taking the tokenID as the header cookie, a call is made to retrieve either the entire user object, or specific fields, by appending attributes to the URL:

http://openam.example.com:8080/openam/json/users/smof?_fields=uid,inetuserstatus,employeenumber

Returns:

{"uid":["smof"],"inetuserstatus":["Active"],"employeenumber":["123456"]}

Policy Decision

There are couple of endpoints for performing a URL access check.  The main one I use here is the ../entitlement/entitlement (note the two entitlements...) endpoint that is very flexible and also returns advice objects to assist with handling any deny messages.

By wanting to do a check against app.example.com:8081/examples, encode the URL and taking the subjects tokenID as the cookie, call:

http://openam.example.com:8080/openam/ws/1/entitlement/entitlement?action=GET&resource=http%3A%2F%2Fapp.example.com%3A8081%2Fexamples

A deny message (for example the user being authenticated to a module that didn't meet the 110 authlevel minimum...) would deliver:

{

  "statusMessage": "OK",

  "body": {

    "resourceName": "http://app.example.com:8081/examples",

    "advices": {

      "AuthLevelConditionAdvice": [

        "/:110"

      ]

    },

    "attributes": {},

    "actionsValues": {}

  },

  "statusCode": 200

}

A positive response would deliver:

{

  "statusMessage": "OK",

  "body": {

    "resourceName": "http://app.example.com:8081/examples",

    "advices": {},

    "attributes": {},

    "actionsValues": {

      "GET": true,

      "POST": true

    }

  },

  "statusCode": 200

}

Detailed endpoint calls can be read here - http://docs.forgerock.org/en/openam/11.0.0/dev-guide/index.html#chap-rest

Role Mining & Peer Analytics in OpenIDM

I created a few custom endpoint extensions for use with OpenIDM, that allows for the analysis of users and their entitlements.  I won't go into the virtues of roles and role based access control, but these endpoints are a simple way to quickly identify similarities between groups of users and then quickly find any differences or exceptions.  These exceptions would then be analysed either by a certification system or perhaps manually by the security admin teams.

Peer Analysis

Peer Analysis JSON

The first endpoint simply groups users (generally managed users) together based on a functional similarity.  This is generally known as 'top down' mining in full blown role mining projects.  The endpoint returns a JSON object with role names and an array of users that are part of that functional grouping.


Peer Entitlements

Peer Entitlements JSON

The role object on it's own it's much use.  What we're really interested in, is what entitlements should be associated with that role.  This makes the onboarding of new users really simple and less error prone.  If we know what entitlements the role should have, we can simply associate a new user, based on the previously identified functional grouping, and the user can then be provisioned those entitlements.  But how do we know which entitlements to associate with the role?  The peerEntitlements.js endpoint is a really robust way of finding out which entitlements are common for a given group of users.  Using the JSON output from the peerAnalysis.js endpoint, we can simply pull out the entitlements for any system known to OpenIDM. The peerEntitlements.js endpoint then identifies every entitlements that is common across every user in that grouping and adds it to the role.

For example if Billy (grp1, grp2), Ann (grp1, grp5) and John (grp1, grp6) were all in the same role, the entitlements endpoint would see that only "grp1" was common across all users and push that into the entitlements array.  The other entitlements we'll come to in a second....


Peer Exceptions

Peer Exceptions JSON

Any entitlements that do no find themselves added to a role due to their similarity (or lack of), need to be handled.  Generally these entitlements are known as exceptions and are managed through long and complex access certification and attestation projects.  There are several fully blown compliance products on the market place, that can take several months to configure and deploy.  The idea behind the peerExceptions.js endpoint, is to quickly identify only the high risk exception entitlements and get those entitlements cleaned up in a timely fashion.  By focusing just on the high risk exceptions, this can cut down the access review process by 80%.  The exceptions in this example, are simply entitlements associated with a user that fall outside of the role model.  Taking user Billy (above), he has "grp1" and "grp2" associated with him.  "grp1" landed in the newly found role, leaving "grp2" as an exception.  He has that entitlement, but other users who perform a similar business function do not.  Maybe he is a manager, or perhaps is new to the job and has experienced privilege creep.  Either way this entitlements don't match those of his peers and that needs investigating.  The peerExceptions.js endpoint performs a diff between the effective entitlements directly associated with the user, and the effective entitlements from the roles the user has.

All code from the above examples is available from Github here.  Note this is an example endpoint and is no way supported by ForgeRock.  It is released simply as a community contribution.  Use as-is!