keycloak-uncached

Added doc for audit

5/27/2014 9:40:23 AM

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