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