<chapter id="audit">
    <title>Audit</title>
    <para>
        Keycloak provides an Audit SPI that makes it possible to register listeners for events in the system. There are two
        interfaces that can be implemented, the first is a pure listener, the second is a provider which listens for events
        as well as providing a query over persisted events. If a realm has a audit provider registered it's possible to
        view events for the realm through the admin console and account management.
    </para>
    <section>
        <title>Events</title>
        <para>
            Login events:
            <itemizedlist>
                <listitem>Login - A user has logged in</listitem>
                <listitem>Register - A user has registered</listitem>
                <listitem>Logout - A user has logged out</listitem>
                <listitem>Code to Token - An application/client has exchanged a code for a token</listitem>
                <listitem>Refresh Token - An application/client has refreshed a token</listitem>
            </itemizedlist>
        </para>
        <para>
            Account events
            <itemizedlist>
                <listitem>Social Link - An account has been linked to a social provider</listitem>
                <listitem>Remove Social Link - A social provider has been removed from an account</listitem>
                <listitem>Update Email - The email address for an account has changed</listitem>
                <listitem>Update Profile - The profile for an account has changed</listitem>
                <listitem>Send Password Reset - A password reset email has been sent</listitem>
                <listitem>Update Password - The password for an account has changed</listitem>
                <listitem>Update TOTP - The TOTP settings for an account has changed</listitem>
                <listitem>Remove TOTP - TOTP has been removed from an account</listitem>
                <listitem>Send Verify Email - A email verification email has been sent</listitem>
                <listitem>Verify Email - The email address for an account has been verified</listitem>
            </itemizedlist>
        </para>
        <para>
            For all events there is a corresponding error event.
        </para>
    </section>
    <section>
        <title>Audit Listener</title>
        <para>
            Keycloak comes with an Email Audit Listener and a JBogg Logging Audit Listener. The Email Audit Listener
            sends an email to the users account when an event occurs. The JBoss Logging Audit Listener writes to a log
            file when an events occurs.
        </para>
        <para>
            The Email Audit Listener only supports the following events at the moment:
            <itemizedlist>
                <listitem>Login Error</listitem>
                <listitem>Update Password</listitem>
                <listitem>Update TOTP</listitem>
                <listitem>Remove TOTP</listitem>
            </itemizedlist>
            You can exclude one or more events by editing <literal>standalone/configuration/keycloak-server.json</literal>
            and adding for example:
<programlisting><![CDATA[
"audit-listener": {
    "email": {
        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
    }
}
]]></programlisting>
        </para>
    </section>

    <section>
        <title>Audit Provider</title>
        <para>
            Audit Providers listen for events and is expected to persist the events to make it possible to query for them
            later. This is used by the admin console and account management to view events. Keycloak includes providers
            to persist audit events to JPA and Mongo. For production you will most likely want to use a separate database
            for audit events. You may even want to use a RDBMS for your model, and Mongo for your audit.
        </para>
        <para>
            You can specify events to include or exclude by editing <literal>standalone/configuration/keycloak-server.json</literal>,
        and adding for example:
<programlisting><![CDATA[
"audit": {
    "jpa": {
        "exclude-events": [ "LOGIN", "REFRESH_TOKEN", "CODE_TO_TOKEN" ]
    }
}
]]></programlisting>
        </para>
    </section>

    <section>
        <title>Configure Audit Settings for Realm</title>
        <para>
            To enable audit for a realm you firstly need to make sure you have a audit provider registered for Keycloak.
            By default the JPA audit provider is registered. Once you've done that open the admin console, select the
            realm you're configuring, select <literal>Audit</literal>. Then click on <literal>Config</literal>.
            You can enable audit for your realm by toggling <literal>Enabled</literal> to ON. You can also set
            an expiration on audit events. This will deleted events from the database that are older than the specified
            time.
        </para>
        <para>
            To configure listeners for a realm on the same page as above add one or more audit listeners to the <literal>
            Audit Listeners</literal> select box. This will allow you to enable any registered Audit Listeners with the
            realm.
        </para>
    </section>
</chapter>