We Have Moved
The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway
The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.
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'. |