content/api/user-guide/5.3-sasl-bind.mdtext - directory-site - Git at Google

 Title: 5.3 - SASL Bind
 NavPrev: 5.2-start-tls.html
 NavPrevText: 5.2 - StartTLS
 NavUp: 5-ldap-security.html
 NavUpText: 5 - LDAP Security
 NavNext: 5.4-password-handling.html
 NavNextText: 5.4 - Password Handling
 Notice: 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.

 >**Note:** Work in progress...

 # 5.3 - SASL Bind

 *SASL* is defined by [RFC 4422](https://tools.ietf.org/html/rfc4422) which obsoletes [RFC2222](https://tools.ietf.org/html/rfc2222). There are also a few RFCs that are related to *SASL*, they are listed in the next paragraph.

 In any case, as *ApacheDS* and the *Apache LDAP API* are based on *Java*, we depend on the *Java* *SASL* impementation. Typically, this is handled by the *SunSASL* provider, which only support the following mechanisms, as of Java 8 :

 * PLAIN (Client)
 * CRAM-MD5 (Client/Server)
 * DIGEST-MD5 (Client/Server)
 * GSSAPI (Client/Server)
 * EXTERNAL (Client)

 Note that in *Java 9*, those mechanisms are spread in two different providers, the *GSSAPI* mechanism being handled by the *JdkSASL* provider.

 We currently don't support any other provider.

 ## SASL Bind handling

 The *SASL* framework may require more than one *BindRequest*/*BindResponse* to be exchanched, as ther server may need more information from the client.  The client must be ready to deal with such situation, by controling the resturned result : *SASL_BIND_IN_PROGRESS* means more is required.

 In any case, the client must send a first *BindRequest* with the proper information. We have dedicated methods to do so, based on the *SASL* mechanism to use :

 * bindSaslPlain() : *PLAIN* mechanism
 * bindSaslCramMd5() : *CRAM-MD5* mechanism
 * bindSaslDigestMd5() : *DIGEST-MD5* mechanism
 * bindSaslGssApi() : *GSSAPI* mechanism
 * bindSaslExternal() : *EXTERNAL* mechaism

 We don't support the *SASL* *ANONYMOUS* mechanism.

 There is also a more generic method that anyone can use with any mechanism, assuming we have a class implementing it :

 * bindSasl( Saslrequest )

 It's just about using an instance of a class extending the *SaslRequest* interface.


 Here is an example of a *SASL* bind, where we assume we have an entry which *uid* is "hnelson", and a *userPassword* which is "secret" (note that the password must be in clear text in the server) :

     :::java
         LdapNetworkConnection connection = new LdapNetworkConnection( Network.LOOPBACK_HOSTNAME, getLdapServer().getPort() );

         BindResponse resp = connection.bindSaslCramMd5( "hnelson", "secret" );
         assertEquals( ResultCodeEnum.SUCCESS, resp.getLdapResult().getResultCode() );


 ## RFCs

 Here are the list of RFCs related to *SASL*:

 ![](../../images/icons/information.gif) : Informational

 ![](../../images/icons/lightbulb.gif) : Historic

 ![](../../images/icons/lightbulb_on.gif) : Proposed Standard

 ![](../../images/icons/warning.gif) : Experimental

 ![](../../images/icons/thumbs_up.gif) : Best current practice


 ### Obsolete RFCs

 | RFC | Description | Obsoleted by | Status  |
 |---|---|---|---|
 | [RFC 2222](https://tools.ietf.org/html/rfc2222) | Simple Authentication and Security Layer (SASL) | [RFC 4422](https://tools.ietf.org/html/rfc4422), [RFC 4752](https://tools.ietf.org/html/rfc4752) | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 2245](https://tools.ietf.org/html/rfc2245) | Anonymous SASL Mechanism | [RFC 4505](https://tools.ietf.org/html/rfc4505) |  ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 2831](https://tools.ietf.org/html/rfc2831) | Using Digest Authentication as a SASL Mechanism | [RFC 4505](https://tools.ietf.org/html/rfc4505) | ![](../../images/icons/lightbulb.gif) |
 | [RFC 4013](https://tools.ietf.org/html/rfc4013) | SASLprep: Stringprep Profile for User Names and Passwords | [RFC 7613](https://tools.ietf.org/html/rfc7613)| ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 7613](https://tools.ietf.org/html/rfc7613) | Preparation, Enforcement, and Comparison of Internationalized Strings Representing Usernames and Passwords | [RFC 8265](https://tools.ietf.org/html/rfc8265) | ![](../../images/icons/lightbulb_on.gif) |

 ### Active RFCs

 | RFC | Description | Status  |
 |---|---|---|---|
 | [RFC 2444](https://tools.ietf.org/html/rfc2444) | The One-Time-Password SASL Mechanism | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 2808](https://tools.ietf.org/html/rfc2808) | The SecurID(r) SASL Mechanism | ![](../../images/icons/information.gif)  |
 | [RFC 4422](https://tools.ietf.org/html/rfc4422) | Simple Authentication and Security Layer (SASL) | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 4505](https://tools.ietf.org/html/rfc4505) | Anonymous Simple Authentication and Security Layer (SASL) Mechanism | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 4616](https://tools.ietf.org/html/rfc4616) | The PLAIN Simple Authentication and Security Layer (SASL) Mechanism | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 4752](https://tools.ietf.org/html/rfc4752) | The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 5801](https://tools.ietf.org/html/rfc58à&) | Using Generic Security Service Application Program Interface (GSS-API) Mechanisms in Simple Authentication and Security Layer (SASL): The GS2 Mechanism Family | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 5802](https://tools.ietf.org/html/rfc5802) | Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 6331](https://tools.ietf.org/html/rfc6331) | Moving DIGEST-MD5 to Historic | ![](../../images/icons/information.gif)|
 | [RFC 7677](https://tools.ietf.org/html/rfc7677) | SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms | ![](../../images/icons/lightbulb_on.gif) |
 | [RFC 8265](https://tools.ietf.org/html/rfc8265) | Preparation, Enforcement, and Comparison of Internationalized Strings Representing Usernames and Passwords | ![](../../images/icons/lightbulb_on.gif) |
	Title: 5.3 - SASL Bind
	NavPrev: 5.2-start-tls.html
	NavPrevText: 5.2 - StartTLS
	NavUp: 5-ldap-security.html
	NavUpText: 5 - LDAP Security
	NavNext: 5.4-password-handling.html
	NavNextText: 5.4 - Password Handling
	Notice: 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.

	>Note: Work in progress...

	# 5.3 - SASL Bind

	SASL is defined by [RFC 4422](https://tools.ietf.org/html/rfc4422) which obsoletes [RFC2222](https://tools.ietf.org/html/rfc2222). There are also a few RFCs that are related to SASL, they are listed in the next paragraph.

	In any case, as ApacheDS and the Apache LDAP API are based on Java, we depend on the Java SASL impementation. Typically, this is handled by the SunSASL provider, which only support the following mechanisms, as of Java 8 :

	* PLAIN (Client)
	* CRAM-MD5 (Client/Server)
	* DIGEST-MD5 (Client/Server)
	* GSSAPI (Client/Server)
	* EXTERNAL (Client)

	Note that in Java 9, those mechanisms are spread in two different providers, the GSSAPI mechanism being handled by the JdkSASL provider.

	We currently don't support any other provider.

	## SASL Bind handling

	The SASL framework may require more than one BindRequest/BindResponse to be exchanched, as ther server may need more information from the client. The client must be ready to deal with such situation, by controling the resturned result : SASL_BIND_IN_PROGRESS means more is required.

	In any case, the client must send a first BindRequest with the proper information. We have dedicated methods to do so, based on the SASL mechanism to use :

	* bindSaslPlain() : PLAIN mechanism
	* bindSaslCramMd5() : CRAM-MD5 mechanism
	* bindSaslDigestMd5() : DIGEST-MD5 mechanism
	* bindSaslGssApi() : GSSAPI mechanism
	* bindSaslExternal() : EXTERNAL mechaism

	We don't support the SASL ANONYMOUS mechanism.

	There is also a more generic method that anyone can use with any mechanism, assuming we have a class implementing it :

	* bindSasl( Saslrequest )

	It's just about using an instance of a class extending the SaslRequest interface.


	Here is an example of a SASL bind, where we assume we have an entry which uid is "hnelson", and a userPassword which is "secret" (note that the password must be in clear text in the server) :

	:::java
	LdapNetworkConnection connection = new LdapNetworkConnection( Network.LOOPBACK_HOSTNAME, getLdapServer().getPort() );

	BindResponse resp = connection.bindSaslCramMd5( "hnelson", "secret" );
	assertEquals( ResultCodeEnum.SUCCESS, resp.getLdapResult().getResultCode() );



	## RFCs

	Here are the list of RFCs related to SASL:

	![](../../images/icons/information.gif) : Informational

	![](../../images/icons/lightbulb.gif) : Historic

	![](../../images/icons/lightbulb_on.gif) : Proposed Standard

	![](../../images/icons/warning.gif) : Experimental

	![](../../images/icons/thumbs_up.gif) : Best current practice


	### Obsolete RFCs

	\| RFC \| Description \| Obsoleted by \| Status \|
	\|---\|---\|---\|---\|
	\| [RFC 2222](https://tools.ietf.org/html/rfc2222) \| Simple Authentication and Security Layer (SASL) \| [RFC 4422](https://tools.ietf.org/html/rfc4422), [RFC 4752](https://tools.ietf.org/html/rfc4752) \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 2245](https://tools.ietf.org/html/rfc2245) \| Anonymous SASL Mechanism \| [RFC 4505](https://tools.ietf.org/html/rfc4505) \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 2831](https://tools.ietf.org/html/rfc2831) \| Using Digest Authentication as a SASL Mechanism \| [RFC 4505](https://tools.ietf.org/html/rfc4505) \| ![](../../images/icons/lightbulb.gif) \|
	\| [RFC 4013](https://tools.ietf.org/html/rfc4013) \| SASLprep: Stringprep Profile for User Names and Passwords \| [RFC 7613](https://tools.ietf.org/html/rfc7613)\| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 7613](https://tools.ietf.org/html/rfc7613) \| Preparation, Enforcement, and Comparison of Internationalized Strings Representing Usernames and Passwords \| [RFC 8265](https://tools.ietf.org/html/rfc8265) \| ![](../../images/icons/lightbulb_on.gif) \|

	### Active RFCs

	\| RFC \| Description \| Status \|
	\|---\|---\|---\|---\|
	\| [RFC 2444](https://tools.ietf.org/html/rfc2444) \| The One-Time-Password SASL Mechanism \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 2808](https://tools.ietf.org/html/rfc2808) \| The SecurID(r) SASL Mechanism \| ![](../../images/icons/information.gif) \|
	\| [RFC 4422](https://tools.ietf.org/html/rfc4422) \| Simple Authentication and Security Layer (SASL) \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 4505](https://tools.ietf.org/html/rfc4505) \| Anonymous Simple Authentication and Security Layer (SASL) Mechanism \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 4616](https://tools.ietf.org/html/rfc4616) \| The PLAIN Simple Authentication and Security Layer (SASL) Mechanism \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 4752](https://tools.ietf.org/html/rfc4752) \| The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 5801](https://tools.ietf.org/html/rfc58à&) \| Using Generic Security Service Application Program Interface (GSS-API) Mechanisms in Simple Authentication and Security Layer (SASL): The GS2 Mechanism Family \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 5802](https://tools.ietf.org/html/rfc5802) \| Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 6331](https://tools.ietf.org/html/rfc6331) \| Moving DIGEST-MD5 to Historic \| ![](../../images/icons/information.gif)\|
	\| [RFC 7677](https://tools.ietf.org/html/rfc7677) \| SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple Authentication and Security Layer (SASL) Mechanisms \| ![](../../images/icons/lightbulb_on.gif) \|
	\| [RFC 8265](https://tools.ietf.org/html/rfc8265) \| Preparation, Enforcement, and Comparison of Internationalized Strings Representing Usernames and Passwords \| ![](../../images/icons/lightbulb_on.gif) \|