Auditing your deployment

{
  "_id": "23a...-23",
  "timestamp": "...",
  "eventName": "OPENIG-HTTP-ACCESS",
  "transactionId": "23a...-22",
  "userId": "id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
  "client": {
    "ip": "0:0:0:0:0:0:0:1",
    "port": 57843
  },
  "server": {
    "ip": "0:0:0:0:0:0:0:1",
    "port": 8080
  },
  "http": {
    "request": {
      "secure": false,
      "method": "GET",
      "path": "http://ig.example.com/home/audit-sso",
      "headers": {
        "accept": ["text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,/;q=0.8"],
        "host": ["ig.example.com:8080"],
        "user-agent": [...]
      }
    }
  },
  "response": {
    "status": "SUCCESSFUL",
    "statusCode": "200",
    "elapsedTime": 276,
    "elapsedTimeUnits": "MILLISECONDS"
  },
  "ig": {
    "exchangeId": "1dc...-26",
    "routeId": "audit-sso",
    "routeName": "audit-sso"
  },
  "source": "audit",
  "topic": "access",
  "level": "INFO"
}

package scripts.groovy

import org.forgerock.services.context.AttributesContext
import org.forgerock.services.context.RequestAuditContext

/**
 * Sample script implementation supporting user id injection in an OpenId scenario.
 * This sample captures the user id and injects 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. after OpenId client authentication (in the
 * OAuth2 authentication filter chain) - as follows:
 *
 * "handler" : {
 *   "type" : "Chain",
 *   "config" : {
 *     "filters" : [ {
 *       "type" : "OAuth2ClientFilter",
 *       "config" : {
 *         ...
 *         "target" : "${attributes.target}",
 *         "registrations" : [ "ClientRegistrationWithOpenIdScope" ],
 *       }
 *     }, {
 *       "type" : "ScriptableFilter",
 *       "config" : {
 *         "file" : "InjectUserIdOpenId.groovy",
 *         "type": "application/x-groovy"
 *       }
 *     } ],
 *     "handler" : "display-user-info-groovy-handler"
 *   }
 * }
 *
 * The ClientRegistration associated with the above OAuth2ClientFilter config will
 * require the 'openid' scope. The OAuth2SessionContext is guaranteed to exist and
 * be populated on successful authentication. The userinfo will then be populated
 * according to the OAuth2ClientFilter OpenId 'target' configuration (e.g. in this
 * sample, on the AttributesContext). The 'target' referenced will be populated
 * with a 'user_info' JSON value containing the userinfo. It should be noted that
 * the OAuth2ClientFilter 'target' config is a config-time expression, and cannot
 * be used in a ScriptableFilter to read runtime data. The RequestAuditContext is
 * also guaranteed to be available.
 *
 * Implementors may decide which 'user_info' field to capture in the audit event:
 * - The userinfo 'sub' field is the user's "complex" ID marked with a type - e.g.
 *   "(usr!bonnie)".
 * - The userinfo 'subName' field is the user's username (or resource name) - e.g.
 *   "bonnie".
 * - 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
 * - 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"
 *
 * Additional error handling may be required.
 *
 * @see RequestAuditContext
 * @see AttributesContext
 */

def requestAuditContext = context.asContext(RequestAuditContext.class)
def attributesContext = context.asContext(AttributesContext.class)

// The OAuth2ClientFilter captures userinfo based on its 'target' configuration.
// In this sample 'target' is configured as the AttributesContext with key "target".
// We can query this for 'user_info' values: 'sub', 'subName' or anything else
// made available via the OIDC Claims Script (see above).
def oauth2UserInfo = attributesContext.getAttributes().get("target")
requestAuditContext.setUserId(oauth2UserInfo.get("user_info").get("sub"))

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

{
  "_id": "b64...-25",
  "timestamp": "2021...",
  "eventName": "OPENIG-HTTP-ACCESS",
  "transactionId": "b64...-24",
  "userId": "(usr!demo)",
  "client": {
    "ip": "0:0:0:0:0:0:0:1",
    "port": 64443
  },
  "server": {
    "ip": "0:0:0:0:0:0:0:1",
    "port": 8080
  },
  "http": {
    "request": {
      "secure": false,
      "method": "GET",
      "path": "http://ig.example.com:8080/home/id_token",
      "headers": {
        "accept": ["text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,/;q=0.8"],
        "host": ["ig.example.com:8080"],
        "user-agent": [...]
      }
    }
  },
  "response": {
    "status": "SUCCESSFUL",
    "statusCode": "200",
    "elapsedTime": 199,
    "elapsedTimeUnits": "MILLISECONDS"
  },
  "ig": {
    "exchangeId": "1dc...-26",
    "routeId": "audit-oidc",
    "routeName": "audit-oidc"
  },
  "source": "audit",
  "topic": "access",
  "level": "INFO"
}

package scripts.groovy

import org.forgerock.http.session.SessionContext
import org.forgerock.services.context.RequestAuditContext

/**
 * Sample ScriptableFilter implementation to capture the user id obtained from a
 * SAML assertion. The IG SamlFederationHandler captures this and locates it on
 * the SessionContext with the key as the configured SAML 2 user id key. We then
 * take this and inject it into the RequestAuditContext for later use when the
 * audit event is written.
 *
 * This ScriptableFilter should be added in the filter chain together with the
 * SamlFederationHandler, as follows. Note that the InjectUserIdSaml.groovy script
 * operates on the response, injecting the userId as captured by the handler.
 *
 * {
 *     "condition" : "${matches(request.uri.path,'^/api/saml')}",
 *     "handler" : {
 *         "type" : "Chain",
 *         "config" : {
 *             "filters" : [ {
 *                 "type" : "ScriptableFilter",
 *                 "config" : {
 *                     "file" : "InjectUserIdSaml.groovy",
 *                     "type": "application/x-groovy"
 *                 }
 *             } ],
 *             "handler" : {
 *                 "name" : "saml_handler_SPOne",
 *                 "type" : "SamlFederationHandler",
 *                 "config" : {
 *                      "assertionMapping" : {
 *                          "SPOne_userName" : "uid",
 *                          "SPOne_password" : "mail"
 *                      },
 *                      "redirectURI" : "/api/home",
 *                      "logoutURI" : "http://openig.example.com:8082/api/after_logout",
 *                      "subjectMapping" : "SubjectName_SPOne",
 *                      "authnContext" : "AuthnContext_SPOne",
 *                      "sessionIndexMapping" : "SessionIndex_SPOne"
 *                 }
 *             }
 *         }
 *     }
 * }
 *
 * The SessionContext and RequestAuditContext are guaranteed to be available and the
 * SessionContext will have been populated with userinfo on successful authentication.
 *
 * Implementors may decide which user id field to capture in the audit event:
 * - This should be based on SAML attribute mappings and/ or the subject mapping (if
 *   transient names are not used).
 * - Other attributes are available, such as 'uid' and 'userName', though  it must be
 *   noted that there is an expectation that the IDP makes available the user id.
 * - In this sample, 'SPOne_userName' maps to the 'uid'.
 *
 * Additional error handling may be required.
 *
 * @see RequestAuditContext
 * @see SessionContext
 */

// Propagate the request to the next filter/ handler in the chain
next.handle(context, request)
    .then({ response ->
        def requestAuditContext = context.asContext(RequestAuditContext.class)
        def sessionContext = context.asContext(SessionContext.class)

        // Inject the user id as captured by the SamlFederationHandler
        requestAuditContext.setUserId(sessionContext.getSession().get("SPOne_userName"))
        return response
    })

{
  "_id": "82f...-14",
  "timestamp": "2021-...",
  "eventName": "OPENIG-HTTP-ACCESS",
  "transactionId": "82f...-13",
  "userId": "demo",
  "client": {
    "ip": "0:0:0:0:0:0:0:1",
    "port": 60655
  },
  "server": {
    "ip": "0:0:0:0:0:0:0:1",
    "port": 8080
  },
  "http": {
    "request": {
      "secure": false,
      "method": "POST",
      "path": "http://sp.example.com:8080/saml/fedletapplication/metaAlias/sp",
      "headers": {
        "accept": ["text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,/;q=0.8"],
        "content-type": ["application/x-www-form-urlencoded"],
        "host": ["sp.example.com:8080"],
        "user-agent": [...]
      }
    }
  },
  "response": {
    "status": "SUCCESSFUL",
    "statusCode": "302",
    "elapsedTime": 2112,
    "elapsedTimeUnits": "MILLISECONDS"
  },
  "ig": {
    "exchangeId": "1dc...-26",
    "routeId": "audit-saml",
    "routeName": "audit-saml"
  },
  "source": "audit",
  "topic": "access",
  "level": "INFO"
}