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 CategoryDescription
audit.aznAuthorization events.
audit.authnAuthentication 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:

ElementDescription
outcomeThe outcome of the event. The outcome element can be one of the following values:
0: Success
1: Failure
2: Pending
3: Unknown
originatorThe server which originated the event being logged.
originator/componentThe component which originated the event being logged.
originator/event_idThe identifier of the event, which can be one of the following:
101: Login
103: Logout
104: Authenticate
108: Authorization check
109: Resource access
originator/locationThe 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.
accessorThe 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/principalUser 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_idThe 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_locationThe IP address of the client which originated the request.
accessor/user_location_typeThe format of the data in the user_location element. Valid values include: IPV4, IPV6
targetThe 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/objectThe 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/policyThe name of the authorization policy which was applied to the request which generated the auditing record.
target/object/methodThe HTTP method which was used when accessing the resource.
target/object/hostThe host which was referenced when accessing the resource.
target/object/pathThe path of the resource which was being accessed.
authntypeThe type of authentication that the user completed.

XML specific elements:

ElementDescription
dateCurrent 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:

ElementDescription
instant/epochSecondThe number of seconds since Epoch at which the audit event was generated.
levelThe logging level for the event. For audit records this will always have the value of 'AUDIT'.

Did this page help you?