Merge pull request #423 from mposolda/master
Updated documentation and added example for Authentication SPI
This commit is contained in:
Stian Thorgersen
commit
5120549005
11 changed files with 321 additions and 0 deletions
|
|
@ -23,6 +23,9 @@
|
||||||
<!ENTITY CORS SYSTEM "modules/cors.xml">
|
<!ENTITY CORS SYSTEM "modules/cors.xml">
|
||||||
<!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
|
<!ENTITY Timeouts SYSTEM "modules/timeouts.xml">
|
||||||
<!ENTITY Audit SYSTEM "modules/audit.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>
|
<book>
|
||||||
|
|
@ -103,6 +106,9 @@ This one is short
|
||||||
&CORS;
|
&CORS;
|
||||||
&Timeouts;
|
&Timeouts;
|
||||||
&Audit;
|
&Audit;
|
||||||
|
&Authentication;
|
||||||
|
&Ldap;
|
||||||
|
&ExportImport;
|
||||||
&Migration;
|
&Migration;
|
||||||
|
|
||||||
</book>
|
</book>
|
||||||
|
|
|
||||||
66
docbook/reference/en/en-US/modules/authentication-spi.xml
Normal file
66
docbook/reference/en/en-US/modules/authentication-spi.xml
Normal 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>
|
||||||
31
docbook/reference/en/en-US/modules/export-import.xml
Normal file
31
docbook/reference/en/en-US/modules/export-import.xml
Normal 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>
|
||||||
12
docbook/reference/en/en-US/modules/ldap.xml
Normal file
12
docbook/reference/en/en-US/modules/ldap.xml
Normal 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>
|
||||||
20
examples/providers/authentication-properties/README.md
Normal file
20
examples/providers/authentication-properties/README.md
Normal file
|
|
@ -0,0 +1,20 @@
|
||||||
|
Example Authentication Provider based on property file values
|
||||||
|
=============================================================
|
||||||
|
|
||||||
|
* To deploy copy "target/authentication-properties-example.jar" to "standalone/deployments/auth-server.war/WEB-INF/lib" . Then edit "standalone/configuration/keycloak-server.json" and add this:
|
||||||
|
````shell
|
||||||
|
"authentication": {
|
||||||
|
"properties": {
|
||||||
|
"propertiesFileLocation": "users.properties"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
````
|
||||||
|
|
||||||
|
* Then start (or restart)the server. Once started open the admin console, select your realm, then click on "Authentication" and then "Add provider" and select "properties" from the list.
|
||||||
|
This will mean that realm will use PropertiesAuthenticationProvider for authentication.
|
||||||
|
|
||||||
|
* Once you try to login to realm, you can login with username/password like "joe/password1" or "james/password2" . Once joe is authenticated,
|
||||||
|
you can see in Keycloak admin console in "Users" list that user "joe" was added to the list.
|
||||||
|
|
||||||
|
* You can try to login as joe and then go to [http://localhost:8080/auth/realms/keycloak-admin/account/password](http://localhost:8080/auth/realms/keycloak-admin/account/password) and change the password.
|
||||||
|
You will then be able to logout and login with new password because properties were updated. But this is just in memory-properties, so after server restart the password will be again "password1" .
|
||||||
45
examples/providers/authentication-properties/pom.xml
Normal file
45
examples/providers/authentication-properties/pom.xml
Normal file
|
|
@ -0,0 +1,45 @@
|
||||||
|
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||||
|
<parent>
|
||||||
|
<artifactId>examples-providers-pom</artifactId>
|
||||||
|
<groupId>org.keycloak</groupId>
|
||||||
|
<version>1.0-beta-1-SNAPSHOT</version>
|
||||||
|
<relativePath>../pom.xml</relativePath>
|
||||||
|
</parent>
|
||||||
|
<name>Properties Authentication Provider Example</name>
|
||||||
|
<description/>
|
||||||
|
<modelVersion>4.0.0</modelVersion>
|
||||||
|
|
||||||
|
<artifactId>authentication-properties-example</artifactId>
|
||||||
|
<packaging>jar</packaging>
|
||||||
|
|
||||||
|
<dependencies>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.keycloak</groupId>
|
||||||
|
<artifactId>keycloak-core</artifactId>
|
||||||
|
<version>${project.version}</version>
|
||||||
|
<scope>provided</scope>
|
||||||
|
</dependency>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.keycloak</groupId>
|
||||||
|
<artifactId>keycloak-model-api</artifactId>
|
||||||
|
<version>${project.version}</version>
|
||||||
|
<scope>provided</scope>
|
||||||
|
</dependency>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.keycloak</groupId>
|
||||||
|
<artifactId>keycloak-authentication-api</artifactId>
|
||||||
|
<version>${project.version}</version>
|
||||||
|
<scope>provided</scope>
|
||||||
|
</dependency>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.jboss.logging</groupId>
|
||||||
|
<artifactId>jboss-logging</artifactId>
|
||||||
|
<scope>provided</scope>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
|
||||||
|
<build>
|
||||||
|
<finalName>authentication-properties-example</finalName>
|
||||||
|
</build>
|
||||||
|
</project>
|
||||||
|
|
@ -0,0 +1,75 @@
|
||||||
|
package org.keycloak.examples.providers.authentication;
|
||||||
|
|
||||||
|
import java.util.Collections;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Properties;
|
||||||
|
|
||||||
|
import org.jboss.logging.Logger;
|
||||||
|
import org.keycloak.authentication.AuthProviderStatus;
|
||||||
|
import org.keycloak.authentication.AuthUser;
|
||||||
|
import org.keycloak.authentication.AuthenticationProvider;
|
||||||
|
import org.keycloak.authentication.AuthenticationProviderException;
|
||||||
|
import org.keycloak.models.RealmModel;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @author <a href="mailto:mposolda@redhat.com">Marek Posolda</a>
|
||||||
|
*/
|
||||||
|
public class PropertiesAuthenticationProvider implements AuthenticationProvider {
|
||||||
|
|
||||||
|
private static final Logger log = Logger.getLogger(PropertiesAuthenticationProvider.class);
|
||||||
|
|
||||||
|
private final Properties properties;
|
||||||
|
|
||||||
|
public PropertiesAuthenticationProvider(Properties properties) {
|
||||||
|
this.properties = properties;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public String getName() {
|
||||||
|
return "properties";
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public List<String> getAvailableOptions() {
|
||||||
|
return Collections.emptyList();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public AuthUser getUser(RealmModel realm, Map<String, String> configuration, String username) throws AuthenticationProviderException {
|
||||||
|
if (properties.getProperty(username) != null) {
|
||||||
|
return new AuthUser(username, username, getName());
|
||||||
|
} else {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public String registerUser(RealmModel realm, Map<String, String> configuration, String username) throws AuthenticationProviderException {
|
||||||
|
// Registration ignored
|
||||||
|
return username;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public AuthProviderStatus validatePassword(RealmModel realm, Map<String, String> configuration, String username, String password) throws AuthenticationProviderException {
|
||||||
|
String propertyFilePassword = properties.getProperty(username);
|
||||||
|
if (propertyFilePassword != null && propertyFilePassword.equals(password)) {
|
||||||
|
return AuthProviderStatus.SUCCESS;
|
||||||
|
} else {
|
||||||
|
return AuthProviderStatus.INVALID_CREDENTIALS;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public boolean updateCredential(RealmModel realm, Map<String, String> configuration, String username, String password) throws AuthenticationProviderException {
|
||||||
|
// Just update in memory (Won't survive restart)
|
||||||
|
log.info("Going to update password for user " + username + " in PropertiesAuthenticationProvider");
|
||||||
|
properties.put(username, password);
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void close() {
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,62 @@
|
||||||
|
package org.keycloak.examples.providers.authentication;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.io.InputStream;
|
||||||
|
import java.util.Properties;
|
||||||
|
|
||||||
|
import org.jboss.logging.Logger;
|
||||||
|
import org.keycloak.Config;
|
||||||
|
import org.keycloak.authentication.AuthenticationProvider;
|
||||||
|
import org.keycloak.authentication.AuthenticationProviderFactory;
|
||||||
|
import org.keycloak.provider.ProviderSession;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @author <a href="mailto:mposolda@redhat.com">Marek Posolda</a>
|
||||||
|
*/
|
||||||
|
public class PropertiesAuthenticationProviderFactory implements AuthenticationProviderFactory {
|
||||||
|
|
||||||
|
private static final Logger log = Logger.getLogger(PropertiesAuthenticationProviderFactory.class);
|
||||||
|
|
||||||
|
private Properties properties;
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public AuthenticationProvider create(ProviderSession providerSession) {
|
||||||
|
return new PropertiesAuthenticationProvider(properties);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void init(Config.Scope config) {
|
||||||
|
String propsFileLocation = config.get("propertiesFileLocation");
|
||||||
|
if (propsFileLocation == null) {
|
||||||
|
throw new IllegalStateException("Properties file location is not configured in PropertiesAuthenticationProviderFactory");
|
||||||
|
} else {
|
||||||
|
log.info("Using properties file: " + propsFileLocation);
|
||||||
|
}
|
||||||
|
|
||||||
|
this.properties = new Properties();
|
||||||
|
InputStream propertiesStream = null;
|
||||||
|
try {
|
||||||
|
propertiesStream = getClass().getClassLoader().getResourceAsStream(propsFileLocation);
|
||||||
|
this.properties.load(propertiesStream);
|
||||||
|
} catch (IOException ioException) {
|
||||||
|
throw new RuntimeException(ioException);
|
||||||
|
} finally {
|
||||||
|
if (propertiesStream != null) {
|
||||||
|
try {
|
||||||
|
propertiesStream.close();
|
||||||
|
} catch (IOException e) {
|
||||||
|
log.error("Error when closing InputStream", e);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void close() {
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public String getId() {
|
||||||
|
return "properties";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
org.keycloak.examples.providers.authentication.PropertiesAuthenticationProviderFactory
|
||||||
|
|
@ -0,0 +1,2 @@
|
||||||
|
joe=password1
|
||||||
|
james=password2
|
||||||
|
|
@ -35,5 +35,6 @@
|
||||||
<modules>
|
<modules>
|
||||||
<module>audit-listener-sysout</module>
|
<module>audit-listener-sysout</module>
|
||||||
<module>audit-provider-mem</module>
|
<module>audit-provider-mem</module>
|
||||||
|
<module>authentication-properties</module>
|
||||||
</modules>
|
</modules>
|
||||||
</project>
|
</project>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue