doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-Kerberos.xml

<?xml version="1.0"?>
<!--

 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.

-->

<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Security-Kerberos-Provider">
    <title>Kerberos</title>

    <para> Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the
        connections. </para>

    <para> Configuration of kerberos is done through system properties (there doesn't seem to be a
        way around this unfortunately). </para>

    <programlisting>
    export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
    \${QPID_HOME}/bin/qpid-server
  </programlisting>

    <para>Where qpid.conf would look something like this:</para>

    <programlisting>
com.sun.security.jgss.accept {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    doNotPrompt=true
    realm="EXAMPLE.COM"
    useSubjectCredsOnly=false
    kdc="kerberos.example.com"
    keyTab="/path/to/keytab-file"
    principal="&lt;name&gt;/&lt;host&gt;";
};</programlisting>

    <para> Where realm, kdc, keyTab and principal should obviously be set correctly for the
        environment where you are running (see the existing documentation for the C++ broker about
        creating a keytab file). </para>

    <section xml:id="Java-Broker-Security-Kerberos-Provider-Spnego">
        <title>SPNEGO Authentication</title>
        <para>
            SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) based authentication can be configured
            for Web Management Console and REST API.
        </para>
        <para>A special JAAS login configuration needs to be provided for
            Service Principal Name (SPN) <emphasis>HTTP/{FQDN}@REALM</emphasis> in addition to configuration
            provided for broker service principal in scope <emphasis>com.sun.security.jgss.accept</emphasis>.
            An example of such SPNEGO configuration is provided below, </para>
        <programlisting>
spnego {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    doNotPrompt=true
    realm="EXAMPLE.COM"
    useSubjectCredsOnly=false
    kdc="kerberos.example.com"
    keyTab="/path/to/keytab-file-for-HTTP-principal"
    principal="HTTP/broker.org";
};</programlisting>

        <important>
            <para>Please, note that in the example above a principal name is specified as
            <emphasis>HTTP/broker.org</emphasis> where <emphasis>broker.org</emphasis> is supposed to be
            a fully qualified name of the host where broker is running. The FQDN used to access the Broker
            must match the host name in the SPN exactly otherwise the authentication will fail.</para>
        </important>
        <para>
            A name of configuration module in the example above is <emphasis>spnego</emphasis>. It can be
            communicated to the Kerberos authentication provider via context variable or JVM system property
            <emphasis>qpid.auth.gssapi.spnegoConfigScope</emphasis>. For example,

    <programlisting>
        export QPID_OPTS=-Dqpid.auth.gssapi.spnegoConfigScope=spnego -Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
    </programlisting>
        </para>
        <para>
            The RELM part in name of authenticated principal logged with SPNEGO mechanism can be stripped by
            setting context variable <emphasis>qpid.auth.gssapi.spnegoStripRealmFromPrincipalName</emphasis> to
            <emphasis>true</emphasis>.
        </para>
    </section>

</section>