Kerberos documentation
This commit is contained in:
mposolda
parent
663560a185
commit
aaf3c18a1b
5 changed files with 282 additions and 11 deletions
|
|
@ -32,6 +32,7 @@
|
||||||
<!ENTITY Events SYSTEM "modules/events.xml">
|
<!ENTITY Events SYSTEM "modules/events.xml">
|
||||||
<!ENTITY AdminApi SYSTEM "modules/admin-rest-api.xml">
|
<!ENTITY AdminApi SYSTEM "modules/admin-rest-api.xml">
|
||||||
<!ENTITY UserFederation SYSTEM "modules/user-federation.xml">
|
<!ENTITY UserFederation SYSTEM "modules/user-federation.xml">
|
||||||
|
<!ENTITY Kerberos SYSTEM "modules/kerberos.xml">
|
||||||
<!ENTITY ExportImport SYSTEM "modules/export-import.xml">
|
<!ENTITY ExportImport SYSTEM "modules/export-import.xml">
|
||||||
<!ENTITY ServerCache SYSTEM "modules/cache.xml">
|
<!ENTITY ServerCache SYSTEM "modules/cache.xml">
|
||||||
<!ENTITY SecurityVulnerabilities SYSTEM "modules/security-vulnerabilities.xml">
|
<!ENTITY SecurityVulnerabilities SYSTEM "modules/security-vulnerabilities.xml">
|
||||||
|
|
@ -119,6 +120,7 @@ This one is short
|
||||||
&AdminApi;
|
&AdminApi;
|
||||||
&Events;
|
&Events;
|
||||||
&UserFederation;
|
&UserFederation;
|
||||||
|
&Kerberos;
|
||||||
&ExportImport;
|
&ExportImport;
|
||||||
&ServerCache;
|
&ServerCache;
|
||||||
&SAML;
|
&SAML;
|
||||||
|
|
|
||||||
231
docbook/reference/en/en-US/modules/kerberos.xml
Normal file
231
docbook/reference/en/en-US/modules/kerberos.xml
Normal 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>
|
||||||
|
|
@ -97,6 +97,14 @@
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</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>
|
<varlistentry>
|
||||||
<term>Other options</term>
|
<term>Other options</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
|
|
||||||
|
|
@ -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
|
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:
|
in Keycloak admin console with the settings like:
|
||||||
Vendor: Other
|
* Vendor: Other
|
||||||
Connection URL: ldap://localhost:10389
|
* Connection URL: ldap://localhost:10389
|
||||||
Base DN: dc=keycloak,dc=org
|
* Base DN: dc=keycloak,dc=org
|
||||||
User DN Suffix: ou=People,dc=keycloak,dc=org
|
* User DN Suffix: ou=People,dc=keycloak,dc=org
|
||||||
Bind DN: uid=admin,ou=system
|
* Bind DN: uid=admin,ou=system
|
||||||
Bind credential: secret
|
* Bind credential: secret
|
||||||
|
|
||||||
Kerberos server
|
Kerberos server
|
||||||
---------------
|
---------------
|
||||||
|
|
@ -114,10 +114,40 @@ To start a ApacheDS based Kerberos server for testing Kerberos + LDAP sending ru
|
||||||
|
|
||||||
mvn exec:java -Pkerberos
|
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
|
There are additional system properties you can use to configure (See EmbeddedServersFactory class for details) but for testing purposes default values should be good.
|
||||||
in Keycloak admin console with same settings like mentioned in previous LDAP section. And you can enable Kerberos with the settings like:
|
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
|
Once kerberos is running, you can create LDAP Federation provider in Keycloak admin console with same settings like mentioned in previous LDAP section.
|
||||||
KeyTab: $KEYCLOAK_SOURCES/testsuite/integration/src/main/resources/kerberos/http.keytab
|
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` .
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -54,7 +54,7 @@ public class KerberosEmbeddedServer extends LDAPEmbeddedServer {
|
||||||
public void init() throws Exception {
|
public void init() throws Exception {
|
||||||
super.init();
|
super.init();
|
||||||
|
|
||||||
log.info("Creating KDC server");
|
log.info("Creating KDC server. kerberosRealm: " + kerberosRealm + ", kdcPort: " + kdcPort);
|
||||||
createAndStartKdcServer();
|
createAndStartKdcServer();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue