ForgeRock Common Audit

ForgeRock LogoCommon Audit is another new feature of the ForgeRock platform.

Common Audit is part of the platform-wide infrastructure: a framework to handle audit events using common audit event handlers that are plugged in to the individual products. The handlers record events, logging them for example into files, relational databases, or syslog. Because handlers are pluggable, new handlers can be added to interoperate with your systems that store and analyze audit data.

Each audit event is identified by a unique transaction ID. The IDs can be communicated across the products and recorded for each local event. The transaction ID is the means to track requests as they traverse the platform.

In the current platform, configuring handlers depends on the product. So there are several places in the docs to read about how to configure Common Audit:

In addition, if you want to get the source code for Common Audit, or are interested in trying out new handlers and developments, you can find it on the ForgeRock Stash server. Right now it is in the forgerock-audit git repository. (To access most code on the ForgeRock Stash server, sign in with your ForgeRock credentials. You can sign up if you have not done so.)

User-Managed Access from ForgeRock

ForgeRock LogoLast week ForgeRock released a platform update, including many new features. One of those features is support for User-Managed Access (UMA). UMA is a profile of OAuth 2.0 that allows resource owners to share their resources with others in a standard way. UMA puts resource owners in charge of defining policies for accessing their resources. From that perspective, UMA could be seen as highly scalable delegated policy administration.

At a very high level, this short video on privacy introduces the ideas it.

At a level closer to the implementation, UMA describes how authorization servers, resource servers, and UMA clients interact to enable resource sharing. In the ForgeRock platform, OpenAM plays the role of authorization server. OpenIG plays the role of resource server. (These are currently the working parts of OpenUMA.) In the present implementation, the client side is for you to implement, although the OpenIG docs include an example client, and there are ForgeRock demos that cover the client side as well. You can download OpenAM 13 and OpenIG 4 from the ForgeRock BackStage downloads page.

To get started with OpenAM authorization server implementation, install OpenAM and then have a look at the Administration Guide chapter on Managing UMA Authorization.

To try OpenIG’s UMA resource server capabilities, install OpenIG and then have a look at the OpenIG Gateway Guide chapter on OpenIG As an UMA Resource Server.

The latter chapter is a tutorial that describes how to get everything working together including a minimalist, browser-based UMA client.


What’s new in the ForgeRock platform release

ForgeRock LogoPerhaps you have read yesterday’s news about ForgeRock launching the updated identity platform.

Those of us who spent the last year working on this update are proud of all the new capabilities, from the integration achieved with common components to the depth and breadth of new features across all the products in the platform.

Looking for detailed lists of what’s new? Here are some quick links to each of the products’ release notes:

I’ll drill down on some of those in future posts.

ForgeRock welcomes Joanne Henry

Welcome to Joanne Henry who joined the ForgeRock documentation team today. Good to work with you again, Joanne.

Joanne has experience as a technical writer and team leader for a variety of projects from chips to consumer electronics to medical software to LDAP. In all of these situations, Joanne has managed to deliver useful documentation for users and to improve the way the team works.

Joanne’s now bringing her diligence, clear thinking, and focus to the OpenIG project. Good news for those of you figuring out how to protect your applications and APIs!

ForgeRock doc tools 3.1.0 released

ForgeRock doc tools 3.1.0 are out.

This is a minor release, compatible with 3.0.0. See the release notes for details.

ForgeRock doc tools 3.1.0 includes the following components:

  • forgerock-doc-maven-plugin
  • forgerock-doc-common-content
  • forgerock-doc-default-branding
  • forgerock-doc-maven-archetype

This release adds a few improvements and resolves a number of bugs.

One of the improvements is initial support for Asciidoc. The doc build plugin generates DocBook from Asciidoc source, and then processes the resulting output in the same way as other documents. At this time the doc build plugin does not allow you to mix Asciidoc and DocBook in the same document. For details, see the README.

Thanks to Peter Major for providing a new release of docbook-linktester, improving the link check usability with a more human-readable report, better supporting <olink> elements, and troubleshooting an issue related to throttling that affected link checks for some documents.

Thanks again to Chris Lee for a number of improvements to Bootstrap HTML output, and for fixing inter-document links in PDF (depends on the renderer, seen to work with Adobe Acrobat).

Thanks also to Lana Frost, Chris Clifton, David Goldsmith, Gene Hirayama, and Mike Jang for testing and bug reports.

ForgeRock doc tools 3.0.0 released

ForgeRock doc tools 3.0.0 is finally done!

This is a major release, and the build plugin configuration has changed. See the release notes for details.

ForgeRock doc tools 3.0.0 includes the following components:

  • forgerock-doc-maven-plugin
  • forgerock-doc-common-content
  • forgerock-doc-default-branding
  • forgerock-doc-maven-archetype

This release resolves 92 issues, with dozens of new features, fixes, and improvements.

Hats off to Chris Lee for his work to provide much better HTML, styled with Bootstrap, and to Gene Hirayama for his many improvements to PDFs.

Thanks also to Lana Frost, David Goldsmith, and Mike Jang for testing and bug reports.

Special thanks to Peter Major for docbook-linktester 1.3.0.

See the README for more about how to use the doc tools, and for details on the new features.

OpenAM 12.0.0 released

OpenAM logo

This past Thursday ForgeRock released OpenAM 12.0.0, a major update with so many improvements and new features that this post only hits a few highlights. You can download OpenAM 12.0.0 from

OpenAM provides an access management solution handling authentication and authorization for all sorts of applications, no doubt including yours. OpenAM does SSO with delegated authentication to over 20 authn services out of the box, authorization both though centralized policies and also using delegated approaches (OAuth 2.0, etc.), security token brokering and more. OpenAM supports a rich set of standards like SAML, OAuth 2.0, OpenID Connect, GSMA Mobile Connect, not to mention standards for authentication. Of course OpenAM is open source and fully extensible as well. The OpenAM service runs as a web application in a variety of containers such as JBoss, Tomcat, WebLogic and WebSphere. OpenAM policy enforcement agents give you out-of-the box protection for many web sites and web applications, though you can also do your own enforcement using OpenAM’s REST APIs.

As a major release, OpenAM 12.0.0 is leap forward in many areas:

  • Default end user pages now use responsive, client-side layout with lots of self-service features (self-registration, password reset, app management, etc.) ready to go.
  • Wizards make it a snap to delegate authentication to Facebook, Google, MSN and other online providers.
  • Policy administration works through a new wizard-based editor, and both policy administration and policy evaluation have well-defined REST APIs for all operations.
  • Script language support for authentication modules let your scripted modules call out to other applications using JavaScript or Groovy, making it easier to integrate external risk management in addition to OpenAM’s built-in capabilities.
  • Security token services now come with a REST API.
  • OpenAM supports OAuth 2.0 and OpenID Connect 1.0 more fully than before, with additional support for GSMA Mobile Connect.
  • And much more…

To see the whole list of features, start by reading the Release Notes for details. Full documentation is available on

When you start using OpenAM 12.0.0 and find that you have questions, in addition to the mailing list ForgeRock also now provides an OpenAM Forum. We look forward to hearing from you.

OpenIG 3.1.0 released

openig-logo This past Friday ForgeRock released OpenIG 3.1.0, an official minor release for which you can get support from ForgeRock. You can download OpenIG 3.1.0 from

OpenIG is a reverse proxy with session management and credential replay functionality. It runs as a web application in Apache Tomcat or Jetty. By using OpenIG you can provide identity and access management solutions for just about any web application, and you can do it without touching the web application itself. OpenIG supports standards like OAuth 2.0, OpenID Connect 1.0, and SAML 2.0, and of course integrates well with ForgeRock’s software stack. Furthermore, OpenIG is extensible through built-in Groovy support and Java plugin points.

As a minor release, OpenIG 3.1.0 is backward compatible with 3.0.0 so you can try it with your existing configuration.

You can then start to take advantage of new features:

  • A JWT session implementation lets you store all state on the client side as long as it fits in a browser cookie whose value is the session data in an encrypted JWT. OpenIG holds the keys for encryption and decryption to prevent anyone else from accessing the session data. By delegating storage of all state data to the user-agent, you can scale out your deployment without having to configure OpenIG’s container to share session data.
  • Inline configuration objects and other improvements make OpenIG configuration files easier to read.
  • Configuration object decorators make it straightforward to capture requests, responses, and exchange data, to time operations, and to audit OpenIG operations.
  • A publish-and-subscribe audit framework and sample monitoring handler returns basic statistics about OpenIG operations.
  • Other improvements make console logs easier to read, script parameters easier to set, OAuth 2.0/OpenID Connect filters more performant, and client information easier to discover.

Start with the Release Notes for details. Full documentation is available on Also check out the articles written by Ludo and Guillaume.

When you have questions, in addition to the mailing list ForgeRock also now provides an OpenIG Forum. Stop by to let us know what you think of OpenIG 3.1.0.

OpenAM: REST APIs for policy evaluation

OpenAM logo

One of the significant new features added to OpenAM and coming in the pending release is the new REST API for policy evaluation. To try the API, get a nightly build of OpenAM, or build the code yourself from the trunk.

Some background: Your application should not be in the business of making policy decisions. Not because you are not smart enough to do it, but instead because you do not want to maintain potentially intricate and changing policies across all your applications. Instead your application should ask a service like OpenAM to make policy decisions, and then focus only on enforcing those policy decisions. (In fact, if your application runs in a web server or application server, you could do even better by getting a policy agent to do the work on your application’s behalf.) You can therefore administer policies within the service like OpenAM, and have them uniformly enforced across many applications. Policy evaluation is what your application asks a policy decision point like OpenAM to carry out.

OpenAM has had REST APIs for policy evaluation for a long time. The older APIs required, however, that you re-encode the SSO token in a particular way. They also did not necessarily return JSON, making them a bit more difficult to work with.

The newer API returns JSON, and does not require tokens to be re-encoded. The newer API makes use of two endpoints:

  1. /json/policies?_action=evaluate (for myRealm/subRealm, /json/myRealm/subRealm/policies?_action=evaluate)
    This endpoint takes an HTTP POST, where the POST data is a JSON object defining the “resources”, “application”, “subject”, and “environment” for which OpenAM makes the policy decision.

    • The “resources” in this case is an array of strings specifying the resource(s), such as "", that the user is trying to access. This is the only required field.
    • The “application” is the policy application name. You see the application names in the new policy editor. Policies belong to applications, so the application name narrows down the set of policies that can apply.
    • The “subject” can take an SSO token ID string to represent the subject, but it can also take a JWT or a map of JWT claims, depending on how the policies are configured in OpenAM.
    • The optional “environment” can provide additional information about the environment of the user who is trying to access the resource.
  2. /json/policies?_action=evaluateTree (for myRealm/subRealm, /json/myRealm/subRealm/policies?_action=evaluateTree)
    This endpoint takes an HTTP POST with POST data similar to the first. Instead of “resources”, it takes a “resource” string. OpenAM returns policy decisions about all the resources under the specified “resource”.

Suppose you have a policy in OpenAM that belongs to the default application and that allows authenticated users GET access to "", returning the user’s common name as a response attribute.

In addition, you have a web page that allows you to get a policy decision when logged in as a user authorized to request policy decisions, such as OpenAM administrator. (This example is overly simplistic and mixes up content with policy enforcement. In real life, your client-side JavaScript would end up requesting a resource; your server-side policy enforcement code would check with OpenAM before responding.)

<!DOCTYPE html>
<script src=""></script>

<h3>Fake Profile Page</h3>

<div id="common-name"></div>
<div id="policy-decision"></div>
<div id="error"></div>

<script type="text/javascript">

var endpoint  =
var resources =
  '{ "resources": [ "" ] }';

$(document).ready(function () {

  // Request decision from OpenAM.

    url: endpoint,
    type: "POST",
    contentType: "application/json",
    dataType: "json",
    data: resources

  }).done(function (data) {

    // Display the name.
      "<h4>Common Name</h4>"
      + "<pre>"
      + data[0]
      + "</pre>"

    // Display the full response.
      "<h4>Policy Decision</h4>"
      + "<pre>"
      + JSON.stringify(data, undefined, 2)
      + "</pre>"

  }).fail(function (data) {

    // Display the error response.
      + "<pre>"
      + JSON.stringify(data, undefined, 2)
      + "</pre>"



If you first login to OpenAM as amadmin in order to get a session cookie and then visit the web page, you can get a policy decision for the specified resource.


For details on the API, see the draft documentation on Requesting Policy Decisions.

OpenIG: A new audit framework

openig-logo This past week Guillaume added an audit framework to OpenIG. You can try it out by installing a new nightly build of OpenIG.

The audit framework follows a publish-subscribe pattern. You add “audit” decorations to OpenIG filter, handlers, and routes. The decorated objects trigger publication of audit events.

Each audit event holds a pointer to the exchange, the name of the object that triggered the event, a timestamp, and tags for the event. OpenIG provides built-in tags: a request when the object is first called; a response after the object is called; a completed tag on success; an exception tag on error. Audit agents subscribe to the audit events, and can select the audit events they want based on the tags. When you set “audit” decorations, you can define your own tags, too, such as “raise alarm” or “Default route”.

If your default route for example looks like this today:

  "handler": "ClientHandler"

Then you can update the route for audit like this:

  "handler": "ClientHandler",
  "audit": "default route"

OpenIG currently provides one audit agent out of the box: MonitorEndpointHandler. A MonitorEndpointHandler counts how many messages through the object are “active”, “completed”, or “failed”, sorts them by the tags used, and returns the result as JSON. You can set a monitor route up like this:

  "handler": {
    "type": "MonitorEndpointHandler"
  "condition": "${exchange.request.method == 'GET'
      and exchange.request.uri.path == '/monitor'}",
  "audit": "monitor"

Suppose that your top level config.json file looks like this:

  "handler": {
    "type": "Router",
    "audit": "main"
  "heap": [
            "name": "LogSink",
            "type": "ConsoleLogSink",
            "config": {
                "level": "DEBUG"
            "name": "ClientHandler",
            "type": "ClientHandler"
          "name": "capture",
          "type": "CaptureDecorator",
          "config": {
            "_captureEntity": true,
            "_captureExchange": true
    "baseURI": ""

Furthermore, suppose you have the default route shown above, plus another route that looks like this:

  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "reason": "OK",
      "entity": "Hello from a static route"
      "${matches(exchange.request.uri.path, '^/static')}",
  "audit": "static route"

After you access your routes through OpenIG a few times, you can see the monitoring results by accessing the /monitor endpoint, which returns the statistics in JSON:

    "static route": {
        "active": 0,
        "completed": 22,
        "failed": 0
    "main": {
        "active": 1,
        "completed": 36,
        "failed": 0
    "monitor": {
        "active": 1,
        "completed": 0,
        "failed": 0
    "default route": {
        "active": 0,
        "completed": 14,
        "failed": 0

Notice that “main” shows the sum for all exchanges, “static route” shows 22 successful exchanges, “default route” 14, and “monitor” (monitoring itself) has 1 active exchange in progress, the current one.

For more on auditing in OpenIG, start with the draft chapter, OpenIG Audit Framework.