You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by bu...@apache.org on 2019/07/12 07:24:07 UTC
svn commit: r1047620 - in /websites/staging/directory/trunk/content: ./
api/user-guide/2.2-binding-unbinding.html
Author: buildbot
Date: Fri Jul 12 07:24:06 2019
New Revision: 1047620
Log:
Staging update by buildbot for directory
Modified:
websites/staging/directory/trunk/content/ (props changed)
websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html
Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jul 12 07:24:06 2019
@@ -1 +1 @@
-1861949
+1862953
Modified: websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/2.2-binding-unbinding.html Fri Jul 12 07:24:06 2019
@@ -244,7 +244,99 @@ h2:hover > .headerlink, h3:hover > .head
</pre></div>
-<h3 id="rebinding">Rebinding<a class="headerlink" href="#rebinding" title="Permanent link">¶</a></h3>
+<h3 id="sasl-binding">SASL Binding<a class="headerlink" href="#sasl-binding" title="Permanent link">¶</a></h3>
+<p>There are various <strong>SASL</strong> mechanisms that can be used to bind to a <strong>LDAP</strong> server. The <strong>Apache LDAP API</strong> support the following 5 mechanisms:</p>
+<h4 id="plain">PLAIN<a class="headerlink" href="#plain" title="Permanent link">¶</a></h4>
+<p>To be completed...</p>
+<h4 id="cram-md5">CRAM-MD5<a class="headerlink" href="#cram-md5" title="Permanent link">¶</a></h4>
+<p>To be completed...</p>
+<h4 id="digest-md5">DIGEST-MD5<a class="headerlink" href="#digest-md5" title="Permanent link">¶</a></h4>
+<p>To be completed...</p>
+<h4 id="external">EXTERNAL<a class="headerlink" href="#external" title="Permanent link">¶</a></h4>
+<p>To be completed...</p>
+<h4 id="gssapi">GSSAPI<a class="headerlink" href="#gssapi" title="Permanent link">¶</a></h4>
+<p>First, non-trivial Kerberos authentication requires configuration. Creating a Kerberos configuration is not well documented elsewhere, so we include here sample code. One approach is to create a JAAS configuration file. Hereâs what such a file might contain:</p>
+<p>myapp {
+ com.sun.security.auth.module.Krb5LoginModule required debug=true useKeyTab=true principal="host/ilab2.myorg.org@MYORG.ORG" refreshKrb5Config=true keyTab="/etc/krb5.keytab";
+};</p>
+<p>See online documentation for Krb5LoginModule for possible options. This example uses the hostâs principal, stored in /etc/krb5.keytab. What goes after @ is the Kerberos domain name.</p>
+<p>Note that if you specify a credential cache, the cache must be in a file. Many operating systems now put the userâs credentials in KEYRING or KCM. That wornât work with Java.</p>
+<p>âmyappâ is the name supplied as the login context name. See the code below.</p>
+<p>When you run the program, you must tell java where the configuration file is. e.g. âjava -Djava.security.auth.login.config=jaas.configâ.</p>
+<p>Here is code to connect to ldap with this configuration. We assume that ldapNetworkConnection has already been opened using connect.</p>
+<div class="codehilite"><pre><span class="n">saslGssApiRequest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SaslGssApiRequest</span><span class="o">();</span>
+<span class="n">saslGssApiRequest</span><span class="o">.</span><span class="na">setLoginModuleConfiguration</span><span class="o">(</span><span class="n">Configuration</span><span class="o">.</span><span class="na">getConfiguration</span><span class="o">());</span>
+<span class="n">saslGssApiRequest</span><span class="o">.</span><span class="na">setLoginContextName</span><span class="o">(</span> <span class="s">"myapp"</span><span class="o">);</span>
+<span class="n">saslGssApiRequest</span><span class="o">.</span><span class="na">setMutualAuthentication</span><span class="o">(</span> <span class="kc">true</span> <span class="o">);</span>
+
+<span class="k">try</span> <span class="o">{</span>
+ <span class="n">BindResponse</span> <span class="n">br</span> <span class="o">=</span> <span class="n">ldapNetworkConnection</span><span class="o">.</span><span class="na">bind</span><span class="o">(</span> <span class="n">saslGssApiRequest</span> <span class="o">);</span>
+ <span class="n">ldapNetworkConnection</span><span class="o">.</span><span class="na">startTls</span><span class="o">();</span>
+<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span> <span class="n">LdapException</span> <span class="n">e</span> <span class="o">)</span> <span class="o">{</span>
+ <span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>At this point you can do operations such as search. Note that the argument to setLoginContextName must match the name in the configuration file. This sample uses mutual authentication. It is possible that some LDAP servers might not support that. If so you can set it to false. You may not need startTls if the connection is already secure.</p>
+<p>Sometimes it is more convenient to supply the configuration information programmatically. Here is an example that sets the same options as the config file</p>
+<div class="codehilite"><pre><span class="kd">class</span> <span class="nc">KerberosConfiguration</span> <span class="kd">extends</span> <span class="n">Configuration</span> <span class="o">{</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="n">AppConfigurationEntry</span><span class="o">[]</span> <span class="nf">getAppConfigurationEntry</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></span> <span class="n">options</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">options</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"useKeyTab"</span><span class="o">,</span> <span class="s">"true"</span><span class="o">);</span>
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">options</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"principal"</span><span class="o">,</span> <span class="s">"host/"</span> <span class="o">+</span> <span class="n">InetAddress</span><span class="o">.</span><span class="na">getLocalHost</span><span class="o">().</span><span class="na">getCanonicalHostName</span><span class="o">()</span> <span class="o">+</span> <span class="err">â</span><span class="nd">@MYORG.ORG</span><span class="err">â</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">Exception</span> <span class="n">e</span><span class="o">){</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Can't find our hostname "</span> <span class="o">+</span> <span class="n">e</span><span class="o">);</span>
+ <span class="o">}</span>
+ <span class="n">options</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"refreshKrb5Config"</span><span class="o">,</span> <span class="s">"true"</span><span class="o">);</span>
+ <span class="n">options</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"keyTab"</span><span class="o">,</span> <span class="s">"/etc/krb5.keytab"</span><span class="o">);</span>
+ <span class="n">options</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"debug"</span><span class="o">,</span> <span class="s">"true"</span><span class="o">);</span>
+
+ <span class="k">return</span> <span class="k">new</span> <span class="n">AppConfigurationEntry</span><span class="o">[]{</span>
+ <span class="k">new</span> <span class="nf">AppConfigurationEntry</span><span class="o">(</span><span class="s">"com.sun.security.auth.module.Krb5LoginModule"</span><span class="o">,</span>
+ <span class="n">AppConfigurationEntry</span><span class="o">.</span><span class="na">LoginModuleControlFlag</span><span class="o">.</span><span class="na">REQUIRED</span><span class="o">,</span>
+ <span class="n">options</span><span class="o">),};</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Here is how it is used:</p>
+<div class="codehilite"><pre><span class="n">saslGssApiRequest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SaslGssApiRequest</span><span class="o">();</span>
+<span class="n">saslGssApiRequest</span><span class="o">.</span><span class="na">setLoginModuleConfiguration</span><span class="o">(</span><span class="k">new</span> <span class="n">KerberosConfiguration</span><span class="o">());</span>
+<span class="n">saslGssApiRequest</span><span class="o">.</span><span class="na">setMutualAuthentication</span><span class="o">(</span> <span class="kc">true</span> <span class="o">);</span>
+
+<span class="k">try</span> <span class="o">{</span>
+ <span class="n">BindResponse</span> <span class="n">br</span> <span class="o">=</span> <span class="n">ldapNetworkConnection</span><span class="o">.</span><span class="na">bind</span><span class="o">(</span> <span class="n">saslGssApiRequest</span> <span class="o">);</span>
+ <span class="n">ldapNetworkConnection</span><span class="o">.</span><span class="na">startTls</span><span class="o">();</span>
+<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span> <span class="n">LdapException</span> <span class="n">e</span> <span class="o">)</span> <span class="o">{</span>
+ <span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note that it is not necessary to set the login context name, since it is only needed to process the configuration file.â</p>
+<p>Warnings: </p>
+<ul>
+<li>
+<p><strong>Apache Kerby</strong> does not implement the option to prompt the user for a password, nor does it permit a password to be passed to <strong>GSSAPI</strong>. Thus authentication is limited to key tables and credential caches.</p>
+</li>
+<li>
+<p>The <strong> Apache Kerby</strong> code sets two system properties. In the default case, it clears <strong>KRB5_CONF</strong> and sets <em>javax.security.auth.useSubjectCredsOnly</em> to true. If other code in your application uses <strong>Kerberos</strong>, be aware that there could be conflicts. Be particularly concerned about multi-threaded code that uses different values. Note that in Kirby you can explicitly set <strong>KRB5_CONF</strong>, with <em>setKrb5ConfFilePath</em>, or cause Kirby to set it with setRealmName, setKdcHost, and setKdcPort. If you use different settings for these options in different threads, there is a potential thread-safety issue.</p>
+</li>
+<li>
+<p>The Java implementation of <strong>Kerberos</strong> has the ability to read standard <strong>Kerberos</strong> credential cache files, e.g. <em>/tmp/krb5cc</em>%{uid}<em>. However it canât read credentials from <strong>KEYRING</strong> or <strong>KCM</strong>. If your code asks for authentication to come from an existing credential cache, make sure that it is in a file. If you write an application that expects to use existing credentials for logged in users, without prompting for a password, you may need to set _default_ccache_name</em> in <em>/etc/krb5.conf</em> to a file, e.g.
+ <em>default_ccache_name = /tmp/krb5cc</em>%{uid}_
+This is not an issue if your authentication comes from key tables or prompts the user.</p>
+</li>
+<li>
+<p>The encryption types supported depends upon the Java version. E,g. <em>aes128-cts-hmac-sha256-128</em> and <em>aes256-cts-hmac-sha384-192</em> are supported only as of Java 11.</p>
+</li>
+</ul>
+<h2 id="rebinding">Rebinding<a class="headerlink" href="#rebinding" title="Permanent link">¶</a></h2>
<p>It's possible to issue a <strong>Bind</strong> on an already bound connection and the existing LDAP session will be terminated, and replaced by a new LDAP session. In any case, the connection is not dropped when doing so. Note that if the connection was encrypted, it remains encrypted.</p>
<div class="codehilite"><pre><span class="nd">@Test</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testRebind</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span>
@@ -261,7 +353,7 @@ h2:hover > .headerlink, h3:hover > .head
<p>If you issue a <em>bind</em> on the same connection with some different credentials, then the existing session will be terminated on the server, and a new one will be created. All the pending requests for the initial session will be lost.</p>
-<h3 id="unbinding">Unbinding<a class="headerlink" href="#unbinding" title="Permanent link">¶</a></h3>
+<h2 id="unbinding">Unbinding<a class="headerlink" href="#unbinding" title="Permanent link">¶</a></h2>
<p>This is a trivial operation : you just send an <strong>UnbindRequest</strong> to the server, which will invalidate your session. </p>
<p>It's important to know that when you issue an <strong>Unbind</strong>, the connection is dropped. It's done like this:</p>
<div class="codehilite"><pre><span class="nd">@Test</span>