keycloak-uncached
Changes
docbook/reference/en/en-US/modules/ldap.xml 12(+12 -0)
Details
diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index b8469c3..0eca23e 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -23,6 +23,9 @@
<!ENTITY CORS SYSTEM "modules/cors.xml">
<!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
<!ENTITY Audit SYSTEM "modules/audit.xml">
+ <!ENTITY Authentication SYSTEM "modules/authentication-spi.xml">
+ <!ENTITY Ldap SYSTEM "modules/ldap.xml">
+ <!ENTITY ExportImport SYSTEM "modules/export-import.xml">
]>
<book>
@@ -103,6 +106,9 @@ This one is short
&CORS;
&Timeouts;
&Audit;
+ &Authentication;
+ &Ldap;
+ &ExportImport;
&Migration;
</book>
diff --git a/docbook/reference/en/en-US/modules/authentication-spi.xml b/docbook/reference/en/en-US/modules/authentication-spi.xml
new file mode 100644
index 0000000..c19dffa
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/authentication-spi.xml
@@ -0,0 +1,66 @@
+<chapter id="authentication-spi">
+ <title>Authentication SPI</title>
+ <para>
+ Keycloak provides Authentication SPI, which allows to choose the <literal>AuthenticationProvider</literal> for authenticating users.
+ AuthenticationProvider is the interface, which states how will be your usernames/passwords validated. You can choose from
+ the set of available AuthenticationProviders or you can even implement and plug your own AuthenticationProvider, which
+ will allow to provide your own way how will Keycloak validates users and their passwords.
+ </para>
+ <section id="authentication-available-providers">
+ <title>Available Authentication Providers</title>
+ <para>
+ <itemizedlist>
+ <listitem><literal>Model</literal> - This provider validates users and their passwords based on the Keycloak model. So it just delegates
+ to model implementation provided either by RDBMS or Mongo at this moment. This is default AuthenticationProvider,
+ which is configured for <literal>keycloak-admin</literal> realm by default and it's also automatically configured for newly created realms.
+ </listitem>
+ <listitem><literal>External-model</literal> - This provider also uses Keycloak model, but it uses different realm to validate your users against.
+ For example if you want to create new realm "foo" and you want all users of already existing realm "bar" that they are automatically
+ able to login into realm "foo" with their usernames and passwords, you can choose this provider.
+ </listitem>
+ <listitem><literal>Picketlink</literal> - This provider delegates Authentication to <ulink url="http://docs.jboss.org/picketlink/2/latest/reference/html-single/#chap-Identity_Management_-_Overview">Picketlink IDM</ulink>
+ framework. Right now, Picketlink IDM in Keycloak is configured to always use LDAP based Identity store, which means that picketlink provider
+ allows you to authenticate your users against LDAP server. Note that you will first need to configure LDAP server as described
+ <link linkend="ldap">here</link> . <literal>PicketlinkAuthenticationProvider</literal> configured for the realm will automatically use LDAP configuration for this realm.
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="authentication-features">
+ <title>Features and configuration</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ You can configure AuthenticationProviders separately for each realm. So for example you can choose that just realm
+ "foo" will use <literal>PicketlinkAuthenticationProvider</literal> and authenticate users against LDAP but realm "keycloak-admin" will still use default <literal>ModelAuthenticationProvider</literal>.
+ </listitem>
+ <listitem>
+ There is also possibility to choose more authentication providers for the realm, which actually means that Keycloak
+ will use first available AuthenticationProvider and just in case that user doesn't exist here,
+ it will fallback to second AuthenticationProvider in chain. So this may allow for example scenario, in which
+ you authenticate user against Keycloak database (model) and just if he doesn't exist in database, it will fallback to LDAP (picketlink).
+ </listitem>
+ <listitem>
+ You can configure for each AuthenticationProvider if you want to update passwords - option <literal>passwordUpdateSupported</literal>.
+ This means that when user update password or his profile through Keycloak UI, this change will be propagated into AuthenticationProvider.
+ So for example password in LDAP will be updated if it's <literal>true</literal>, but for read-only LDAP, you will likely switch it to <literal>false</literal>.
+ It also means that newly registered users will be propagated to particular AuthenticationProvider too,
+ but note that each user is always bind just to one AuthenticationProvider.
+ </listitem>
+ <listitem>
+ You can add/edit/remove AuthenticationProviders in the <literal>Authentication</literal> tab in admin console, which is under URL
+ <ulink url="http://localhost:8080/auth/admin/keycloak-admin/console/#/realms/YOUR_REALM/auth-settings">http://localhost:8080/auth/admin/keycloak-admin/console/#/realms/YOUR_REALM/auth-settings</ulink>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </section>
+ <section id="authentication-new-provider">
+ <title>Creating your own Authentication Provider</title>
+ <para>
+ You need to implement interface AuthenticationProvider and add the name of your AuthenticationProviderFactory class into
+ <literal>META-INF/services/org.keycloak.authentication.AuthenticationProviderFactory</literal> file inside your JAR with AuthenticationProvider. You also need to copy this JAR into
+ <literal>standalone/deployments/auth-server.war/WEB-INF/lib</literal> . The best is to look at <ulink url="https://github.com/keycloak/keycloak/tree/master/examples/providers/authentication-properties">example</ulink> and try it out.
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/docbook/reference/en/en-US/modules/export-import.xml b/docbook/reference/en/en-US/modules/export-import.xml
new file mode 100644
index 0000000..534ee80
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/export-import.xml
@@ -0,0 +1,31 @@
+<chapter id="export-import">
+ <title>Export and Import</title>
+ <para>
+ Export/import is useful especially if you want to migrate your whole Keycloak database from one environment to another or migrate to different database (For example from MySQL to Oracle).
+ You can trigger export/import at startup of Keycloak server and it's configurable with System properties right now. The fact it's done at server startup means that no-one can access Keycloak UI or REST endpoints
+ and edit Keycloak database on the fly when export or import is in progress. Otherwise it could lead to inconsistent results.
+ </para>
+ <para>
+ You can export/import your database either to directory on local filesystem (useful just for testing purposes or if your filesystem is properly protected)
+ or to encrypted ZIP file on local filesystem. Encrypted ZIP is recommended as export contains many sensitive informations like passwords of your users (even if they are hashed),
+ but also their email addresses, and especially private keys of the realms.
+ </para>
+ <para>
+ So to export the content of your Keycloak database into encrypted ZIP, you can execute Keycloak server with the System properties like:
+ <programlisting><![CDATA[
+bin/standalone.sh -Dkeycloak.migration.action=export
+-Dkeycloak.migration.provider=zip -Dkeycloak.migration.zipFile=<FILE TO EXPORT TO>
+-Dkeycloak.migration.zipPassword=<PASSWORD TO DECRYPT EXPORT>
+]]></programlisting>
+ Then you can move or copy the encrypted ZIP file into second environment and you can trigger import from it into Keycloak server with the same command but use
+ <literal>-Dkeycloak.migration.action=import</literal> instead of <literal>export</literal> .
+ </para>
+ <para>
+ To export into unencrypted directory you can use:
+ <programlisting><![CDATA[
+bin/standalone.sh -Dkeycloak.migration.action=export
+-Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>
+]]></programlisting>
+ And similarly for import just use <literal>-Dkeycloak.migration.action=import</literal> instead of <literal>export</literal> .
+ </para>
+</chapter>
\ No newline at end of file
docbook/reference/en/en-US/modules/ldap.xml 12(+12 -0)
diff --git a/docbook/reference/en/en-US/modules/ldap.xml b/docbook/reference/en/en-US/modules/ldap.xml
new file mode 100644
index 0000000..dd7d4ab
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/ldap.xml
@@ -0,0 +1,12 @@
+<chapter id="ldap">
+ <title>LDAP Integration</title>
+ <para>
+ Right now, LDAP server is configured separately for each Realm. Configuration is in admin console in tab <literal>Ldap</literal>
+ under realm settings. It's under URL like <ulink url="http://localhost:8080/auth/admin/keycloak-admin/console/index.html#/realms/YOUR_REALM/ldap-settings">http://localhost:8080/auth/admin/keycloak-admin/console/index.html#/realms/YOUR_REALM/ldap-settings</ulink> .
+ There is nothing like "shared" LDAP server for more realms in Keycloak, but it's planned for the future.
+ </para>
+ <para>
+ LDAP is currently used just for authentication of users done through <literal>PicketlinkAuthenticationProvider</literal> as described <link linkend="authentication-available-providers">here</link> .
+ In the future, we have plan to have full Sync SPI, which will allow one-way or two-way synchronization between LDAP server and Keycloak database including users and roles.
+ </para>
+</chapter>
\ No newline at end of file