1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
<?xml version="1.0" encoding="utf-8"?>
<!--
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 id="Java-Broker-Security-Authentication-Providers">
<title>Authentication Providers</title>
<para>
In order to successfully establish a connection to the Java Broker, the connection must be
authenticated. The Java Broker supports a number of different authentication schemes, each
with its own "authentication manager". Different managers may be used on different ports.
Each manager has its own configuration element, the presence of which within the
<security> section denotes the use of that authentication provider. Where only one
such manager is configured, that manager will be used on all ports (including JMX). Where
more than one authentication manager is configured the configuration must define which
manager is the "default", and (if required) the mapping of non-default authentication
managers to other ports.
</para>
<para>
The following configuration sets up three authentication managers, using a password file as
the default (e.g. for the JMX port), Kerberos on port 5672 and Anonymous on 5673.
</para>
<example>
<title>Configuring different authentication schemes on different ports</title>
<programlisting><![CDATA[
<security>
<pd-auth-manager>
<principal-database>
<class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
<attributes>
<attribute>
<name>passwordFile</name>
<value>${conf}/passwd</value>
</attribute>
</attributes>
</principal-database>
</pd-auth-manager>
<kerberos-auth-manager><auth-name>sib</auth-name></kerberos-auth-manager>
<anonymous-auth-manager></anonymous-auth-manager>
<default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager>
<port-mappings>
<port-mapping>
<port>5672</port>
<auth-manager>KerberosAuthenticationManager</auth-manager>
</port-mapping>
<port-mapping>
<port>5673</port>
<auth-manager>AnonymousAuthenticationManager</auth-manager>
</port-mapping>
</port-mappings>
</security>]]>
</programlisting>
</example>
<section><title>Password File</title></section>
<section><title>LDAP</title>
<example>
<title>Configuring a LDAP authentication</title>
<programlisting><![CDATA[
<security>
<simple-ldap-auth-manager>
<provider-url>ldaps://example.com:636/</provider-url>
<search-context>dc=example\,dc=com</search-context>
<search-filter>(uid={0})</search-filter>
</simple-ldap-auth-manager>
</security>]]>
</programlisting>
</example>
<para>
The authentication manager first connects to the ldap server anonymously and searches for the
ldap entity which is identified by the username provided over SASL. Essentially the
authentication manager calls
DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
with the values of search-context and search-filter as the first two arguments, and the username
as the only element in the array which is the third argument.
</para>
<para>
If the search returns a name from the LDAP server, the AuthenticationManager then attempts to
login to the ldap server with the given name and the password.
</para>
<para>
If the URL to open for authentication is different to that for the search, then the
authentication url can be overridden using <provider-auth-url> in addition to providing a
<provider-url>. Note that the URL used for authentication should use ldaps:// since
passwords will be being sent over it.
</para>
<para>
By default com.sun.jndi.ldap.LdapCtxFactory is used to create the context, however this can be
overridden by specifying <ldap-context-factory> in the configuration.
</para>
</section>
<section><title>Kerberos</title>
<para>
Kereberos Authentication is configured using the <kerberos-auth-manager> element within
the <security> section. When referencing from the default-auth-manager or port-mapping
sections, its name is KerberosAuthenticationManager.
</para>
<para>
Since Kerberos support only works where SASL authentication is available (e.g. not for JMX
authentication) you may wish to also include an alternative Authentication Manager
configuration, and use this for other ports:
</para>
<example>
<title>Configuring a Kerberos authentication</title>
<programlisting><![CDATA[
<security>
<pd-auth-manager>
<principal-database>
<class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
<attributes>
<attribute>
<name>passwordFile</name>
<value>${conf}/passwd</value>
</attribute>
</attributes>
</principal-database>
</pd-auth-manager>
<kerberos-auth-manager></kerberos-auth-manager>
<default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager>
<port-mappings>
<port-mapping>
<port>5672</port>
<auth-manager>KerberosAuthenticationManager</auth-manager>
</port-mapping>
</port-mappings>
</security>]]>
</programlisting>
</example>
<para>
Configuration of kerberos is done through system properties (there doesn't seem to be a way
around this unfortunately).
</para>
<programlisting>
export QPID_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><![CDATA[
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="<name>/<host>";
};]]>
</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>
<para>
Note: You may need to install the "Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working.
</para>
</section>
<section><title>SSL Client Certificates</title></section>
<section><title>Anonymous</title></section>
</section>
|
