keycloak-uncached
Changes
docbook/reference/en/en-US/modules/audit.xml 104(+104 -0)
Details
diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index e3b1659..b8469c3 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -22,6 +22,7 @@
<!ENTITY Roles SYSTEM "modules/roles.xml">
<!ENTITY CORS SYSTEM "modules/cors.xml">
<!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
+ <!ENTITY Audit SYSTEM "modules/audit.xml">
]>
<book>
@@ -101,6 +102,7 @@ This one is short
&Roles;
&CORS;
&Timeouts;
+ &Audit;
&Migration;
</book>
docbook/reference/en/en-US/modules/audit.xml 104(+104 -0)
diff --git a/docbook/reference/en/en-US/modules/audit.xml b/docbook/reference/en/en-US/modules/audit.xml
new file mode 100755
index 0000000..0136a91
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/audit.xml
@@ -0,0 +1,104 @@
+<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>
\ No newline at end of file