Auditing

Auditing is defined as the logging of audit records. It includes the collection of data about system activities that affect the secure operation of the IBM Application Gateway (IAG). IAG can capture audit events whenever any security-related auditable activity occurs. This includes events for authorization and authentication activities.

The following table shows the categories and description of auditing events which can be captured by the IAG:

Event Category	Description
audit.azn	Authorization events.
audit.authn	Authentication events.

Formatting

All auditing events will be sent to the console of the IAG. By default the events will be formatted as Extensible Markup Language (XML), but the JSON Logging configuration entry can be used to have the events formatted as JavaScript Object Notation (JSON) instead.

Configuration

Auditing is configured using the Components configuration entry. The following YAML snippet shows how to enable auditing for both authorization and authentication events in JSON format:

...
logging:
  json_logging: true
  
  components:
    - audit.azn
    - audit.authn
...

Sample Events

This section contains some sample events which illustrate what the auditing events will look like.

Authorization

XML Format:

<event rev="1.3">
   <date>2019-12-04-23:28:35.676+00:00I-----</date>
   <outcome status="0">0</outcome>
   <originator blade="iag">
      <component rev="1.1">azn</component>
      <event_id>108</event_id>
      <location>ibm-app-gw.ibm.com</location>
   </originator>
   <accessor name="testuser">
      <principal auth="oidc">testuser</principal>
      <session_id>9c98b270-7078-7028-80c8-48a7e029c4a1</session_id>
      <user_location>172.17.0.1</user_location>
   </accessor>
   <target resource="0">
      <object>
         <policy>any-auth</policy>
         <method>GET</method>
         <host>iag.vwasp.gc.au.ibm.com:8443</host>
         <path>/creds</path>
      </object>
   </target>
</event>

JSON Format:

{
    "instant": {
        "epochSecond": 1575502167
    },
    "level": "AUDIT",
    "outcome": "0",
    "originator": {
        "blade": "iag",
        "component": "azn",
        "event_id": "108",
        "location": "ibm-app-gw.ibm.com"
    },
    "accessor": {
        "user": "testuser",
        "principal": {
            "auth": "oidc",
            "name": "testuser"
        },
        "session_id": "6e0da4c4-847e-a860-800b-b94601557b2f",
        "user_location": "172.17.0.1"
    },
    "target": {
        "resource": "0",
        "object": {
            "policy": "any-auth",
            "method": "GET",
            "host": "iag.vwasp.gc.au.ibm.com:8443",
            "path": "\/creds"
        }
    }
}

Authentication

XML Format:

<event rev="1.3">
   <date>2019-12-04-23:39:46.757+00:00I-----</date>
   <outcome status="0">0</outcome>
   <originator blade="iag">
      <component rev="1.4">authn</component>
      <event_id>101</event_id>
      <location>ibm-app-gw.ibm.com</location>
   </originator>
   <accessor name="testuser">
      <principal auth="oidc">testuser</principal>
      <user_location>172.17.0.1</user_location>
      <user_location_type>IPV4</user_location_type>
   </accessor>
   <target resource="7">
      <object />
   </target>
   <authntype>oidc</authntype>
</event>

JSON Format:

{
    "instant": {
        "epochSecond": 1575502842
    },
    "level": "AUDIT",
    "outcome": "0",
    "originator": {
        "blade": "iag",
        "component": "authn",
        "event_id": "101",
        "location": "ibm-app-gw.ibm.com"
    },
    "accessor": {
        "user": "testuser",
        "principal": {
            "auth": "oidc",
            "name": "testuser"
        },
        "user_location": "172.17.0.1",
        "user_location_type": "IPV4"
    },
    "target": {
        "resource": "7",
        "object": ""
    },
    "authntype": "oidc"
}

Output Elements

The following output elements are contained in the auditing records:

Common elements:

Element	Description
outcome	The outcome of the event. The outcome element can be one of the following values: 0: Success 1: Failure 2: Pending 3: Unknown
originator	The server which originated the event being logged.
originator/component	The component which originated the event being logged.
originator/event_id	The identifier of the event, which can be one of the following: 101: Login 103: Logout 104: Authenticate 108: Authorization check 109: Resource access
originator/location	The host name (location) of the machine. If there is no host name specified, a notation of "location not specified" is substituted in the location element.
accessor	The name of the user that triggered the event. If there is no user name specified, a notation of "user not specified" or "" is substituted in the accessor element.
accessor/principal	User authorization credentials. Generally each event captures the result of an action that a user (principal) attempts on a target object. If there is no user name specified, a notation of auth="invalid" is substituted in the principal element.
accessor/session_id	The session ID that is associated with this session. This ID can be used to trace a series of events back to the authentication data that was initially provided by the user. For example, the data in the session_id element could be used to determine when a user logged in and when a user logged out.
accessor/user_location	The IP address of the client which originated the request.
accessor/user_location_type	The format of the data in the user_location element. Valid values include: IPV4, IPV6
target	The target of the request which generated the auditing record. The resource attribute, which represents a broad categorization of the target object, can be one of the following values: 0: authorization 7: authentication
target/object	The target object of the request which generated the auditing record. This is used in authorization auditing records to indicate the resource which is being accessed.
target/object/policy	The name of the authorization policy which was applied to the request which generated the auditing record.
target/object/method	The HTTP method which was used when accessing the resource.
target/object/host	The host which was referenced when accessing the resource.
target/object/path	The path of the resource which was being accessed.
authntype	The type of authentication that the user completed.

XML specific elements:

Element	Description
date	Current date and timestamp. The date element has the following format: yyyy-mm-dd-hh:mm:ss.xxx-xx:xxI----- Where: yyyy-mm-dd: Relates to the year (yyyy), the month (mm), and the day (dd). hh:mm:ss: Relates to hours (hh), minutes (mm), and seconds (ss). xxx-xx:xxI: Refers to the time zone.

JSON specific elements:

Element	Description
instant/epochSecond	The number of seconds since Epoch at which the audit event was generated.
level	The logging level for the event. For audit records this will always have the value of 'AUDIT'.