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

  • 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"}

Possible types of security events:

• 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

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