Auditing

Auditing

DirX Access acts as a source of audit events and allows a variety of auditing sinks to be integrated with DirX Access. This chapter presents the auditing subsystem, describes the externalization interface by which audit events are provided to (third-party) auditing sinks and illustrates how an integration of such auditing sinks can be achieved.

About the Functional Roles in Auditing

The functional roles of an auditing source and auditing sink need to be differentiated:

  • The auditing source is responsible for creating (a variety) of audit events and pushing them to auditing sinks.

  • The auditing sinks are responsible for processing auditing events; for example, persisting them according a DBMS scheme, making statistic analyses, and creating reports.

The role of DirX Access regarding auditing is to act as a source of audit events, not a sink for audit events. The actual auditing source is represented by the DirX Access business services on the DirX Access Server:

  • Business code (for example, the authentication or authorization services) is responsible for detecting the need to do some auditing, collecting related information (who, what, when…), formulating audit events and invoking the audit service for further handling.

  • The audit service provides processing tasks common to all audit events and is responsible for pushing provided audit events to registered sinks.

Externalization Interface

The audit source is DirX Access-internal while the sink can be externalized. This section specifies the externalization interface.

The externalization interface that an (external) auditing sink must implement is provided by the interface class com.siemens.dxa.common.callout.audit.AuditCallout. This is a simple interface comprising a single method audit. There is a single input parameter com.siemens.dxa.common.audit.source.AuditEvent. There is no return parameter. The DirX Access Server calls an auditing sink at this interface method when audit events need to be dropped.

Externalized Object Abstractions

The following artifacts specify the DirX Access audit events. The listed artifacts are provided in the DirX Access Client SDK. Their JavaDoc comments provide details on the syntax and semantics of the provided audit event information:

  • Java class AuditSourceConstants: defines constants specific to the audit events that are provided by DirX Access.

  • Java interface class AuditEvent: defines the audit events that are provided by DirX Access.

  • Java interface class AuthnEvent: defines the authentication-related parts of DirX Access audit events. Note that the value types (for example, UUID, DN) of the audit event quantities that serve the identification of the authenticated subject are situational and may vary according to the details of the deployment environment and the authentication protocol.

  • Java interface class AuthzDecisionEvent: defines the authorization decision-related parts of DirX Access audit events:

    • ResourceTypeWrapper: a simple wrapper for the XACML 1.x and 2.0 ResourceType classes. This object represents the requested resource. It provides a Java class representation for the xacml-ctx:Resource abstractions in XACML version 1.x or 2.0. The DirX Access Client SDK provides code for handling these abstractions (ResourceTypeWrapper in the package com.siemens.dxa.common.authz.xacml.context, ResourceType in the packages com.siemens.dxa.generated.applications.webservices.common.types.xacml_2_0_context and com.siemens.dxa.generated.applications.webservices.common.types.xacml_1_0_context). The method AuthzDecisionEvent.toStringResource() supports auditing sinks that are not interested in the details of corresponding XACML context syntax objects.

    • ActionTypeWrapper: a simple wrapper for the XACML 1.x and 2.0 ActionType classes. This object represents the requested action. It provides a Java class representation for the xacml-ctx:Action abstractions in XACML version 1.x or 2.0. The DirX Access Client SDK provides code for handling these abstractions (ActionTypeWrapper in package com.siemens.dxa.common.authz.xacml.context, ActionType in the packages com.siemens.dxa.generated.applications.webservices.common.types.xacml_2_0_context and com.siemens.dxa.generated.applications.webservices.common.types.xacml_1_0_context). The method AuthzDecisionEvent.toStringAction() supports auditing sinks that are not interested in the details of corresponding XACML context syntax objects.

    • DecisionTypeWrapper: a simple wrapper for the XACML 1.x and 2.0 DecisionType classes. This object represents the rendered authorization decision. It provides a Java class representation for the xacml-ctx:Decision abstractions in XACML version 1.x or 2.0. The DirX Access Client SDK provides code for handling these abstractions (DecisionTypeWrapper in the package com.siemens.dxa.common.authz.xacml.context, DecisionType in the packages com.siemens.dxa.generated.applications.webservices.common.types.xacml_2_0_context and com.siemens.dxa.generated.applications.webservices.common.types.xacml_1_0_context). The method AuthzDecisionEvent.toStringDecision() supports auditing sinks that are not interested in the details of corresponding XACML context syntax objects.

  • Java interface class AuthzPolicyEvent: defines the authorization policy-related events at the authorization service such as equipping PDPs with authorization policies.

  • Java interface class ConfigEvent: defines the configuration data-related events at the configuration service concerning the creation, modification or removal of configuration abstractions such PEP or PDP configurations. This class refers to basic abstractions such as the type of configuration abstraction (by fully qualified Java class name) and configuration object identifier. The events created by additions and modifications of configuration objects also imprint the full configuration object in a Java class representation referring to objects that are defined in the XML schema file dxa-configuration.xsd. The DirX Access Client SDK already contains JAX-WS-generated Java code to work with these objects.

  • Java interface class SubjectAttributeFinderEvent: defines the subject attribute finder-related events from the authorization service.

Note that these abstractions may change with different product versions. External auditing sinks processing DirX Access auditing events are expected to accommodate the ability to handle received audit events in a version-specific manner. The DirX Access audit event codes are prefixed in a way that allows identifying the product version.

Provided Implementation

DirX Access provides the off-the-shelf implementation of the externalization interface AuditCallout - Log4JAuditCalloutHandler.This implementation is based on Log4J and allows using Log4J appenders to process DirX Access audit events. This class provides the default implementation for the externalization interface AuditCallout and is delivered with the product core. This default implementation is presented in more detail in the following sections.

Log4J-Based Auditing Sinks

The default implementation of the DirX Access auditing externalization interface AuditCallout makes use of Log4J.

In this approach, the actual decoupling between the auditing source (DirX Access-internal) and external auditing sinks is done by Log4J:

  • The Log4JAuditCalloutHandler invokes Log4J methods; for example, LOGGER.info(auditEvent) with an instance of a DirX Access AuditEvent class. Executing this call causes the audit event to be passed to an external component, Log4J in this case.

  • The sink part is represented by modules deployed with the Log4J framework, so-called Log4J appenders. All functionality that is supported through Log4J appenders can be employed. Details of the provided audit event processing functionality (how to do layout, how/where to persist, whether/how to analyze, whether/how report…) are at the discretion of the (external) auditing sink.

Any Log4J appender can be used with the default Log4JAuditCalloutHandler to handle DirX Access audit events. For example:

  • Console: Prints information to the system console.

  • File: Records information in files on the local file system
    Note: out of the box, DirX Access employs a file-based appender that produces audit files called audit.log. Arbitrary Log4J appenders can be deployed for DirX Access audit data by modifying the standard Log4J configuration file log4j.properties (section “AUDIT APPENDER”).

  • Database: Records information in a JDBC database.

  • Syslog: Records information on a UNIX or Linux syslog facility.

  • Remote: Records information using a remote audit sink.

Since the Log4JAuditCalloutHandler is provided as a default implementation for the DirX Access auditing externalization interface AuditCallout, there is no need to create your own software or run the employment process for external plug-in modules if this option is chosen for a deployment.

Additional Auditing Sinks

Other implementations can also be created and used instead of Log4JAuditCalloutHandler. These implementations must satisfy the interface specified in the AuditCallout class and are free to do whatever they deem reasonable with the provided audit events.

The employment of another implementation for the DirX Access auditing externalization interface AuditCallout is described in Audit Event Plug-ins.

Auditing into DirX Audit

DirX Access can be configured to send audit events into the DirX Audit system. The steps required to set up auditing into DirX Audit are:

  • Download an appropriate version of the DirX Audit Handler plug-in from the IAM Support Portal https://iam-support.it-solutions.atos.net/ .

  • After downloading and unzipping the plug-in, open the installation guide AuditPluginForDirXAccess.pdf and follow the installation instructions on how to configure the audit handler plug-in.

  • Install the DirX Audit Handler plug-in into the DirX Access Services container.

  • Specify the local DirX Audit Handler plug-in configuration in file {DirXAccessInstallFolder}\Services\instances\{TenantId}\etc\audit_dxt.ini.

  • Modify DirX Access and request injection configuration via DirX Access Manager or by importing configuration data via DirX Access Console:

    • Customize preconfigured audit injection templates where needed so that relevant user data are injected into audit events. The preconfigured audit injection templates names for DirX Audit are prefixed with DXT_Audit.

    • Choose one of the preconfigured “DXT File Audit Callout Handler” or “DXT JMS Audit Callout Handler” audit callouts to be used by the Services container.

    • Choose the appropriate audit injection templates to be used when creating audit events.

  • Restart the DirX Access Services container.

Configuring Auditing

The configuration of auditing comprises the definition of audit event levels per actual audit sources and the declaration of the audit externalization plug-in.

It is not recommended to use auditing into a file when producing a lot of audit logs, as it can significantly impact the operating system’s I/O operations and decrease overall performance.

Audit Event Levels

The recognized audit levels are:

  • info

  • warning

  • error

  • none

These levels can be configured for the following audit event sources:

  • ServerLifecycle

  • AppRepoService

  • AuthenticationService

  • AuthorizationService

  • DecisionMaking

  • FederationService

  • SsoService

  • UserService

These configuration settings are provided on the level of a Cluster configuration object. The default audit event level for these sources is none.

Audit Event Codes

The following table shows the audit event codes used for auditing.

Source Event Code

Server LifeCycle

DXA81CSL001I "System started"

Application Repository Service

DXA8100AR600I "Application Repository record added"

DXA8100AR601I "Application Repository record modified"

DXA8100AR602I "Application Repository record deleted"

DXA8100AR610E "Application Repository record addition not authorized"

DXA8100AR611E "Application Repository record modification not authorized"

DXA8100AR612E "Application Repository record deletion not authorized"

DXA8100AR613E "Application Repository record reading not authorized"

DXA8100AR614E "Application Repository record listing not authorized"

DXA8100AR615E "Error during processing of Application Repository request"

Authentication Service

DXA81CAN301I "Re-authentication succeeded with SAML assertion"

DXA81CAN303I "Re-authentication succeeded with X.509 certificate"

DXA81CAN304I "Re-authentication succeeded with Windows credentials (Kerberos ticket or NTLM)"

DXA81CAN305I "Re-authentication succeeded with password"

DXA81CAN308I "Re-authentication succeeded with one-time-password (RFC 4226)"

DXA81CAN309I "Re-authentication succeeded with one-time-password (callback)"

DXA81CAN310I "Calling into attribute finder handler"

DXA81CAN311I "Returning from attribute finder handler"

DXA81CAN312I "Calling into authn token finder handler"

DXA81CAN313I "Returning from authn token finder handler"

DXA81CAN314I "Calling into validation handler"

DXA81CAN315I "Returning from validation handler"

DXA82AAN316I "Re-authentication succeeded with third party token"

DXA82AAN317I "Re-authentication succeeded with one-time-password (RFC 6238)"

DXA830AN318I "Re-authentication succeeded with OAuth"

DXA830AN319I "Re-authentication succeeded in trusting mode"

DXA870AN320I "Re-authentication succeeded with FIDO"

DXA890AN321I "Re-authentication succeeded with Composite"

DXA81CAN301E "Authentication failed with SAML assertion"

DXA81CAN303E "Authentication failed with X.509 certificate"

DXA81CAN304E "Authentication failed with Windows credentials (Kerberos ticket or NTLM)"

DXA81CAN305E "Authentication failed with password"

DXA81CAN308E "Authentication failed with one-time-password (RFC 4226)"

DXA81CAN309E "Authentication failed with one-time-password (callback)"

DXA82AAN316E "Authentication failed with third party token"

DXA82AAN317E "Authentication failed with one-time-password (RFC 6238)"

DXA82AAN318E "Authentication failed with OAuth"

DXA82AAN319E "Authentication failed with trusting mode"

DXA81CAN201I "Password is expired"

DXA82AAN205W "SAML assertion replay detected"

DXA850AN320E "Initial authentication failed due to risk-based authentication policy."

DXA850AN321E "Violation of risk-based authentication policy."

DXA870AN322E "Authentication failed with FIDO"

DXA890AN323E "Authentication failed with Composite"

DXA890AN324I "Calling into name mapping handler"

DXA890AN325I "Returning from name mapping handler"

Authorization Service

DXA81CAZ500I "Authorization decision "Permit" obtained from PDP"

DXA81CAZ501I "Authorization decision "Deny" obtained from PDP"

DXA81CAZ502I "Authorization decision "NotApplicable" obtained from PDP"

DXA81CAZ503I "Authorization decision "Indeterminate" obtained from PDP"

Federation Service

DXA81CFE101I "SAML assertion created (for SAML Web federation)"

DXA81CFE102I "SAML assertion created (for Web services federation)"

DXA900FE109I "OAuth 2.0 Authorization endpoint request"

DXA900FE110I "OAuth 2.0 Token endpoint request"

DXA900FE111I "OAuth 2.0 Revocation endpoint request"

DXA900FE112I "User Info endpoint request"

DXA900FE113I "OAuth 2.0 Introspection endpoint request"

DXA900FE114I "Client Registration endpoint request"

DXA900FE115I "UMA Claims Interaction endpoint request"

DXA900FE116I "UMA Resource Registration endpoint request"

DXA900FE117I "UMA Permission endpoint request"

DXA900FE118I "UMA Policy Management endpoint request"

DXA900FE119I "UMA Rule Template Registration endpoint request"

DXA900FE120I "Metadata endpoint request"

DXA900FE121I "An error occurred during processing the OAuth request"

SSO Service

DXA81CSO104I "SSO object removed as lifetime has expired"

DXA81CSO106I "SSO object removed as idle time has expired"

DXA81CSO107I "SSO object removed by logout"

DXA81CSO108I "SSO objects user account has expired"

DXA81CSO109I "SSO objects user password has expired"

DXA81CSO110I "SSO object assigned by correlation"

DXA81CSO111I "Calling into SSO event handler"

DXA81CSO112I "Returning from SSO event handler"

User Service

DXA81CUS105I "User successfully added"

DXA81CUS108I "User successfully modified"

DXA81CUS205E "User cannot be added"

DXA81CUS208E "User cannot be modified"

DXA81CUS221E "OrganizationalUnit cannot be read"

DXA81CUS222E "OrganizationalUnits cannot be listed"

DXA81CUS223E "User cannot be read"

DXA81CUS224E "Users cannot be listed"

DXA81CUS225E "Group cannot be read"

DXA81CUS226E "Groups cannot be listed"
Audit Externalization Plug-in

The plug-in class that allows for pushing audit events into external sinks needs to be configured on the basis of its fully-qualified class name. This configuration setting is provided on the level of a Cluster configuration object. For migration reasons, the default Log4J provider (com.siemens.dxa.common.audit.sink.impl.log4j.Log4JAuditCalloutHandler) is used if this configuration setting is omitted.

Auditing Semantics

This section describes the semantics of selected audit events.

Authentication Process

The authentication process may issue the audit messages at two different stages:

  • Success: If the authentication succeeds, this event is propagated via an audit message with an appropriate code. This code is the same for both initial and re-authentication and carries information about the type of used authentication method.

  • Failure: If the authentication fails, this event is propagated via an audit message with an appropriate code. This code carries information about the type of used authentication method.

Auditing of a single-step authentication method is straightforward. Authentication credentials are sent by an entity, verified by the server and an appropriate message (success or failure) is issued.

Auditing of a multiple-step authentication method is a more complex process with the following properties:

  • The final step (when the server does not need to issue any other challenge) follows the rules of the single-step authentication.

  • The multiple-step authentication process as a whole issues exactly one authentication audit event (success or failure) – intermediary steps aren’t audited.

attachments/att++_++9++_++for++_++110526498
Figure 1. Authentication Auditing Flow

Composite Authentication Method

The composite authentication method consists of several standalone authentication methods combined into one. Either the method succeeds as a whole and a new SSO session is created (or an existing one updated) or fails as a whole and no session is created (or any existing updated). The intermediary methods used in the authentication process don’t issue audit messages.

The audit message related to the composite authentication method includes the information about all the intermediary methods used. The content of this information is equal to the content of the audit event of the same method used in a standalone mode. To be able to transfer this content, the audit event object issued by the composite authentication method implements the CompositeAuthnEvent (implementing AuthnEvent) interface which introduces a list of AuthnStep objects that describe the respective authentication method used.