PingAM 7.5.1

REST API auditing

AM supports two audit logging services: the common REST-based Audit Logging service, and the legacy Logging service, which is based on a Java SDK.

Both audit facilities log AM REST API calls.

Common Audit Logging of REST API calls

AM logs information about all REST API calls to the access topic. For more information about AM audit topics, see Audit log topics.

Locate specific REST endpoints in the http.path log file property.

Legacy Logging of REST API calls

This functionality is labelled as legacy.

AM logs information about REST API calls to two files:

amRest.access

Records accesses to a common REST endpoint, regardless of whether the request successfully reached the endpoint through policy authorization.

An amRest.access example is as follows:

$ cat openam/var/audit/amRest.access
#Version: 1.0
#Fields: time  Data  LoginID  ContextID  IPAddr  LogLevel  Domain  LoggedBy  MessageID  ModuleName
NameID  HostName
"2011-09-14 16:38:17"   /home/user/openam/var/audit/ "cn=dsameuser,ou=DSAME Users,o=openam"
aa307b2dcb721d4201 "Not Available" INFO  o=openam   "cn=dsameuser,ou=DSAME Users,o=openam"
LOG-1  amRest.access  "Not Available"  192.168.56.2
"2011-09-14 16:38:17"  "Hello World"  id=bjensen,ou=user,o=openam 8a4025a2b3af291d01  "Not Available"
INFO  o=openam id=amadmin,ou=user,o=openam "Not Available" amRest.access "Not Available"
192.168.56.2

amRest.authz

Records all common REST authorization results regardless of success. If a request has an entry in the amRest.access log, but no corresponding entry in amRest.authz, then that endpoint was not protected by an authorization filter and therefore the request was granted access to the resource.

The amRest.authz file contains the Data field, which specifies the authorization decision, resource, and type of action performed on that resource. The Data field has the following syntax:

("GRANT"||"DENY") > "RESOURCE | ACTION"

  • GRANT > is prepended to the entry if the request was allowed.

  • DENY > is prepended to the entry if the request was not allowed.

  • RESOURCE is ResourceLocation | ResourceParameter, where:

    • ResourceLocation is the endpoint location (for example, subrealm/applicationtypes).

    • ResourceParameter is the ID of the resource being touched (for example, myApplicationType) if applicable.

    Otherwise, this field is empty if touching the resource itself, such as in a query.

  • ACTION is ActionType | ActionParameter, where:

    • ActionType is CREATE||READ||UPDATE||DELETE||PATCH||ACTION||QUERY.

    • ActionParameter is one of the following depending on the ActionType:

      • For CREATE: the new resource ID

      • For READ: empty

      • For UPDATE: the revision of the resource to update

      • For DELETE: the revision of the resource to delete

      • For PATCH: the revision of the resource to patch

      • For ACTION: the actual action performed (for example, "forgotPassword")

      • For QUERY: the query ID if any

$ cat openam/var/audit/amRest.authz
#Version: 1.0
#Fields: time   Data  ContextID  LoginID  IPAddr  LogLevel  Domain  MessageID  LoggedBy  NameID
ModuleName    HostName
"2014-09-16 14:17:28"   /var/root/openam/var/audit/   7d3af9e799b6393301
"cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org" "Not Available" INFO
dc=openam,dc=forgerock,dc=org  LOG-1  "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org"
"Not Available" amRest.authz    10.0.1.5
"2014-09-16 15:56:12"  GRANT  sessions|ACTION|logout|AdminOnlyFilter  d3977a55a2ee18c201
id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org "Not Available" INFO  dc=openam,dc=forgerock,dc=org
OAuth2Provider-2  "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org"  "Not Available"
amRest.authz    127.0.0.1
"2014-09-16 15:56:40"   GRANT  sessions|ACTION|logout|AdminOnlyFilter  eedbc205bf51780001
id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org  "Not Available" INFO dc=openam,dc=forgerock,dc=org
OAuth2Provider-2  "cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org"  "Not Available"
amRest.authz    127.0.0.1

AM also provides additional information in its debug notifications for accesses to any endpoint, depending on the message type (error, warning or message) including realm, user, and result of the operation.