Creating Personal Access Tokens in ForgeRock AM

Personal Access Tokens (PAT’s) are used to provide scoped self-managed access credentials that can be used to provide access to trusted systems and services that want to act on a users behalf.

Similar to OAuth tokens, they often don’t have an expiration and are used conceptually instead of passwords.  A PAT could be used in combination with a username when performing basic authentication.

For example see the https://github.com/settings/tokens page within Github which allows scope-related tokens to be created for services to access your Github profile.

PAT Creation

The PAT can be an opaque string – perhaps a SHA256 hash.  Using a hash seems the most sensible approach to avoid collisions and create a fixed-length portable string.  A hash without a key of course wont provide any creator assurance/verification function, but since the hash will be stored against the user profile and not treated like a session/token this shouldn’t be an issue.

An example PAT value could be:

Eg:

f83ee64ef9d15a68e5c7a910395ea1611e2fa138b1b9dd7e090941dfed773b2c:{“resource1” : [ “read”, “write”, “execute” ] }

a011286605ff6a5de51f4d46eb511a9e8715498fca87965576c73b8fd27246fe:{"resource2" : [ "read", "write"]}

The key was simply created by running the resource and the associated permissions through sha256sum on Linux.  How you create the hash is beyond the scope of this blog, but this could be easily handled by say ForgeRock IDM and a custom endpoint in a few lines of JavaScript.

PAT Storage

The important aspect is where to store the PAT once it has been created.  Ideally this really needs to be stored against the users profile record in DJ.  I’d recommend creating a new schema attribute dedicated for PAT’s that is multivalued.  The user can then update their PAT’s over REST the same as any other profile attribute.

For this demo I used the existing attribute called “iplanet-am-user-alias-list” for speed as this was multi-valued.  I added in a self-created PAT for my fake resource:

Using a multi-valued attribute allows me to create any number of PAT’s.  As they don’t have an expiration they might last for some time in the user store.

PAT Usage

Once stored, they could be used in a variety of ways to provide “access” within applications. The most simple way, is to leverage the AM authorization engine as a decision point to verify that a PAT exists and what permissions it maps to.

Once the PAT is stored and created, the end user can present it to another user/service that they want to use the PAT.  That service or user presents the username:PAT combination to the service they wish to gain access to.  That service calls the AM authorization API’s to see if the user:PAT combination is valid.

The protected service would call {{OpenAM}}/openam/json/policies?_action=evaluate with a payload similar to:

Here I am calling the ../policies endpoint with a dedicated account called “policyeval” which has ability to read the REST endpoint and also read realm users which we will need later on.  Edit the necessary privileges tab within the Admin console.

If the PAT exists within the user profile of “smoff”, AM returns an access=true message, along with the resource and associated permissions that can be used within the calling application:

So what needs setting up in the background to allow AM to make these decisions? Well all pretty simple really.

Create Authorization Resource Type for PAT’s

Firstly create a resource type that matches the pat://*.* format (or any format you prefer):

Next we need to add a policy set that will contain our access policies:

The PATValidator only contains one policy called AllPATs, which is just a wildcard match for pat://*:*.  This will allow any combination of user:pat to be submitted for validation:

Make sure to set the subjects condition to “NOT Never Match” as we are not analysing user session data here.  The logic for analysis is being handled by a simple script.

PAT Authorization Script

The script is available here.

At a high level is does the following:

  1. Captures the submitted username and PAT that is part of the authorization request
  2. As the user will not have a local session, we need to make a native REST call to look up the user
  3. We do this by first generating a session for our policyeval user
  4. We use that session to call the ../json/users endpoint to perform a search for the users PATs
  5. We do a compare between the submitted PAT and any PAT’s found against the user profile
  6. If a match is found, we pull out the assigned permissions and send back as a response attribute array to the calling application

This blog post was first published @ http://www.theidentitycookbook.com/, included here with permission from the author.

Faster docs

One of the things you have asked for is to see large documents load faster on the ForgeRock BackStage docs site. We recently switched from publishing HTML documentation through the BackStage single-page app to publishing separate, static HTML with JavaScript to provide BackStage features.

This allows browsers to use progressive rendering, and start laying out the page before everything has been loaded and styled. The result is that large documents feel faster in your browser.

If you have bookmarks to published HTML, notice that we have dropped the per-chapter view of published docs. Each document is now a single HTML page. So instead of a link to /docs/product/version/book/chapter#section, target /docs/product/version/book/#section.

Also notice that we have consolidated documentation sets to make information easier to find, with only one set per major or minor release. Generally this means that you only have to read one set of release notes, no matter what maintenance version you have right now.

The latest docs are the ones for version 5 of the platform:

We still publish all the same docs as before, including docs for software that is beyond the end of its service life. Please check out the updated site. Open issues there for any problems you notice.

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

Faster docs

ForgeRock Logo One of the things you have asked for is to see large documents load faster on the ForgeRock BackStage docs site. We recently switched from publishing HTML documentation through the BackStage single-page app to publishing separate, static HTML with JavaScript to provide BackStage features.

This allows browsers to use progressive rendering, and start laying out the page before everything has been loaded and styled. The result is that large documents feel faster in your browser.

If you have bookmarks to published HTML, notice that we have dropped the per-chapter view of published docs. Each document is now a single HTML page. So instead of a link to /docs/product/version/book/chapter#section, target /docs/product/version/book/#section. Also notice that we have consolidated documentation sets to make information easier to find, with only one set per major or minor release. Generally this means that you only have to read one set of release notes, no matter what maintenance version you have right now.

The latest docs are the ones for version 5 of the platform:

We still publish all the same docs as before, including docs for software that is beyond the end of its service life. Please check out the updated site. Open issues there for any problems you notice.


Step up authentication OpenID Connect

A common use case in access management is step up authentication. ForgeRock AM is very good for that. The OIDC standard talks about step up authentication and level of authentication requested by the client.

To do so, one could use acr_values which is a voluntary claim, but the openid specification says : «  the Authorization Server is not required to provide this Claim in its response. »
In order to achieve that, the essential claim acr is used, it is describe in chapter 5.5.1.1. Requesting the “acr” Claim of the OpenID Core (see: http://openid.net/specs/openid-connect-core-1_0.html#acrSemantics)

In order to demonstrate the functionality, use the following example based on AM 5.1:

In the AM console, browse to Realms >Realm Name>Services, and then click OAuth2 Provider.
Configure the mapping between acr values (in the example 1=ldapService and 2=HOTP chain) in the authorization request and AM authentication chains.

 

OAuth 2 Provider service configuration

HOTP chain contains HOTP module only

Step 1:
The url decoded value of the claims parameter:

{
    “id_token”: 
        {
            “acr”:
                {    
                    “essential”: true, 
                    “values”:[“1”]
                }
        }
}

Click on the URL
http://openam.example.com:8080/openam/oauth2/authorize?response_type=code&scope=openid%20profile&client_id=myClientID&redirect_uri=http%3A%2F%2Fopenam.example.com%3A8080%2Fopenid%2Fcb-basic.html&claims=%7B%22id_token%22%3A%20%7B%22acr%22%3A%7B%22essential%22%3A%20true%2C%20%22values%22%3A%5B%221%22%5D%7D%7D%7D

The user enters the login / password

The id tokens returns acr=1

Step 2:

The url decoded value of the claims parameter:
{
    “id_token”: 
        {
            “acr”:
                {    
                    “essential”: true, 
                    “values”:[“2”]
                }
        }
}

Click on the URL:
http://openam.example.com:8080/openam/oauth2/authorize?response_type=code&scope=openid%20profile&client_id=myClientID&redirect_uri=http%3A%2F%2Fopenam.example.com%3A8080%2Fopenid%2Fcb-basic.html&claims=%7B%22id_token%22%3A%20%7B%22acr%22%3A%7B%22essential%22%3A%20true%2C%20%22values%22%3A%5B%222%22%5D%7D%7D%7D

The user receives OTP and enters the OTP in the login screen.

The id tokens returns acr=2

Note that this is a real step up authentication, the session is alive from step 1 to step 2, the OTP is sent to the user connected at the first step.

 

Unlock user account using OpenAM Forgot Password flow

OpenAM provides “Account Lockout” functionality which can be used to configure various lockout parameters such as failure count, lockout interval etc.

Note that OpenDJ also provides Account Lockout functionality, this article is based on OpenAM Account Lockout policies. Refer this KB article for more differences between OpenAM and OpenDJ lockout polices.

Using OpenAM “Account Lockout” policies, users may get locked out with invalid login attempts. OpenAM offers both Memory and Physical lockouts. Using memory lockout, users get unlocked automatically after specified duration.

Many deployments use “Physical lockout” due to security requirements. When this lockout mode is used then there should be some Self-service flow so that user can unlock themselves. Why not use OpenAM forgot password self-service flow ?

OpenAM forgot password allows user to reset password after successfully completing various stages (such as KBA, email confirmation, reCaptcha etc). Unfortunately, the problem is that the account is not unlocked when this flow is used. There is already an open RFE for this issue.

Solution

Versions used for this implementation: OpenAM 13.5, OpenDJ 3.5
One of the solution can include extending out of the box OpenAM’s forgot password self-service flow by adding custom stage to unlock user’s account:
  • Implement ForgottenPasswordConfigProviderExt to include account unlock stage.
  • Implement unlock custom stage
  • Extend selfServiceExt.xml to include custom provider.

Deploy

  • Build the custom stage by using maven.
  • Delete all instances of User Self-Service from all realms.
  • Remove existing selfService
./ssoadm delete-svc --adminid amadmin --password-file /tmp/pwd.txt -s selfService
  • Restart OpenAM
  • Register custom selfService
  • Restart OpenAM
./ssoadm create-svc --adminid amadmin --password-file /tmp/pwd.txt --xmlfile ~/softwares/selfServiceExt.xml
  • Add User Self-Service to specified realm and enable forgot password flow.

Testing

  1. Lock user by authenticating using wrong password till user is locked out.
  2. Follow forgot password flow to reset password and unlock account.
  3. Try authenticating again with new password. This should succeed.

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

ForgeRock Self-Service Custom Stage

Introduction

A while ago I blogged an article describing how to add custom stages to the ForgeRock IDM self-service config.  At the time I used the sample custom stage available from the ForgeRock Commons Self-Service code base.  I left it as a task for the reader to build their own stage!  However, I recently had cause to build a custom stage for a proof of concept I was working on.

It’s for IDM v5 and I’ve detailed the steps here.

Business Logic

The requirement for the stage was to validate that a registering user had ownership of the provided phone number.  The phone number could be either a mobile or a landline.  The approach taken was to use Twilio (a 3rd party) to send out either an SMS to a mobile, or text-to-speech to a landline.  The content of the message is a code based on HOTP.

Get the code for the module

https://stash.forgerock.org/users/andrew.potter/repos/twilio-stage/browse

Building the module

Follow the instructions in README.md

After deploying the .jar file you must restart IDM for the bundle to be correctly recognised.

The module is targeted for IDMv5.  It uses the maven repositories to get the binary dependencies.
See this article in order to access the ForgeRock ‘private-releases’ maven repo:
https://backstage.forgerock.com/knowledge/kb/article/a74096897

It also uses appropriate pom.xml directives to ensure the final .jar file is packaged as an OSGi bundle so that it can be dropped into IDM

Technical details

The code consists of a few files.  The first two in this list a the key files for any stage.  They implement the necessary interfaces for a stage.  The remaining files are the specific business logic for this stage.

  • TwilioStageConfig.java.  This class manages reading the configuration data from the configuration file.  It simply represents each configuration item for the stage as properties of the class.
  • TwilioStage.java.  This is main orchestration file for the stage.  It copes with both registration and password reset scenarios.  It manages the ‘state’ of the flow within this stage and generates the appropriate callbacks to user, but relies on the other classes to do the real code management work.  If you want to learn about the way a ‘stage’ works then this is file to consider in detail.
  • HOTPAlgorithm.java.  This is taken from the OATH Initiative work and is unchanged by me.  It is a java class to generate a code based on the HOTP algorithm.
  • TwilioService.java. This class manages the process of sending the code.  It generates the code then decides whether to send it using SMS or TTS.  (In the UK, all mobile phone numbers start 07… so it’s very simple logic for my purpose!)  This class also provides a method to validate the code entered by the user.
  • TwilioUtil.java.  The class provides the utility functions that interact directly with the Twilio APIs for sending either an SMS or TTS

 

Configuration

There are also two sample config files for registration and password reset.  You should include the JSON section relating to this class in your self-service configuration files for IDM.
For example:

        {
“class” : “org.forgerock.selfservice.twilio.TwilioStageConfig”,
“codeValidityDuration” : “6000”,
“codeLength” : “5”,
“controlUrl” : “http://twimlets.com/message?Message%5B0%5D=Hello%20Please%20enter%20the%20following%20one%20time%20code”,
“fromPhone” : “+441412803033”,
“accountSid” : “<Enter accountSid>”,
“tokenId” : “<Enter tokenId>”,
“telephoneField” : “telephoneNumber”,
“skipSend” : false
},

Most configuration items should be self explanatory.  However, the ‘skipSend’ option is worthy of special note.  This, when true, will cause the stage to avoid calling the Twilio APIs and instead return the code as part of the callback data.  This means that if you’re using the OOTB UI then the ‘placeholder’ HTML attribute of the input box will tell you the code to enter.  This is really useful for testing this stage if you don’t have access to a Twilio account as this also ignores the Twilio account specific configuration items.

Of course, now you need to deploy it as per my previous article!

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

ForgeRock welcomes Nabil Maynard

Late welcome to Nabil Maynard who joined the ForgeRock documentation team this past Monday.

Nabil has started working on the identity management documentation. He’s digging into his new full-time job as a writer.

Nabil brings solid technical experience and understanding of how server software works, having been a QA professional for years at places like Dropbox. So much of writing good documentation for ForgeRock software depends on throughly understanding what the software does, how it can be broken, and what you should do to make it work correctly. Nabil’s contributions will surely help you get deeper into ForgeRock’s identity management software.


ForgeRock welcomes Gina Cariaga

Late welcome to Gina Cariaga who joined the ForgeRock documentation team this spring.

Gina has strong experience writing about access management and directory services. Her formal background in training, mixed with her hands-on success with the kind of documentation we do at ForgeRock make a great combination.

Gina’s initial work at ForgeRock has included putting together a guide to getting started with the ForgeRock platform for IoT architects and developers. Gina is continuing to write on using ForgeRock’s identity and access management capabilities in the IoT space, and much more.


Save greenbacks on Google Container Engine using autoscaling and preemptible VMs

There is an awesome new feature on Google Container Engine (GKE) that lets you combine autoscaling, node pools and preemptible VMs to save big $!

The basic idea is to create a small cluster with an inexpensive VM type that will run 7×24. This primary node can be used for critical services that should not be rescheduled to another pod. A good example would be a Jenkins master server. Here is an example of how to create the cluster:

gcloud alpha container clusters create $CLUSTER 
  --network "default" --num-nodes 1 
  --machine-type  ${small} --zone $ZONE 
  --disk-size 50

Now here is the money saver trick:  A second node pool is added to the cluster. This node pool is configured to auto-scale from one node up to a maximum. This additional node pool uses preemptible VMs. These are VMs that can be taken away at any time if Google needs the capacity, but in exchange you get dirt cheap images. For example, running a 4 core VM with 15GB of RAM for a month comes in under $30.

This second pool is perfect for containers that can survive a restart or migration to a new node. Jenkins slaves would be a good candidate.

Here is an example of adding the node pool to the cluster you created above:

gcloud alpha container node-pools create $NODEPOOL --cluster $CLUSTER --zone $ZONE 
    --machine-type ${medium} --preemptible --disk-size 50 
    --enable-autoscaling --min-nodes=1 --max-nodes=4

That node pool will scale down to a single VM if the cluster is not busy, and scale up to a maximum of 4 nodes.

If your VM gets preempted (and it will at least once every 24 hours),  the pods running on that node will be rescheduled onto a new node created by the auto-scaler.

Container engine assigns a label to nodes which you can use for scheduling. For example, to ensure you Jenkins Master does not get put on a preemptible node, you can add the following annotation to your Pod Spec:

apiVersion: v1kind: Podspec:  nodeSelector:    !cloud.google.com/gke-preemptible
apiVersion: v1kind: Podspec:  nodeSelector:    !cloud.google.com/gke-preemptible
nodeSelector:    !cloud.google.com/gke-preemptible

See https://cloud.google.com/container-engine/docs/preemptible-vm for the details.

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

Identi-Tea Podcast, Episode 5: The Answer is Blowing in the (IoT) Wind

In episode 5, Daniel and Chris are live at IoT World / Connected & Autonomous Vehicles 2017 in Santa Clara, CA. Topics include how identity can play a key role in customizing the user experience for connected cars, how to creatively use access policies and contextual data to solve IoT challenges, and how securing devices on the edge requires a different way of thinking. Oh, and it was very windy.

Episode Links:

ForgeRock Identity Live 2017

Video: Objects in Mirror May Be Closer Than They Appear (Donut Demo)

ForgeRock Edge Security Early Access Program