libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Kerberos documentation

Browse source
This commit is contained in:
mposolda 2015-02-26 20:34:51 +01:00
parent 663560a185
commit aaf3c18a1b
5 changed files with 282 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docbook/reference/en/en-US/master.xml
View file

@ -32,6 +32,7 @@
<!ENTITY Events SYSTEM "modules/events.xml">
<!ENTITY AdminApi SYSTEM "modules/admin-rest-api.xml">
<!ENTITY UserFederation SYSTEM "modules/user-federation.xml">
<!ENTITY Kerberos SYSTEM "modules/kerberos.xml">
<!ENTITY ExportImport SYSTEM "modules/export-import.xml">
<!ENTITY ServerCache SYSTEM "modules/cache.xml">
<!ENTITY SecurityVulnerabilities SYSTEM "modules/security-vulnerabilities.xml">
@ -119,6 +120,7 @@ This one is short
&AdminApi;
&Events;
&UserFederation;
&Kerberos;
&ExportImport;
&ServerCache;
&SAML;

231
docbook/reference/en/en-US/modules/kerberos.xml Normal file
View file

@ -0,0 +1,231 @@
<chapter id="kerberos">
<title>Kerberos brokering</title>
<para>
Keycloak supports login with Kerberos ticket through SPNEGO. SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is used
to authenticate transparently through the web browser after the user has been authenticated when logging-in his session.
For non-web cases or when ticket is not available during login, Keycloak also supports login with Kerberos username/password.
</para>
<para>
A typical use case for web authentication is the following:
<orderedlist>
<listitem>
<para>
User logs into his desktop (Such as a Windows machine in Active Directory domain or Linux machine with Kerberos integration enabled).
</para>
</listitem>
<listitem>
<para>
User then uses his browser (IE/Firefox/Chrome) to access a web application secured by Keycloak.
</para>
</listitem>
<listitem>
<para>
Application redirects to Keycloak login.
</para>
</listitem>
<listitem>
<para>
Keycloak sends HTML login screen together with status 401 and HTTP header <literal>WWW-Authenticate: Negotiate</literal>
</para>
</listitem>
<listitem>
<para>
In case that browser has Kerberos ticket from desktop login, it transfers the desktop sign on information to the
Keycloak in header <literal>Authorization: Negotiate 'spnego-token'</literal> . Otherwise it just displays login screen.
</para>
</listitem>
<listitem>
<para>
Keycloak validates token from browser and authenticate user. It provisions user data from LDAP (in case of
LDAPFederationProvider with Kerberos authentication support) or let user to update his profile and prefill data
(in case of KerberosFederationProvider).
</para>
</listitem>
<listitem>
<para>
Keycloak returns back to the application. Communication between Keycloak and application happens through OpenID
Connect or SAML messages. The fact that Keycloak was authenticated through Kerberos is hidden from the application.
So Keycloak acts as broker to Kerberos/SPNEGO login.
</para>
</listitem>
</orderedlist>
</para>
<para>
For setup there are 3 main parts:
<orderedlist>
<listitem>
<para>
Setup and configuration of Kerberos server (KDC)
</para>
</listitem>
<listitem>
<para>
Setup and configuration of Keycloak server
</para>
</listitem>
<listitem>
<para>
Setup and configuration of client machines
</para>
</listitem>
</orderedlist>
</para>
<section>
<title>Setup of Kerberos server</title>
<para>
This is platform dependent. Exact steps depend on your OS and the Kerberos vendor you're going to use.
Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server.
</para>
<para>
At least you will need to:
<itemizedlist>
<listitem>
<para>
Add some user principals to your Kerberos database. You can also integrate your Kerberos with LDAP,
which means that user accounts will be provisioned from LDAP server.
</para>
</listitem>
<listitem>
<para>
Add service principal for "HTTP" service. For example if your Keycloak server will be running on
<literal>www.mydomain.org</literal> you may need to add principal <literal>HTTP/www.mydomain.org@MYDOMAIN.ORG</literal>
assuming that MYDOMAIN.ORG will be your Kerberos realm.
</para>
<para>
For example on MIT Kerberos you can run "kadmin" session. If you are on same machine where is MIT Kerberos, you can simply use command:
<programlisting><![CDATA[
sudo kadmin.local
]]></programlisting>
Then add HTTP principal and export his key to keytab file with the commands like:
<programlisting><![CDATA[
addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG
ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG
]]></programlisting>
Keytab file <literal>/tmp/http.keytab</literal> will need to be accessible on the host where keycloak server will be running.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Setup and configuration of Keycloak server</title>
<itemizedlist>
<listitem>
<para>
Install kerberos client. This is again platform dependent. If you are on Fedora, Ubuntu or RHEL, you can install package <literal>freeipa-client</literal>,
which contains Kerberos client and bunch of other stuff.
</para>
</listitem>
<listitem>
<para>
Configure kerberos client (on linux it's in file <literal>/etc/krb5.conf</literal> ). You need to put your Kerberos realm and at least
configure the Http domains your server will be running on. For the example realm MYDOMAIN.ORG you may configure <literal>domain_realm</literal> section like this:
<programlisting><![CDATA[
[domain_realm]
.mydomain.org = MYDOMAIN.ORG
mydomain.org = MYDOMAIN.ORG
]]></programlisting>
</para>
</listitem>
<listitem>
<para>
Export keytab file with HTTP principal and make sure the file is accessible to the process under which Keycloak
server is running. For production, it's ideal if it's readable just by this process and not by someone else.
For MIT Kerberos example above, we already exported keytab to <literal>/tmp/http.keytab</literal> . If your KDC and Keycloak
are running on same host, you have file already available.
</para>
</listitem>
<listitem>
<para>
Finally run Keycloak server and configure SPNEGO/Kerberos authentication in Keycloak admin console. Keycloak supports Kerberos authentication
through <link linkend='user_federation'>Federation provider SPI</link> . We have 2 federation providers with Kerberos authentication support:
<variablelist>
<varlistentry>
<term>Kerberos</term>
<listitem>
<para>
This provider is useful if you want to authenticate with Kerberos <literal>NOT</literal> backed by LDAP server.
In this case, users are usually created to Keycloak database after first successful SPNEGO/Kerberos login
and they may need to update profile after first login, as Kerberos protocol itself doesn't provision
any data like first name, last name or email.
</para>
<para>
You can also choose if users can authenticate with classic username/password. In this case, if user doesn't have SPNEGO ticket available,
Keycloak will display login screen and user can fill his Kerberos username and password on login screen. Username/password works also for non-web flows like
<link linkend='direct-access-grants'>Direct Access grants</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LDAP</term>
<listitem>
<para>
This provider is useful if you want to authenticate with Kerberos backed by LDAP server.
In this case, data about users are provisioned from LDAP server after successful Kerberos authentication.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Setup and configuration of client machines</title>
<para>
Clients need to install kerberos client and setup krb5.conf as described above. Additionally they need to enable SPNEGO login support in their browser.
See for example <ulink url="http://www.microhowto.info/howto/configure_firefox_to_authenticate_using_spnego_and_kerberos.html">this</ulink>
for more info about Firefox. URI <literal>.mydomain.org</literal> must be allowed in <literal>network.negotiate-auth.trusted-uris</literal> config option.
</para>
<para>
In windows domain, clients usually don't need to configure anything special as IE is already able to participate in SPNEGO authentication for the windows domain.
</para>
</section>
<section>
<title>Example setups</title>
<para>
For easier testing with Kerberos, we provided some example setups to test.
</para>
<section>
<title>Keycloak and FreeIPA docker image</title>
<para>
Once you install <ulink url="https://www.docker.com/">docker</ulink>, you can run docker image with <ulink url="http://www.freeipa.org/">FreeIPA</ulink>
server installed. FreeIPA provides integrated security solution with MIT Kerberos and 389 LDAP server among other things . The image provides
also Keycloak server configured with LDAP Federation provider and enabled SPNEGO/Kerberos authentication against the FreeIPA server.
See details <ulink url="https://github.com/mposolda/keycloak-freeipa-docker/blob/master/README.md">here</ulink> .
</para>
</section>
<section>
<title>ApacheDS testing Kerberos server</title>
<para>
For quick testing and unit tests, we use very simple <ulink url="http://directory.apache.org/apacheds/">ApacheDS</ulink> Kerberos server.
You need to build Keycloak from sources and then run Kerberos server with maven-exec-plugin from our testsuite. See details
<ulink url="https://github.com/keycloak/keycloak/blob/master/testsuite/integration/README.md#kerberos-server">here</ulink> .
</para>
</section>
</section>
<section>
<title>Troubleshooting</title>
<para>
If you have issues, we recommend to enable more logging by:
<itemizedlist>
<listitem>
<para>
Enable <literal>Debug</literal> flag in admin console for Kerberos or LDAP federation providers
</para>
</listitem>
<listitem>
<para>
Enable TRACE logging for category <literal>org.keycloak</literal> in logging section of <literal>$WILDFLY_HOME/standalone/configuration/standalone.xml</literal>
to receive more info <literal>$WILDFLY_HOME/standalone/log/server.log</literal>
</para>
</listitem>
<listitem>
<para>
Add system properties <literal>-Dsun.security.krb5.debug=true</literal> and <literal>-Dsun.security.spnego.debug=true</literal>
</para>
</listitem>
</itemizedlist>
</para>
</section>
</chapter>

8
docbook/reference/en/en-US/modules/user-federation.xml
View file

@ -97,6 +97,14 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Allow Kerberos authentication</term>
<listitem>
<para>
Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP. More info in <link linkend="kerberos">Kerberos section</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Other options</term>
<listitem>

50
testsuite/integration/README.md
View file

@ -100,12 +100,12 @@ To start a ApacheDS based LDAP server for testing LDAP sending run:
There are additional system properties you can use to configure (See EmbeddedServersFactory class for details). Once done, you can create LDAP Federation provider
in Keycloak admin console with the settings like:
Vendor: Other
Connection URL: ldap://localhost:10389
Base DN: dc=keycloak,dc=org
User DN Suffix: ou=People,dc=keycloak,dc=org
Bind DN: uid=admin,ou=system
Bind credential: secret
* Vendor: Other
* Connection URL: ldap://localhost:10389
* Base DN: dc=keycloak,dc=org
* User DN Suffix: ou=People,dc=keycloak,dc=org
* Bind DN: uid=admin,ou=system
* Bind credential: secret
Kerberos server
---------------
@ -114,10 +114,40 @@ To start a ApacheDS based Kerberos server for testing Kerberos + LDAP sending ru
mvn exec:java -Pkerberos
There are additional system properties you can use to configure (See EmbeddedServersFactory class for details). Once done, you can create LDAP Federation provider
in Keycloak admin console with same settings like mentioned in previous LDAP section. And you can enable Kerberos with the settings like:
There are additional system properties you can use to configure (See EmbeddedServersFactory class for details) but for testing purposes default values should be good.
By default ApacheDS LDAP server will be running on localhost:10389 and Kerberos KDC on localhost:6088 . LDAP will import initial data from [src/main/resources/kerberos/users-kerberos.ldif](src/main/resources/kerberos/users-kerberos.ldif) .
Server Principal: HTTP/localhost@KEYCLOAK.ORG
KeyTab: $KEYCLOAK_SOURCES/testsuite/integration/src/main/resources/kerberos/http.keytab
Once kerberos is running, you can create LDAP Federation provider in Keycloak admin console with same settings like mentioned in previous LDAP section.
But additionally you can enable Kerberos authentication in LDAP provider with the settings like:
* Kerberos realm: KEYCLOAK.ORG
* Server Principal: HTTP/localhost@KEYCLOAK.ORG
* KeyTab: $KEYCLOAK_SOURCES/testsuite/integration/src/main/resources/kerberos/http.keytab (Replace $KEYCLOAK_SOURCES with correct absolute path of your sources)
Once you do this, you should also ensure that your Kerberos client configuration file is properly configured with KEYCLOAK.ORG domain.
See [src/main/resources/kerberos/test-krb5.conf](src/main/resources/kerberos/test-krb5.conf) for inspiration. The location of Kerberos configuration file
is platform dependent (In linux it's file `/etc/krb5.conf` )
Then you need to configure your browser to allow SPNEGO/Kerberos login from `localhost` .
Exact steps are again browser dependent. For Firefox see for example [http://www.microhowto.info/howto/configure_firefox_to_authenticate_using_spnego_and_kerberos.html](http://www.microhowto.info/howto/configure_firefox_to_authenticate_using_spnego_and_kerberos.html) .
URI `localhost` must be allowed in `network.negotiate-auth.trusted-uris` config option.
For Chrome, you just need to run the browser with command similar to this (more details in Chrome documentation):
```
/usr/bin/google-chrome-stable --auth-server-whitelist="localhost"
```
Finally test the integration by retrieve kerberos ticket. In many OS you can achieve this by running command from CMD like:
```
kinit hnelson@KEYCLOAK.ORG
```
and provide password `secret`
Now when you access `http://localhost:8081/auth/realms/master/account` you should be logged in automatically as user `hnelson` .

2
testsuite/integration/src/main/java/org/keycloak/testutils/ldap/KerberosEmbeddedServer.java
View file

@ -54,7 +54,7 @@ public class KerberosEmbeddedServer extends LDAPEmbeddedServer {
public void init() throws Exception {
super.init();
log.info("Creating KDC server");
log.info("Creating KDC server. kerberosRealm: " + kerberosRealm + ", kdcPort: " + kdcPort);
createAndStartKdcServer();
}