Auditing the PingGateway deployment

{
  "name": "30-json-excludeif",
  "baseURI": "https://app.example.com:8444",
  "condition": "${find(request.uri.path, '^/home/json-audit-excludeif$')}",
  "heap": [
    {
      "name": "AuditService",
      "type": "AuditService",
      "config": {
        "config": {
          "filterPolicies": {
            "field": {
              "excludeIf": [
                "/access/http/request/headers/host",
                "/access/http/request/path",
                "/access/server",
                "/access/response"
              ]
            }
          }
        },
        "eventHandlers": [
          {
            "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
            "config": {
              "name": "json",
              "logDirectory": "/tmp/logs",
              "topics": [
                "access"
              ],
              "rotationRetentionCheckInterval": "1 minute",
              "buffering": {
                "maxSize": 100000,
                "writeInterval": "100 ms"
              }
            }
          }
        ]
      }
    }
  ],
  "auditService": "AuditService",
  "handler": "ReverseProxyHandler"
}

package scripts.groovy

import org.forgerock.openig.openam.SsoTokenContext
import org.forgerock.services.context.RequestAuditContext

/**
 * Sample ScriptableFilter implementation to capture the user id from the session
 * and inject it into the RequestAuditContext for later use when the audit event
 * is written.
 *
 * This ScriptableFilter should be added in the filter chain at whatever point the
 * desired user id is available - e.g. on the session after SSO.
 *
 * "handler": {
 *   "type": "Chain",
 *   "config": {
 *     "filters": [ {
 *        "name": "SingleSignOnFilter-1",
 *         "type": "SingleSignOnFilter",
 *         "config": {
 *           "amService": "AmService-1"
 *         }
 *       }, {
 *         "type" : "ScriptableFilter",
 *         "config" : {
 *           "file" : "InjectUserIdSso.groovy",
 *           "type": "application/x-groovy"
 *         }
 *       }
 *     ],
 *     "handler" : "ReverseProxyHandler",
 * }
 *
 * When using the SSO/ CDSSO flow then the SsoTokenContext is guaranteed to exist and
 * be populated if there was no error. The RequestAuditContext is also guaranteed to
 * be available. Note also that if the SessionInfoFilter is present in the route then
 * a SessionInfoContext would be available in the context chain and could be queried
 * for user info.
 *
 * Implementors may decide which user id field to capture in the audit event:
 * - The sessionInfo universalId - 'universalId' - is always available as
 *   provided by AM and resembles -
 *   e.g. "id=bonnie,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org".
 * - The sessionInfo username - mapped to 'username') resembles - e.g. "bonnie".
 *   Field 'username' should be preferred to 'uid', which also points to 'username'.
 *
 * Additional error handling may be required.
 *
 * @see RequestAuditContext
 * @see SsoTokenContext
 * @see org.forgerock.openig.openam.SessionInfoContext
 */

def requestAuditContext = context.asContext(RequestAuditContext.class)
def ssoTokenContext = context.asContext(SsoTokenContext.class)

// The sessionInfo 'universalId' is always available, though 'username' may be unknown
requestAuditContext.setUserId(ssoTokenContext.universalId)

// Propagate the request to the next filter/ handler in the chain
next.handle(context, request)

{
  "name": "audit-sso",
  "baseURI": "https://app.example.com:8444",
  "condition": "${find(request.uri.path, '^/home/audit-sso$')}",
  "heap": [
    {
      "name": "AuditService",
      "type": "AuditService",
      "config": {
        "eventHandlers": [
          {
            "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
            "config": {
              "name": "jsonstdout",
              "elasticsearchCompatible": false,
              "topics": [
                "access"
              ]
            }
          }
        ],
        "config": {}
      }
    },
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/"
      }
    }
  ],
  "auditService": "AuditService",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SingleSignOnFilter-1",
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        },
        {
          "type" : "ScriptableFilter",
          "config" : {
            "file" : "InjectUserIdSso.groovy",
            "type": "application/x-groovy"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

package scripts.groovy

import org.forgerock.services.context.RequestAuditContext
import org.forgerock.openig.filter.oauth2.client.OAuth2InfoContext

/**
 * Sample script implementation supporting user id injection in an OpenId scenario.
 *
 * <p>This sample captures the user id and injects it into the RequestAuditContext for later use when the audit event is
 * written.
 *
 * <p>This ScriptableFilter should be added in the filter chain at whatever point the desired user id is available -
 * e.g. after OpenId client authentication (in the OAuth2 authentication filter chain) - as follows:
 * <pre>
 * {@code
 * "handler" : {
 *   "type" : "Chain",
 *   "config" : {
 *     "filters" : [ {
 *       "type" : "AuthorizationCodeOAuth2ClientFilter",
 *       "config" : {
 *         ...
 *         "registrations" : [ "ClientRegistrationWithOpenIdScope" ],
 *       }
 *     }, {
 *       "type" : "ScriptableFilter",
 *       "config" : {
 *         "file" : "InjectUserIdOpenId.groovy",
 *         "type": "application/x-groovy"
 *       }
 *     } ],
 *     "handler" : "display-user-info-groovy-handler"
 *   }
 * }
 * }
 * </pre>
 *
 * <p>The ClientRegistration associated with the above AuthorizationCodeOAuth2ClientFilter config will require the
 * 'openid' scope. The {@link OAuth2InfoContext} and {@link RequestAuditContext} are guaranteed to exist and be
 * populated on successful authentication.
 *
 * <p>Implementors may decide which 'user_info' field to capture in the audit event:
 * <ul>
 *   <li>The userinfo 'sub' field is the user's "complex" ID marked with a type - e.g. "(usr!bonnie)".
 *   <li>The userinfo 'subName' field is the user's username (or resource name) - e.g. "bonnie".
 *   <li>To capture the universalId (consistent with the session info universalId), it is necessary to configure AM to
 *   provide it as a claim in the id-token. To do this, edit the OIDC Claims Script to include the following line just
 *   prior to the UserInfoClaims creation: computedClaims["universalId"] = identity.universalId
 *   <li>This will include 'universalId' in the userinfo which we can use with audit e.g.
 *   "id=bonnie,ou=user,o=myrealm,ou=services,dc=openam,dc=forgerock,dc=org"
 * </ul>
 *
 * <p>Additional error handling may be required.
 */

def requestAuditContext = context.asContext(RequestAuditContext.class)
def oauth2InfoContext = context.asContext(OAuth2InfoContext.class)

// The AuthorizationCodeOAuth2ClientFilter captures userinfo in a dedicated OAuth2Info context. We can query this for
// 'userInfo' values: 'sub', 'subName' or anything else made available via the OIDC Claims Script (see above).
requestAuditContext.setUserId(oauth2InfoContext.userInfo["sub"])

// Propagate the request to the next filter/ handler in the chain
next.handle(context, request)

{
  "name": "audit-oidc",
  "baseURI": "https://app.example.com:8444",
  "condition": "${find(request.uri.path, '^/home/id_token')}",
  "heap": [
    {
      "name": "AuditService",
      "type": "AuditService",
      "config": {
        "eventHandlers": [
          {
            "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
            "config": {
              "name": "jsonstdout",
              "elasticsearchCompatible": false,
              "topics": [
                "access"
              ]
            }
          }
        ],
        "config": {}
      }
    },
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AuthenticatedRegistrationHandler-1",
      "type": "Chain",
      "config": {
        "filters": [
          {
            "name": "ClientSecretBasicAuthenticationFilter-1",
            "type": "ClientSecretBasicAuthenticationFilter",
            "config": {
              "clientId": "oidc_client",
              "clientSecretId": "oidc.secret.id",
              "secretsProvider": "SystemAndEnvSecretStore-1"
            }
          }
        ],
        "handler": "ForgeRockClientHandler"
      }
    }
  ],
  "auditService": "AuditService",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "AuthorizationCodeOAuth2ClientFilter-1",
          "type": "AuthorizationCodeOAuth2ClientFilter",
          "config": {
            "clientEndpoint": "/home/id_token",
            "failureHandler": {
              "type": "StaticResponseHandler",
              "config": {
                "status": 500,
                "headers": {
                  "Content-Type": [
                    "text/plain"
                  ]
                },
                "entity": "Error in OAuth 2.0 setup."
              }
            },
            "registrations": [
              {
                "name": "oidc-user-info-client",
                "type": "ClientRegistration",
                "config": {
                  "clientId": "oidc_client",
                  "issuer": {
                    "name": "Issuer",
                    "type": "Issuer",
                    "config": {
                      "wellKnownEndpoint": "http://am.example.com:8088/openam/oauth2/.well-known/openid-configuration"
                    }
                  },
                  "scopes": [
                    "openid",
                    "profile",
                    "email"
                  ],
                  "authenticatedRegistrationHandler": "AuthenticatedRegistrationHandler-1",
                  "clientSecretIdUsage": "ID_TOKEN_VALIDATION_ONLY",
                  "clientSecretId": "oidc.secret.id",
                  "secretsProvider": "SystemAndEnvSecretStore-1"
                }
              }
            ],
            "requireHttps": false,
            "cacheExpiration": "disabled"
          }
        },
        {
          "type": "ScriptableFilter",
          "config": {
            "file": "InjectUserIdOpenId.groovy",
            "type": "application/x-groovy"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}