Transferring security events to file or Kafka#

In Blitz Identity Provider, you can configure the logging of security events to one or more receivers. The configuration is set in the blitz.prod.local.idp.audit configuration block.

The following settings must be configured:

emitters - defines the list of receivers of audit records. For each receiver the settings block is filled in:
- type - receiver type. Possible values:
  - audit-store - the record is made in the DBMS;
  - log - the record is made to the logger with the name logback.
- enabled - optional setting - determines whether the receiver is enabled or not;
- include - optional setting - lists the types of security events (see the table below), which are used to write to the receiver. If the setting is not specified, all security events are written;
- exclude - optional setting - lists the types of security events (see table below) that should not be written to the receiver. If the setting is not specified, no events are excluded. If the setting is specified together with include, the list of events is first defined by the include setting, and then the events specified in exclude are excluded from it. It is recommended not to use both include and exclude settings together, but to use only one of them;
- logger - optional setting - specified only for the receiver with log type. Allows you to define the name of the logger. If the setting is not specified, the recording is made to the logger with the name AUDIT;
- name - optional setting - specified for receivers with types log and kafka. Specifies the name of the receiver, since multiple receivers can be configured for these receiver types. If the setting is not specified, log and kafka are used as receiver names;
- bootstrapServers - a mandatory setting for a receiver with type kafka - specifies a list of addresses for initial connection to the Kafka cluster;
- topic - mandatory setting for receiver with type kafka - the name of the Kafka topic to which the event should be sent;
- securityProtocol - optional setting for receiver with type kafka - in case of using SASL connection may not be specified. In case of connection via SSL, the value SSL must be specified in the setting. If TLS is not configured in Kafka, the value SASL_PLAINTEXT must be specified;
- sasl - optional configuration block for receiver with type kafka - specifies connection parameters when using SASL authentication to connect to Kafka:
  - jaasConfig is a connection string that can use the substitution parameters from secureParams;
  - mechanism is the value of PLAIN;
  - secureParams - block with parameters that will be encrypted in the configuration file when the server is started.
Block example:
```
"sasl": {
    "jaasConfig": "org.apache.kafka.common.security.plain.PlainLoginModule required username=\"alice\" password=\"${pswd}\";",
    "mechanism": "PLAIN",
    "secureParams": {
        "pswd": "Content will be encrypted at startup",
    }
}
```
- ssl - optional configuration block for receiver with type kafka - sets SSL parameters for connection to Kafka:
  - enabledProtocols - lines with the list of enabled protocols;
  - keyStore is a settings block with parameters for accessing Blitz Identity Provider key container. It contains type, path, password settings;
  - trustedStore - settings block with parameters of access to the container with trusted certificates. It contains type, path, password settings;
  - keyPassword - optional setting - the password to access the key.
Block example:
```
"securityProtocol" : "SSL",
"ssl" : {
    "enabledProtocols" : ["TLSv1.2,TLSv1.3"],
    "keyStore" : {
        "password" : "CHANGE-ME",
        "path" : "/etc/blitz-config/bip-d1app01-1.jks",
        "type" : "JKS"
    },
    "trustedStore" : {
        "password" : "CHANGE-ME",
        "path" : "/etc/blitz-config/ca.jks",
        "type" : "JKS"
    },
    "keyPassword": "CHANGE-ME"
},
```
- tuning - optional settings block for a receiver with type kafka - specifies optional producer settings for interaction with Kafka. Parameter names must be specified with a dot as in the Kafka documentation.
Block example:
```
"tuning": {
    "client.id": "BlitzKafka"
}
```
- emitAtLeastOneOf - optional setting - the list of receivers is specified, it is enough to record events in any of them for the operation to be considered successful;
- emitToAllOf - optional setting - specifies the list of receivers that must receive confirmation of successful event recording for the operation to be considered successful. If the emitAtLeastOneOf and emitToAllOf settings are not specified, then confirmation from all configured receivers is mandatory;
- emitTimeoutInSec - optional setting - defines the maximum response time from the receiver in response to event record requests. If the setting is not specified, the wait is 60 seconds.
Example of audit recording settings in log, DBMS and Kafka at the same time:
```
"audit": {
    "emitters": [
        {
            "type": "log",
            "name": "users-log",
            "enabled": true,
            "logger": "AUDIT",
            "exclude": ["admin_added", "admin_pswd_changed", "admin_removed", "admin_roles_changed",
                        "config_changed"]
        },
        {
            "type": "log",
            "name": "admins-log",
            "enabled": true,
            "logger": "AUDITADMIN",
            "include": ["admin_added", "admin_pswd_changed", "admin_removed", "admin_roles_changed",
                        "config_changed"]
        },
        {
            "type": "audit-store",
            "enabled": true
        },
        {
            "type" : "kafka",
            "enabled": true,
            "name" : "kafka",
            "include": ["login"],
            "bootstrapServers" : ["infra-kfk01:9443"],
            "topic" : "blitz_audit",
            "securityProtocol" : "SSL",
            "ssl" : {
                "enabledProtocols" : ["TLSv1.2,TLSv1.3"],
                "keyStore" : {
                    "password" : "CHANGE-ME",
                    "path" : "/etc/blitz-config/bip-app01.jks",
                    "type" : "JKS"
                },
                "trustedStore" : {
                    "password" : "CHANGE-ME",
                    "path" : "/etc/blitz-config/ca.jks",
                    "type" : "JKS"
                }
            },
        }
    ],
    "emitAtLeastOneOf": ["users-log","admins-log","kafka"],
    "emitToAllOf": ["audit-store"],
    "emitTimeoutInSec": 30
}
```

When logging an audit to the logger, you can configure the logger using the logback.xml configuration file (see for more information <https://logback.qos.ch/documentation.html>`__). Example of configuring the ``AUDIT logger in the logback.xml configuration file:

…
    <appender name="AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${dir.logs}/audit-${app.name}.log</file>
        <encoder>
            <pattern>%date - [%level] -[%file:%line] - %message%n%xException{20}</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${dir.logs}/archive/audit-${app.name}.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>90</maxHistory>
            <totalSizeCap>5GB</totalSizeCap>
        </rollingPolicy>
    </appender>

    <logger name="AUDIT" additivity="false">
        <appender-ref ref="AUDIT" />
    </logger>
…

Example of a log entry:

2023-11-20 13:29:47,170 - [INFO] -[LoggerEventEmitterDriver.scala:37] - {"ip_st":"Tashkent","ip":"213.230.116.179","authnDone":"true","process_id":"b80ca03e-4718-44ff-9456-7d4255610eaa","ip_ctr":"Узбекистан","type":"login","object_id":"BIP-123456","protocol":"oAuth","subject_id":"BIP-123456","auth_methods":"cls:password","session_id":"f8d85ba2-a26a-447f-b82e-944b9218abb8","timestamp":1700476187069,"ch_platform_version":"\"14.1.0\"","ch_platform":"\"macOS\"","ip_ct":"Tashkent","id_store":"ldap01","ip_lng":"69.2494","ip_rad":"5","ch_ua":"\"Google Chrome\";v=\"119\", \"Chromium\";v=\"119\", \"Not?A_Brand\";v=\"24\"","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36","lp_id":"test-system","id":"6056828858453673-600312119","ip_lat":"41.3171","client_auth_method":"redirectUri"}

The set of record attributes may vary depending on the type of security event and the specifics of the login process. Attribute assignments in the audit record are shown in the table below:

Assigning attributes to an audit record

Attribute	Purpose and possible meanings
`id`	Security event log entry identifier
`type`	Security Event Type: `admin_added` - administrator added `admin_pswd_changed` - administrator password changed `admin_removed` - administrator removed `admin_roles_changed` - administrator roles changed `app_password_changed` - the password for the application is set `attribute_changed` - attribute added, changed or deleted `attribute_confirmed` - attribute confirmed `auth` - authentication performed (with OAuth 2.0 Resource Owner Password Credentials) `auth_failed` - authentication error `auth_req` - authentication request `authz_granted` - OAuth authorization issued `authz_rejected` - OAuth authorization denied `authz_revoked` - OAuth authorization revoked `bind_ext_account` - account is bound to an external account `config_changed` - changed configuration settings `duo_put` - Duo Mobile app is bound `duo_remove` - Duo Mobile application is unbound `grant_right` - assigning access rights `group_attr_changed` - user group’s attribute has been changed or deleted `group_registered` - user group created `group_removed` - user group deleted `hotp_attached` - HOTP generator is bound `hotp_detached` - HOTP generator is unbound `internal_user_deleted` - account deleted `locked_methods_changed` - changed the list of blocked authentication methods `login` - login is performed `login_failed` - login error `login_stopped` - unsuccessful login `logout` - user is logged out `logout_req` - logout request `member_added` - the user is joined to the user group `member_removed` - user excluded from the user group `needed_password_change` - flag of password change necessity is set `recovery` - account access restored `recovery_fail` - access recovery failed `recovery_req` - access recovery is request `registration` - account is registered `registration_req` - registration is request `required_factor_changed` - changed user authentication mode `reset_user_password` - password set by administrator `reset_user_sessions` – log out devices (reset sessions) `revoke_right` - revoke access rights `send_email_code` - confirmation code sent to email `send_push_code` - confirmation code sent to Push `send_sms_code` - confirmation code sent by SMS `token_exchange_failed` - access token exchange denied `token_exchanged` - access token has been exchanged `token_granted` - access token issued `totp_attached` - TOTP generator is bound `totp_detached` - TOTP generator is unbound `unbind_ext_account` - account is unbound from external account `user_locked` - account locked `user_password_changed` - user password changed `user_sec_qsn_changed` – security question changed `user_sec_qsn_removed` – security question removed `user_unlocked` - account unlocked `web_authn_reg_key` - security key added `web_authn_revoke_key` - security key removed
`alt_pswd_cause`	The reason why the user was asked to change the password. Possible values: `password_expired` - password expired `password_reset` - password should be changed at the first login `password_policy_violated` - password does not comply with password policy
`attr_name`	Installed, deleted or modified attribute name
`auth_methods`	Contains a list of authentication methods passed by the user. Possible values: `password` - password authentication `spnego` - login using an OS session `x.509` - login with electronic signature tool `qrCode` - login by QR code `tls` – login using HTTP headers of the proxy server `webAuthn` - login or login confirmation with security keys `css` - automatic login based on the results of user registration or password recovery `sms` - one-time password by SMS `email` - one-time email password `hotp` - second factor of authentication with hardware key fob `totp` is the second factor of authentication using the software TOTP confirmation code generator `externalIdps:<type>:<name>` - login using an external identity provider (social networks etc.) `userApp` - secondary authentication in the mobile application `outside_%NAME%` - external logging in method named %NAME% The presence of the prefix `cls:` before the method means that the login was performed using a long-term session, and that the primary login previously used those login methods listed after `cls:`
`auth_soft_id`	Authenticator application (when logging in by QR code)
`authnDone`	Whether authentication was performed at this login
`captcha_passed`	An indication that a CAPTCHA was asked when logging in
`client_auth_method`	A method for authenticating the application that invoked Blitz Identity Provider applications: `internal` - for events invoked by internal Blitz Identity Provider applications `x.509` - for events triggered by SAML applications, provided that the SAML request came signed `Basic` - for applications calling REST services that use Basic authorization `redirectUri` - for applications that have identified themselves in the URL (e.g., specified their client_id in the URL parameter), but whose authentication has not been performed (it is not reliably known that this is actually calling Blitz Identity Provider for this particular application) `Bearer` - using access_token for authentication by mobile app with dynamic client_id/client_secret
`dcId`	Dynamic `client_id`
`device`	device ID
`deviceFingerprint`	Device imprint
`dTyp`	Device type (for dynamic registration)
`email`	E-mail address
`entry_point`	The type of interface used to register the user: `WEB` - when registering from Blitz Identity Provider web application, `REST` - when registering via Blitz Identity Provider REST services.
`error`	Error (for unsuccessful events)
`ext_account_id`	External account ID
`ext_account_name`	Name of the external identity provider
`ext_account_type`	Type of External Identity Provider
`failed_method`	Indicates which authentication method the user was unable to pass
`group_id`	User group identifier
`group_profile`	User Group Usage Profile Identifier
`id_store`	User profile storage
`ip`	user IP address
`ip_ctr`	Country according to IP address
`ip_st`	Region according to IP address
`ip_ct`	City according to IP address
`ip_lat`	Latitude according to IP address
`ip_lng`	Longitude according to IP address
`ip_rad`	Surrounding by IP address
`lp_id`	The identifier of the application (`EntityId` for SAML or `client_id` for OIDC) that invoked Blitz Identity Provider.
`mobile`	Mobile phone number
`module`	Identifier of the modified setting block
`new_attr_value`	New value of the installed or modified attribute
`new_factor`	New value of the attribute indicating the necessity to verify the second authentication factor
`new_roles`	Roles added to the administrator account
`oauth_scopes`	List of authorizations granted or revoked by the user
`object_id`	Identifier of the operation object (user for which the operation was performed)
`old_attr_value`	Previous value of the deleted or modified attribute
`old_factor`	Previous value of the attribute indicating the need to verify the second authentication factor
`old_roles`	Roles revoked from the administrator account
`origin_app`	Identifier of the application that initiated user registration or password recovery
`process_id`	Process ID
`protocol`	The protocol for the application to communicate with Blitz Identity Provider. Possible values: `SAML` - for SAML and WS-Federation `OAuth` - for OpenID Connect and OAuth 2.0 `simple` - for proxy authentication- `internal` - to log in to the User Profile (`_blitz_profile`)
`pswd_changed`	An indication that a password change was recommended
`pswd_tmp_locked`	An indication that there was a temporary lockdown
`recovery_contact`	The contact (email or cell phone number) specified during recovery
`recovery_type`	Password recovery type: `email` or `mobile`
`right_name`	Name of access right
`roles`	Administrator account roles
`session_id`	Unique identifier of the user session. Allows you to correlate all user events performed by the user within a common user session
`subject_id`	Identifier of the subject of the operation (the user who invoked the operation)
`tags`	Tag of assigned or revoked access right
`timestamp`	The date and time of the event. For example, `2022-11-04T17:49:58.384+0300`
`tried_old_pswd`	An indication that a login attempt was made with a password from the saved password history (previous password)
`used_login`	Login used at sign in
`user_agent`	User device data (`UserAgent`)
`wa_key_id`	Security key identifier
`wa_key_name`	Security key name
`withDelay`	Entry delay was enabled