mariusz.pacek/keycloak
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc merge

Browse Source
This commit is contained in:
Bill Burke committed 2014-05-28 09:33:42 -04:00
2 parents e880b77692 e8fe26ff1c
commit a64b35d72f
53 files changed
+1189 -173
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docbook/reference/en/en-US/master.xml
+8
View File
@@ -23,6 +23,10 @@
<!ENTITY Roles SYSTEM "modules/roles.xml">
<!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 +107,10 @@ This one is short
&Roles;
&CORS;
&Timeouts;
&Audit;
&Authentication;
&Ldap;
&ExportImport;
&Migration;
</book>
docbook/reference/en/en-US/modules/MigrationFromOlderVersions.xml
+15
View File
@@ -3,10 +3,25 @@
<sect1>
<title>Migrating from 1.0 Alpha 4 to Beta 1</title>
<itemizedlist>
<listitem>
DB Schema has changed. We have added export of the database to Beta 1, but not the ability to import
the database from older versions. This will be supported in future releases.
</listitem>
<listitem>
For all clients except bearer-only applications, you must specify at least one redirect uri. Keycloak
will not allow you to log in unless you have specified a valid redirect uri for that application.
</listitem>
<listitem>
Resource Owner Password Credentials flow is now disabled by default. It can be enabled by setting the toggle
for <literal>Direct Grant API</literal> <literal>ON</literal> under realm config in the admin console.
</listitem>
<listitem>
Configuration is now done through <literal>standalone/configuration/keycloak-server.json</literal>. This
should mainly affect those that use MongoDB.
</listitem>
<listitem>
JavaScript adapter has been refactored. See the <link linkend='javascript-adapter'>JavaScript adapter</link> section for more details.
</listitem>
</itemizedlist>
</sect1>
<sect1>
docbook/reference/en/en-US/modules/audit.xml
Executable
+104
View File
@@ -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>
docbook/reference/en/en-US/modules/authentication-spi.xml
+66
View File
@@ -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>
docbook/reference/en/en-US/modules/export-import.xml
+31
View File
@@ -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>
docbook/reference/en/en-US/modules/javascript-adapter.xml
+1 -1
View File
@@ -1,4 +1,4 @@
<section>
<section id="javascript-adapter">
<title>Pure Client Javascript Adapter</title>
<para>
The Keycloak Server comes with a Javascript library you can use to secure pure HTML/Javascript applications. It
docbook/reference/en/en-US/modules/ldap.xml
+12
View File
@@ -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>
docbook/reference/en/en-US/modules/openshift.xml
+2 -2
View File
@@ -27,7 +27,7 @@
Scroll down to the bottom of the page to find the
<literal>Code Anything</literal>
section. Insert
<literal>https://raw.github.com/keycloak/openshift-keycloak-cartridge/master/metadata/manifest.yml</literal>
<literal>http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge</literal>
into the
<literal>URL to a cartridge definition</literal>
field and click on <literal>Next</literal>. Fill in the
@@ -44,7 +44,7 @@
<title>Create Keycloak instance with the command-line tool</title>
<para>
Run the following command from a terminal:
<programlisting>rhc app create &lt;APPLICATION NAME&gt; https://raw.github.com/keycloak/openshift-keycloak-cartridge/master/metadata/manifest.yml</programlisting>
<programlisting>rhc app create &lt;APPLICATION NAME&gt; http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge</programlisting>
Replace <literal>&lt;APPLICATION NAME&gt;</literal> with the name you want (for example keycloak).
</para>
<para>
docbook/reference/en/en-US/modules/server-installation.xml
+55 -15
View File
@@ -37,8 +37,10 @@ keycloak-appliance-dist-all-1.0-beta-1-SNAPSHOT/
standalone.sh
standalone.bat
standalone/deployments/
auth-server.war/
auth-server.war/
standalone/configuration/
keycloak-server.json
themes/
adapters/
keycloak-as7-adapter-dist-1.0-beta-1-SNAPSHOT.zip
keycloak-eap6-adapter-dist-1.0-beta-1-SNAPSHOT.zip
@@ -81,6 +83,9 @@ keycloak-war-dist-all-1.0-beta-1-SNAPSHOT/
deployments/
auth-server.war/
keycloak-ds.xml
configuration/
keycloak-server.json
themes/
adapters/
keycloak-as7-adapter-dist-1.0-beta-1-SNAPSHOT.zip
keycloak-eap6-adapter-dist-1.0-beta-1-SNAPSHOT.zip
@@ -90,8 +95,9 @@ keycloak-war-dist-all-1.0-beta-1-SNAPSHOT/
</programlisting>
</para>
<para>
After unzipping this file, copy the <literal>deployments/</literal> directory into to the <literal>standalone/</literal>
of your JBoss or Wildfly distro.
After unzipping this file, copy everything in <literal>deployments</literal> directory into the
<literal>standalone/deployments</literal> of your JBoss or Wildfly distro. Also, copy everything in
<literal>configuration</literal> directory into the <literal>standalone/configuration</literal> directory.
</para>
<para>
<programlisting>
@@ -248,20 +254,53 @@ keycloak-war-dist-all-1.0-beta-1-SNAPSHOT/
<title>MongoDB based model</title>
<para>
Keycloak provides <ulink url="http://www.mongodb.com">MongoDB</ulink> based model implementation, which means that your identity data will be saved
in MongoDB instead of traditional RDBMS. To setup it, you need to add few system properties when running Keycloak.
First you need to specify that you want to use <literal>mongo</literal> instead of default <literal>jpa</literal> model, and you may also specify
host, port and name of mongo database. So you can start keycloak with the command like this:
in MongoDB instead of traditional RDBMS. To configure Keycloak to use Mongo open <literal>standalone/configuration/keycloak-server.json</literal>
in your favourite editor, then change:
<programlisting><![CDATA[
./standalone.sh -Dkeycloak.model=mongo -Dkeycloak.model.mongo.host=localhost
-Dkeycloak.model.mongoport=27017 -Dkeycloak.model.mongo.db=keycloak
"audit": {
"provider": "jpa",
"jpa": {
"exclude-events": [ "REFRESH_TOKEN" ]
}
},
"model": {
"provider": "jpa"
},
]]></programlisting>
Note that when you install MongoDB on your laptop, it's usually on localhost/270717 by default. That's why properties
<literal>keycloak.model.mongo.host</literal> and <literal>keycloak.model.mongo.port</literal> are not mandatory, but they already have
default values <literal>localhost</literal> and <literal>27017</literal> . Similarly property <literal>keycloak.model.mongo.db</literal>
has default value <literal>keycloak</literal> for name of underlying database. So the example above could be simplified like:
<programlisting><![CDATA[
./standalone.sh -Dkeycloak.model=mongo
to:
<programlisting><![CDATA[
"audit": {
"provider": "mongo",
"mongo": {
"exclude-events": [ "REFRESH_TOKEN" ],
"host": "<hostname>",
"port": <port>,
"user": "<user>",
"password": "<password>",
"db": "<db name>"
}
},
"model": {
"provider": "mongo",
"mongo": {
"host": "<hostname>",
"port": <port>,
"user": "<user>",
"password": "<password>",
"db": "<db name>"
}
},
]]></programlisting>
All configuration options are optional. Default values for host and port are localhost and 27017. If
user and password are not specified Keycloak will connect unauthenticated to your MongoDB. Finally, default
values for db are keycloak for the model, and keycloak-audit for audit.
If you switch to Mongo model, it could be a good idea to remove RDBMS related stuff from your distribution to reduce startup time and memory footprint.
To do it, you need to:
<itemizedlist>
@@ -270,6 +309,7 @@ keycloak-war-dist-all-1.0-beta-1-SNAPSHOT/
</itemizedlist>
</para>
</section>
<section>
<title>AS7/EAP6.x Logging</title>
<para>
docbook/reference/en/en-US/modules/themes.xml
+24 -23
View File
@@ -16,11 +16,30 @@
</para>
</section>
<section>
<title>Default themes</title>
<para>
Keycloak comes bundled with default themes in <literal>standalone/configuration/themes</literal>. It is
not recommended to edit these themes directly. Instead you should create a new theme to extend a default
theme. A good reference is to copy the keycloak themes as these extend the base theme to add styling.
</para>
</section>
<section>
<title>Creating a theme</title>
<para>
There are two types of themes in Keycloak, <literal>login</literal> and <literal>account</literal>. Login themes are used to customize the
login forms, while account themes are used to customize account management. A theme consists of:
There are several types of themes in Keycloak:
<itemizedlist>
<listitem>Account - Account management</listitem>
<listitem>Admin - Admin console</listitem>
<listitem>Common - Shared resources for themes</listitem>
<listitem>Email - Emails</listitem>
<listitem>Login - Login forms</listitem>
</itemizedlist>
</para>
<para>
A theme consists of:
<itemizedlist>
<listitem><para><ulink url="http://freemarker.org">FreeMarker</ulink> templates</para></listitem>
<listitem><para>Stylesheets</para></listitem>
@@ -37,9 +56,9 @@
templates.
</para>
<para>
To create a new theme, create a folder in <literal>.../standalone/configuration/themes/login</literal> or
<literal>.../standalone/configuration/themes/account</literal>. The name of the folder is the name of the theme.
Then create a file <literal>theme.properties</literal> inside the theme folder. The contents of the file should be:
To create a new theme, create a folder in <literal>.../standalone/configuration/themes/&lt; theme type&gt;</literal>.
The name of the folder is the name of the theme. Then create a file <literal>theme.properties</literal> inside the theme folder.
The contents of the file should be:
</para>
<programlisting>parent=base</programlisting>
<para>
@@ -104,24 +123,6 @@
Check out the Freemarker website on how to form a template file.
</para>
</section>
<section>
<title>Full Example Templates</title>
<para>
Keycloak comes bundled with some default themes which you cannot view or modify. The distribution
also contains full example templates which you can edit directly if you're running the Keycloak appliance
distro, or which you can install, if you're using the WAR distro. The name of these full example themes
is <literal>template</literal> and they contain a complex example for generating all pages related
to login, error displaying, oauth grant pages, and user account management.
</para>
<para>
For the Keycloak Appliance Distro, these theme files are in the directories
<literal>${appliance-distro}/keycloak/standalone/configuration/themes/login/template</literal>
and <literal>${appliance-distro}/keycloak/standalone/configuration/themes/account/template</literal>.
For the WAR distro, there is a zip file in the examples directory called <literal>keycloak-example-themes-dist.zip</literal>
which you will need to unzip in the <literal>standalone/configuration</literal> or <literal>domain/configuration</literal>
directory if the JBoss or Wildfly instance you have deployed Keycloak server to.
</para>
</section>
</section>
<section>