104 lines
5.3 KiB
XML
104 lines
5.3 KiB
XML
|
<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>
|