Skip to main content

Enabling Auditing

Overview

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'.