Cumulative Statistics with Identity Gateway

How healthy is your Identity Gateway? How healthy are the downstream applications it protects. Cough, cough - one might think.
IG Studio allows to easily enable statistics collection. Data is cumulative since server startup or over recent time intervals. Statistics-based health checking is not just if endpoints are alive or dead, but how they are serving clients. 

So, bring up IG Studio and configure the /rocksock application (route) and enable statistics for it. 

Turning statistics on and providing the percentiles sets the "monitor" object in the configuration.

  "monitor" : {

    "enabled" : true,

    "percentiles" : [ 0.25, 0.5, 0.9, 0.99, 0.999, 0.9999 ]

  }

The cumulative statistics can be retrieved with a simple curl command :

curl http://openig.example.com:8080/openig/api/system/objects/_router/routes/rocksock/monitoring?_prettyPrint=true

{

  "requests" : {

    "total" : 1590742,

    "active" : 0

  },

  "responses" : {

    "total" : 1590742,

    "info" : 0,

    "success" : 1590742,

    "redirect" : 0,

    "clientError" : 0,

    "serverError" : 0,

    "other" : 0,

    "errors" : 0,

    "null" : 0

  },

  "throughput" : {

    "mean" : 3060.6,

    "lastMinute" : 3206.0,

    "last5Minutes" : 2584.7,

    "last15Minutes" : 1349.9

  },

  "responseTime" : {

    "mean" : 0.017,

    "median" : 0.009,

    "standardDeviation" : 0.042,

    "total" : 31727,

    "percentiles" : {

      "0.25" : 0.007,

      "0.5" : 0.009,

      "0.9" : 0.022,

      "0.99" : 0.206,

      "0.999" : 0.504,

      "0.9999" : 0.995

    }

  }

}

The allows allows to read out characteristics which help to determine the actual health of the system:

• IG is up and this application protection (route) is deployed
• IG treated 1590742 requests since startup for /rocksock of which all received a success response
• The throughput over that last minute was 3206 requests per second, 2584 requests/sec over the last 5 minutes and 1349.9 requests over the last 15 minutes
• 99.99 % of the requests were responded to in 0.995 milliseconds or less

For further details on configuring statistics and analysing the result, see the Configuration Reference. Note that the absolute response times depend a lot on the response times of the downstream applications.

The Identity Gateway Studio will be shipped with ForgeRock Identity Gateway 5.0.

For more, see the Identity Gateway Studio introduction or the blog post on message capture.

By Joachim Andres

Message Capture with OpenIG

Setting up protection for a web application or API is much easier if you know what is actually going on between client and server.
OpenIG functions by the concept of a reverse web proxy, primarily with the objective to enforce authentication and authorization. However it also allows to simply log inbound and outbound messages to a file.

The OpenIG Studio provides a straightforward way to configure capture inbound and outbound messages.



















The capture is logged by default in the route-rocksock.log file. In this example, openig.example.com is the external hostname which hits OpenIG. The internal hostname is internal.company.com. This is not know to the client but configured in the route configuration for /rocksock in OpenIG.
The route-rocksock.log file from the example :

--- (request) id:0307be7f-3166-4dde-bf08-698dd82c2c5b-178 --->   

GET http://openig.example.com:8080/rocksock/ HTTP/1.1
accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
accept-encoding: gzip, deflate
accept-language: en;q=1,de;q=0.9,en-US;q=0.8,fr-FR;q=0.7,it;q=0.6
connection: keep-alive
host: openig.example.com:8080
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:36.0) Gecko/20100101 Firefox/36.0 SeaMonkey/2.33.1

--- (request) id:0307be7f-3166-4dde-bf08-698dd82c2c5b-178 --->

GET http://internal.company.com:9080/rocksock/ HTTP/1.1
accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
accept-encoding: gzip, deflate
accept-language: en;q=1,de;q=0.9,en-US;q=0.8,fr-FR;q=0.7,it;q=0.6
connection: keep-alive
host: openig.example.com:8080
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:36.0) Gecko/20100101 Firefox/36.0 SeaMonkey/2.33.1

<--- (response) id:0307be7f-3166-4dde-bf08-698dd82c2c5b-178 ---

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 42
Content-Type: text/html
Date: Tue, 25 Oct 2016 16:13:48 GMT
ETag: W/"42-1477411512000"
Last-Modified: Tue, 25 Oct 2016 16:05:12 GMT

[entity]

<--- (response) id:0307be7f-3166-4dde-bf08-698dd82c2c5b-178 ---

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 42
Content-Type: text/html
Date: Tue, 25 Oct 2016 16:13:48 GMT
ETag: W/"42-1477411512000"
Last-Modified: Tue, 25 Oct 2016 16:05:12 GMT

[entity]

The route configuration as produced by the OpenIG Studio looks as follows :
{
  "name": "rocksock",
  "baseURI": "http://internal.company.com:9080",
  "condition": "${matches(request.uri.path, '^/rocksock')}",
  "monitor": false,
  "capture": [
    "request",
    "response"
  ],
  "heap": [
    {
      "type": "ClientHandler",
      "name": "ClientHandler",
      "capture": [
        "request",
        "response"
      ]
    }
  ],
  "handler": "ClientHandler"
}

The IG studio will be shipped with ForgeRock Identity Gateway 5.0. For more, see the OpenIG Studio introduction .

By Joachim Andres

Introducing OpenIG Studio

According to the Twelve-Factor App, OpenIG [1] configuration is considered code [2]. Organizations are driving towards "headless" deployment models meaning that beyond the development stage, administration consoles or management APIs are disabled. It's the continuous integration and delivery pipeline which takes care of bringing a change from development to production in an automated way.

With this in mind and combined with the need to simplify the creation of OpenIG application protections (routes), we decided build an IDE-type utility, the OpenIG studio. OpenIG studio allows to visually build application or API protection (aka route) enabling message capture, throttling, authentication, authorization and statistics gathering. Further, OpenIG studio allows to do rapid prototyping of what is being built.

You can test drive the OpenIG studio without hassle via Docker. It only takes a couple of docker commands to get OpenIG running. Then point a browser to http://localhost:8080/openig/studio and create an application/API protection.

{
  "name": "rocksock",
  "baseURI": "http://internal.company.com:9080",
  "condition": "${matches(request.uri.path, '^/rocksock')}",
  "monitor": false,
  "handler": "ClientHandler"
}

You can export the configuration (ehem code) and then feed your source code management system (e.g. git) and ultimately the continuous delivery pipeline.

For example :
 {
  "name": "rocksock",
  "baseURI": "http://internal.company.com:9080",
  "condition": "${matches(request.uri.path, '^/rocksock')}",
  "monitor": false,
  "handler": "ClientHandler"
}

{
  "name": "rocksock",
  "baseURI": "http://internal.company.com:9080",
  "condition": "${matches(request.uri.path, '^/rocksock')}",
  "monitor": false,
  "handler": "ClientHandler"
}

Now that the configuration (ehem code) is built, how to rapidly test it ? As the studio is packaged with the OpenIG war file, the new configuration can be pushed to this running OpenIG instance. Press "Deploy" !

What all these configuration options are useful for, how to shut down the studio in production deployments and how to deal with deployment environment specific parameters merit separate contemplation.

The studio will be shipped with ForgeRock Identity Gateway 5.0.

Notes

[1] OpenIG is an identity gateway integrating (legacy) applications with modern digital identity tokens and procedures. Based on a reverse proxy type architecture, it can enforce authentication and authorization for access to web applications or APIs.
[2] With the exception for deployment environment specific settings. OpenIG provides a way to deal with this following Twelve-Factor App recommendations.

By Joachim Andres

OpenIG on Docker: The Perfect Couple

"Docker containers wrap a piece of software in a complete filesystem that contains everything needed to run [...]" [1]

OpenIG (Open Identity Gateway) provides an elegant yet flexible way to integrate your applications, devices, APIs with modern identity standards such as token types, authentication and authorization. The gateway as your integration component can be deployed and scaled along the applications and services it secures. 
Whilst organizations adopt containerization as part of a "well-oiled" delivery pipeline, which includes the gateway, OpenIG in a container is also very beneficial for evaluation purposes. Here's how you can evaluate in just a couple of minutes.

As prerequisites, you need docker and git on your system.

1. Checkout the ForgeRock docker project to retrieve the Dockerfile and sample OpenIG configuration files
• git clone https://stash.forgerock.org/scm/docker/docker.git
• cd docker/openig
2. Build the docker image (the --no-cache option assures that it pulls the latest OpenIG nightly build at each docker build)
• docker build -t forgerock/openig:latest .
3. Run the docker image and mount the sample-config directory from your local git copy in the container
• docker run --detach -p 8080:8080 --volume <LOCAL_PATH_TO_GIT>/docker/openig/sample-config:/var/openig --name openig -it forgerock/openig
  

To test the sample configuration, point your client (e.g. web browser, curl) to http://localhost:8080/simplethrottle for instance. The response is determined by the StaticResponseHandler setting in the 20-simplethrottle.json file.

A simplified version of this procedure however without the sample configuration but not necessitating usage of git and clone the full repo goes as follows. This is well suited to evaluate the upcoming user interface.

1. Download the Dockerfile from https://stash.forgerock.org/projects/DOCKER/repos/docker/browse/openig/Dockerfile
2. Build the docker image (as above)
• docker build -t forgerock/openig:latest .
3. Run the docker image
• docker run -d -p 8080:8080 --name openig -it forgerock/openig

Other useful commands:

• Stop container: docker stop openig
• Start container: docker start openig
• Get shell prompt: docker exec -i -t openig /bin/bash
• Remove container: docker rm openig

References

[1] "Package your application into a standardized unit for software development". Retrieved from https://www.docker.com/what-docker on Sep 6th, 2016.

Unlocking the Authorization Asset

Consumer identity is a core asset to your business. Unlocking authorization and leveraging it into your business processes and (micro) services helps you in this endeavor as it drives a yet higher level of personalization and how users interact with resources and objects.

In a recent post titled "Authorization for Everything" I outlined how any resource or object can be described in ForgeRock's identity platform authorization framework by the example of a home cinema.

But who's going to setup the authorization objects and controls ?

(Question by an attendee of the ForgeRock Identity Summit in Düsseldorf)

User facing applications that operate or control devices or resources, like mobile applications or smart remote controls, are now enabled to call directly in the authorization framework to manage or evaluate permissions. This is also possible go via a hub to which an appliance like the home cinema would register when it is plugged in.

Smart authorization is now unlocked to any of these procedures, services and applications regardless of the platform. And the key is the REST API provided by the ForgeRock identity platform.

The key to drive authorization in the user experience or device management is the API !
Implement it where it creates most value for the consumer.

(My answer)

In full detail now how to manage and evaluate authorization elements via REST by the example of a home cinema.


Authorization Management via REST in detail
Step 1: Creating a resource type TV

First we create a resource type TV and specify the format of how to address the resource (e.g. tv://myhouse/homecinema) and possible actions for the resource.

Request:
curl -s --request POST --header "Content-Type: application/json" --data @request.json https://sso.redstone.com:443/sso/json/authzrealm/resourcetypes?_action=create&_prettyPrint=true
Request (JSON):
{
  "patterns": [
    "tv://*/*"
  ],
  "name": "tv",
  "actions": {
    "ENABLE": true,
    "DISABLE": true,
    "BROADCAST SCREEN": true,
    "BROADCAST CAMERA": true
  }
}
Response (JSON):
{
  "uuid" : "9fefc18f-5731-4963-a8d6-fa8aba7923d4",
  "name" : "tv",
  "description" : null,
  "patterns" : [ "tv://*/*" ],
  "actions" : {
    "DISABLE" : true,
    "ENABLE" : true,
    "BROADCAST CAMERA" : true,
    "BROADCAST SCREEN" : true
  },
  "createdBy" : "id=amadmin,ou=user,dc=sso-config,dc=com",
  "creationDate" : 1447989190178,
  "lastModifiedBy" : "id=amadmin,ou=user,dc=sso-config,dc=com",
  "lastModifiedDate" : 1447989190178
}
Note the resource type's UUID in the response. This value is needed later to assign a resource type to a policy.


Step 2: Creating the policy set (or application)

Next the resource set (or application) needs to be created with the resourceTypeUUID containing the one of resource type TV.

Request:
curl -s --request POST --header "Content-Type: application/json" --data @request.json https://sso.redstone.com:443/sso/json/authzrealm/applications?_action=create&_prettyPrint=true
Request (JSON):
{    "name" : "SmartHome",
    "applicationType" : "iPlanetAMWebAgentService",
    "description" : "Controlling objects in a smart home.",
    "resourceTypeUuids" : [ "9fefc18f-5731-4963-a8d6-fa8aba7923d4"],
    "subjects" : [ "Policy", "NOT", "OR", "JwtClaim", "AuthenticatedUsers", "AND", "Identity", "NONE" ],
    "entitlementCombiner" : "DenyOverride",
    "saveIndex" : null,
    "searchIndex" : null,
    "resourceComparator" : null,
    "attributeNames" : [ ],
    "editable" : true,
    "conditions" : [ "LEAuthLevel", "Policy", "Script", "AuthenticateToService", "SimpleTime", "AMIdentityMembership", "OR", "IPv6", "IPv4", "SessionProperty", "AuthScheme", "AuthLevel", "NOT", "AuthenticateToRealm", "AND", "ResourceEnvIP", "LDAPFilter", "OAuth2Scope", "Session" ]
}
Response (JSON):
{
  "lastModifiedBy" : "id=amadmin,ou=user,dc=sso-config,dc=com" ],
  "lastModifiedDate" : 1447989192860,
  "creationDate" : 1447989192860,
  "createdBy" : "id=amadmin,ou=user,dc=sso-config,dc=com",
  "applicationType" : "iPlanetAMWebAgentService",
  "subjects" : [ "Policy", "NOT", "OR", "JwtClaim", "AuthenticatedUsers", "AND", "Identity", "NONE" ],
  "entitlementCombiner" : "DenyOverride",
  "saveIndex" : null,
  "searchIndex" : null,
  "resourceComparator" : null,
  "attributeNames" : [ ],
  "editable" : true,
  "conditions" : [ "LEAuthLevel", "Policy", "Script", "AuthenticateToService", "SimpleTime", "AMIdentityMembership", "OR", "IPv6", "IPv4", "SessionProperty", "AuthScheme", "AuthLevel", "NOT", "AuthenticateToRealm", "AND", "ResourceEnvIP", "LDAPFilter", "OAuth2Scope", "Session" ],
  "description" : "Controlling objects in a smart home.",
  "name" : "SmartHome"
}
Step 3: Creating the policy giving permissions to Bob

Next the resource set (or application) needs to be created with the resourceTypeUUID containing the one of resource type TV.

Request:
curl -s --request POST --header "Content-Type: application/json" --data @request.json https://sso.redstone.com:443/sso/json/authzrealm/policies?_action=create&_prettyPrint=true
Request (JSON):
{
    "name" : "HomeCinema",
    "active" : true,
    "description" : "",
    "applicationName" : "SmartHome",
    "actionValues" : {
      "ENABLE" : true,
      "DISABLE" : true,
      "BROADCAST SCREEN" : true,
      "BROADCAST CAMERA" : true
    },
    "resources" : [ "tv://myhouse/homecinema" ],
    "subject" : {
      "type" : "Identity",
      "subjectValues" : [ "id=bob,ou=user,o=authzrealm,ou=services,dc=sso-config,dc=com" ]
    },
    "resourceTypeUuid" : "9fefc18f-5731-4963-a8d6-fa8aba7923d4"
}
Response (JSON):
{
  "name" : "HomeCinema",
  "active" : true,
  "description" : "",
  "applicationName" : "SmartHome",
  "actionValues" : {
    "DISABLE" : true,
    "ENABLE" : true,
    "BROADCAST CAMERA" : true,
    "BROADCAST SCREEN" : true
  },
  "resources" : [ "tv://myhouse/homecinema" ],
  "subject" : {
    "type" : "Identity",
    "subjectValues" : [ "id=bob,ou=user,o=authzrealm,ou=services,dc=sso-config,dc=com" ]
  },
  "resourceTypeUuid" : "9fefc18f-5731-4963-a8d6-fa8aba7923d4",
  "lastModifiedBy" : "id=amadmin,ou=user,dc=sso-config,dc=com",
  "lastModifiedDate" : "2015-11-20T03:13:14.274Z",
  "createdBy" : "id=amadmin,ou=user,dc=sso-config,dc=com",
  "creationDate" : "2015-11-20T03:13:14.274Z"
}
Step 4: Evaluating the policy for user Bob

Next the resource set (or application) needs to be created with the resourceTypeUUID containing the one of resource type TV. For completeness - the procedure is already outlined in "Authorization for Everything" - here's how an upstream application would evaluate if Bob can broadcast the screen (or any other action). 

Request URL:

https://sso.redstone.com:443/sso/json/authzrealm/policies?_action=evaluateTree&_prettyPrint=true

Request (JSON):
{
  "application": "SmartHome",
  "resource": "tv://myhouse/homecinema",
  "subject": {
    "ssoToken": "AQIC5wM2LY4SfcxbXJgKBtBsbzH0OtxslnEQDHK2RJ5UJho.*AAJTSQACMDIAAlNLABQtOTIwMDUyMDgxMTA2Mzk1NjIzMgACUzEAAjAx*"
  }
}
Response (JSON):
[ {
  "advices" : { },
  "ttl" : 9223372036854775807,
  "resource" : "tv://myhouse/homecinema",
  "actions" : {
    "DISABLE" : true,
    "ENABLE" : true,
    "BROADCAST CAMERA" : true,
    "BROADCAST SCREEN" : true
  },
  "attributes" : { }
} ]

If you want to go further, look at the details of policy creation via REST, policy evaluation or maybe even reproduce my demo at the Identity Summit in Düsseldorf, check the openam-high5 GitHub project. In particular the 652-authz-create-policy and 654-authz-evaluate-policy-tv.

By Joachim Andres