Not all of the features described in this document must be supported by an LDAP service provider. However, if a feature is supported, it should be supported in the way described by this document.
There are four types of environment properties that affect LDAP service providers:
In particular, if any of the following properties is not supplied in the environment properties then it is sought from the system properties, applet parameters, and both provider and application resource files (in that order):
A context's environment properties can be examined using the Context.getEnvironment method.
When a property is removed from the environment properties of a context, the context assumes the default behavior specified for that property. This does not necessarily mean that the default value must be recorded as the property's value. The removal may also be indicated by the absence of the property from the context's environment properties.
The value of this property is a string of decimal digits that specifies the batch size of search results returned by the server.
This property affects the blocking behaviour of the Context.list, Context.listBindings, and DirContext.search methods and the NamingEnumeration objects that they return. It does not affect how many items are returned in the enumeration; it only affects how the items are batched or read at the LDAP protocol level.
A setting of zero means that the provider should block until all results have been received. A setting of an integer n greater than zero means that the provider should block until n results have been received from the server or until the enumeration terminates, whichever produces the fewer number of results. After the application has read n results (using NamingEnumeration.next or NamingEnumeration.nextElement), the provider should read n more results from the server or until the enumeration terminates, whichever produces the fewer number of results.
If this property is not set then its default value is implementation-specific.
For example, the following code specifies that the provider should block until 24 entries have been read from the server or until the enumeration terminates, whichever produces the fewer number of results:
env.put(Context.BATCHSIZE, "24");
The value of this property is a colon-separated list of fully qualified class names of control factory classes.
The factories are responsible for narrowing the class of response controls. They create specific response controls from the generic response controls generated by the provider.
No default value is defined for this property.
For example, the following code sets the ResponseControlFactory class as the control factory to try:
env.put(LdapContext.CONTROL_FACTORIES, "com.sun.jndi.ldap.ctl.ResponseControlFactory");
The value of this property is the fully qualified class name of the factory class which creates the initial context for the LDAP service provider.
It is used to select a particular LDAP service provider; it's not actually used by the provider itself. This property need not be set when the name argument to initial context methods is a URL.
No default value is defined for this property.
For example, the following code selects Sun's LDAP provider:
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
The value of this property is a colon-separated list of fully qualified class names of object factory classes.
The factories are responsible for creating specific objects from the LDAP entries returned by the provider. For example, a Person object factory might generate a Person object from an LDAP entry of object class person. Object factories behave in the opposite way to state factories in that they generate objects from LDAP attributes.
No default value is defined for this property.
For example,
env.put(Context.OBJECT_FACTORIES, "com.sun.jndi.ldap.obj.PersonFromLDAP");sets the PersonFromLDAP class as the object factory to try.
The value of this property is a colon-separated list of fully qualified class names of state factory classes.
The factories are responsible for creating an object's state (for storing) from the object itself. For example, a Person state factory might generate an LDAP entry of object class person from a Person object. State factories behave in the opposite way to object factories in that they generate LDAP attributes from objects.
No default value is defined for this property.
For example,
env.put(Context.STATE_FACTORIES, "com.sun.jndi.ldap.obj.PersonToLDAP");
sets the PersonToLDAP class as the state factory to try.
The value of this property is a string language tag according to RFC 1766.
env.put(Context.LANGUAGE, "ja-JP");
The value of this property is a list of space-separated LDAP or LDAPS URL strings, each of which specifies the hostname and port number of the LDAP server, and the root distinguished name of the naming context to use. An LDAP URL specifies the use of a plain (i.e., unprotected) connection; an LDAPS URL specifies the use of an SSL connection. If the list contains more than one URL, the provider should attempt to use each URL in turn until it is able to create a successful connection, and after creation, set the property to the successful URL.
The default hostname is localhost; the default port is 389 for plain connections and 636 for SSL connections. The default root distinguished name is the empty string. If this property is not set, or if either the hostname or port number is omitted, then the default values are used in place of the missing information. If both the hostname and port are missing but a non-empty distinguished name is present in the URL, then the provider should use the distinguished name to determine the hostname and port of the LDAP server(s) as described in the URLs section and when a connection has been established successfully, set the java.naming.provider.url property to a URL constructed using the successful hostname, port and distinguished name. See also the URLs section for information on how the provider should treat other information found in the URL.
For example:
env.put(Context.PROVIDER_URL, "ldap://secserver:636");specifies that the LDAP server is running on a host named secserver at port 636.
NOTE: Changing this property using the Context.addToEnvironment or Context.removeFromEnvironment methods does not affect the context. It is only used by the initial context constructors.
The value of this property is a string that specifies how referrals shall be handled by the provider. The following values are defined for this property:
See the URLs section for information on how to treat multiple URLs found in a single referral entry.
If this property is not set then its default value is ignore.
For example:
env.put(Context.REFERRAL, "throw");
The value of this property is a string that specifies the authentication mechanism(s) for the provider to use. The following values are defined for this property:
See the SASL section for information on how this property is used for SASL authentication. See RFC 2829 for information on LDAP authentication mechanisms.
If this property is not set then its default value is none, unless the java.naming.security.credentials property is set, in which case the default value is simple. If this property is set to a value that the provider does not recognize or support, it should throw AuthenticationNotSupportedException.
For example:
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_AUTHENTICATION, "DIGEST-MD5 CRAM-MD5");
env.put(Context.SECURITY_CREDENTIALS, "secret");
The value of this property is a string that specifies the identity of the principal to be authenticated. Its format depends on the authentication type; see RFC 2829 for more information. The value is used as the name component in an LDAP ASN.1 BindRequest for non-SASL authentication. For SASL authentication, the value of this property is used as the authentication ID for SASL mechanisms that need an authentication ID.
The provider is not required to verify the validity of the principal name. It may, for example, just pass the string to be verified by the server. If the principal identified is not a valid principal then the provider shall throw an AuthenticationException.
No default value is defined for this property.
For example:
env.put(Context.SECURITY_PRINCIPAL, "cn=admin,o=sun,c=us");
sets the principal name to be the distinguished name "cn=admin, o=sun, c=us".
If this property is set to ssl, the provider must use SSL sockets, or throw ConfigurationException if it is unable to do so. In addition to the value listed above, a provider may support other security protocols. However, such provider-specific protocols might not be supported by all providers. If this property is set to a security protocol that the provider does not recognize or support, it should throw ConfigurationException.
If the java.naming.ldap.factory.socket property is set, then the socket factory identified by that property must create sockets that are appropriate for this protocol setting. For example, if the security protocol is set to ssl, then the socket factory must create SSL-compliant sockets.
If this property is not set then the default is to use no security protocol.
As a developer of the LDAP provider, you should be aware that using SSL to connect to a server on a port that is not listening for SSL connections causes the socket to hang. Similarly, using a plain socket to connect to a server that is listening for SSL connections also leads to hanging. This is a characteristic of the protocol that some implementations may choose to correct but is not otherwise required to do so. The provider's documentation, however, should describe this behavior to its users. See SSL for information on how to use SSL.
For example:
env.put(Context.SECURITY_PROTOCOL, "ssl");
| Attribute ID | OID | Reference |
|---|---|---|
| Any attribute ID with the ";binary" option. | ||
| photo | 0.9.2342.19200300.100.1.7 | RFC 1274 |
| personalSignature | 0.9.2342.19200300.100.1.53 | RFC 1274 |
| audio | 0.9.2342.19200300.100.1.55 | RFC 1274 |
| jpegPhoto | 0.9.2342.19200300.100.1.60 | RFC 2798 |
| javaSerializedData | 1.3.6.1.4.1.42.2.27.4.1.7 | RFC 2713 |
| thumbnailPhoto | 2.16.128.113533.1.1400.1 | NAC LIP Schema |
| thumbnailLogo | 2.16.128.113533.1.1400.2 | NAC LIP Schema |
| userPassword | 2.5.4.35 | RFC 2256 |
| userCertificate | 2.5.4.36 | RFC 2256 |
| cACertificate | 2.5.4.37 | RFC 2256 |
| authorityRevocationList | 2.5.4.38 | RFC 2256 |
| certificateRevocationList | 2.5.4.39 | RFC 2256 |
| crossCertificatePair | 2.5.4.40 | RFC 2256 |
| x500UniqueIdentifier | 2.5.4.45 | RFC 2256 |
env.put("java.naming.ldap.attributes.binary",
"mpegVideo myspecialkey");
env.put("java.naming.ldap.control.connect",
new Control[]{ new ManageReferralControl(true) });
For example:
env.put("java.naming.ldap.deleteRDN", "false");
The value of this property is a string that specifies how aliases are dereferenced during search operations. The following values are defined for this property:
env.put("java.naming.ldap.derefAliases", "searching");
NOTE: this property is unrelated to the dereference-links flag in the SearchControls object.
env.put("java.naming.ldap.factory.socket",
"javax.net.ssl.SSLSocketFactory");
env.put("java.naming.ldap.ref.separator", ":");
env.put("java.naming.ldap.referral.limit", "5");
If this property is not set then its default value is false.
For example:
env.put("java.naming.ldap.typesOnly", "true");
If this property is not set then the provider first attempts to bind using LDAP v3 and fails over to using LDAP v2 if a protocol error is received from the server. This failover mechanism is only used when the java.naming.security.authentication property indicates anonymous bind or simple authentication.
For example:
env.put("java.naming.ldap.version", "2");
java.naming.security.sasl.authorizationId
The value of this property is a string that specifies the authorization ID for the SASL mechanisms.
If this property is not set, then the authorization ID passed to the SASL mechanisms is the empty string. According to SASL (RFC 2222), using an authorization ID of the empty string directs the server to derive an authorization ID from the client's authentication credentials.
For example:
env.put("java.naming.security.sasl.authorizationId",
"dn:cn=administrators,ou=groups,o=sun,c=us");
specifies the identity to use for authorization (access control) upon successful authentication.
java.naming.security.sasl.realm
The value of this property is a string that specifies the realm information required by some SASL mechanisms such as DIGEST-MD5.
If this property is not set, then a mechanism-specific default such as that negotiated between the client and server during the authentication exchange is used.
For example:
env.put("java.naming.security.sasl.realm", "webusers");
specifies that the client wants to use the "webusers" realm for authentication.
java.naming.security.sasl.callback
The value of this property is an instance of javax.security.auth.callback.CallbackHandler. When the provider uses a SASL mechanism that requires callbacks, the SASL mechanism uses the object supplied in the property. The callback handler should satisfy a NameCallback by supplying the authentication ID.
If this property is not set, then the provider should use a default callback handler that satisfies the NameCallback using the value of the java.naming.security.principal property, satisfies the PasswordCallback using the value of the java.naming.security.credentials property, and satisfies the RealmCallback and RealmChoiceCallback (described in the Java SASL API) using the value of the java.naming.security.sasl.realm property.
For example:
env.put("java.naming.security.sasl.callback",
new MyCallbackHandler());
supplies an instance of the callback handler for SASL mechanisms to use.
The value of this property is a ','-separated list of quality-of-protection (qop) values used to specify the client's qop preference. A qop value is one of
The value of this property is a ','-separated list of cipher strength values used to specify the client's preference. A strength value is one of
For privacy in DIGEST-MD5, "high" maps to "3des", "medium" to "rc4" or "des", and "low" to "rc4-56" or "rc4-40".
The value of this property is the string representation of an integer that specifies the maximum size of the receive buffer in bytes that the client is willing to receive. If this property is absent, the default size is defined by the SASL mechanism.
The value of this property is either "true" or "false", specifying whether the server must authenticate to the client or not, respectively. If this property is absent, the default is "false".
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must support forward secrecy between sessions or not, respectively. If this property is absent, the default is "false".
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must require client credentials or not, respectively. If this property is absent, the default is "false".
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to simple plain passive attacks or not, respectively. If this property is absent, the default is "false".
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to active (non-dictionary) attacks or not, respectively. If this property is absent, the default is "false".
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to dictionary attacks or not, respectively. If this property is absent, the default is "false".
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not accept anonymous logins or not, respectively. If this property is absent, the default is "false".
The name supplied to an LDAP context is always relative to that context. For example, given an LDAP context (lctx) for "dc=widget,dc=com", in order to name LDAP entries in that subtree, a name relative to "dc=widget,dc=com" must be supplied. For example, the following call obtains the attributes for the "cn=John Smith,dc=widget,dc=com" entry.
Attributes attrs = lctx.getAttributes("cn=John Smith");
Similarly, when a context is enumerated using any of the enumeration methods (Context.list, Context.listBindings, DirContext.search), the names returned are relative to the target context--the context being enumerated. When referrals are invoked, instead of a relative name, an LDAP or LDAPS URL string containing the fully qualified name is returned. (If the enumeration was performed using a plain connection, an LDAP URL string is returned; if it was done using an SSL connection, an LDAPS URL string is returned.) The format of LDAP URLs is defined in RFC 2255.
LDAP URLs that follow RFC 2255 and LDAPS URLs may be supplied to any of the context methods. The hostname and port number are extracted from the URL and used to contact the LDAP server; the URL's scheme ("ldap" or "ldaps") is used to determine whether a plain or SSL connection is used. The java.naming.factory.initial and java.naming.provider.url properties are ignored. For example,
DirContext ictx = new
InitialDirContext();
Attributes attrs =
ictx.getAttributes(
"ldap://wserver:389/cn=John Smith,dc=widget,dc=com");
This code fragment contacts the LDAP server at machine wserver at port 389 using a plain connection.
The LDAP provider expects as input and returns as output all attribute values as either String or byte[] objects. See the java.naming.ldap.attributes.binary environment property for which ones are treated as byte[] and how to extend the list.
ldap://host:port/dn?attributes?scope?filter?extensions
Authentication information may be specified in the extensions portion of the URL. See the RFC for a complete description of the format.
In addition to LDAP URLs, the provider may also support the non-standard but widely used LDAPS URLs. LDAPS URLs use SSL connections instead of plain (i.e., unprotected) connections. They have a syntax similar to LDAP URLs except the schemes are different and the default port for LDAPS URLs is 636 instead of 389.
ldaps://host:port/dn?attributes?scope?filter?extensions
URLs play a role in several places in JNDI:
With the exception of the search methods, when an LDAP or LDAPS
URL is passed as a name to the initial context, the URL should
not contain any query ('?') components. Otherwise,
an InvalidNameException is thrown by the service provider.
For the search methods, the query components of the URL override
any corresponding components supplied as arguments. For example, if
an LDAP URL containing a scope component is supplied, then that
scope overrides any scope setting that may be passed in a
SearchControls argument.
References, referenceable and serializable objects should be stored according to RFC 2713. DirContext objects should be stored by storing their attributes.
When storing a reference's list of RefAddr into the javaReferenceAddress attribute, the separator to use for delimiting the address's position, type and content are controlled using the environment property java.naming.ldap.ref.separator. If this environment property is not specified, the hash character '#' should be used as the separator.
The provider uses the DirectoryManager.getStateToBind method when storing objects in the directory. This allows objects of any type to be transformed into one of the four categories listed above so that they can be stored into the directory.
Permission to modify the contents of the schema tree is determined by the directory administrator. When the schema tree is modified, the changes are made to schema stored on the directory server.
| Name of Binding | Description of Binding |
|---|---|
| AttributeDefinition | Root of the attribute definition tree: a flat namespace with attributes identified by their name or OID. |
| ClassDefinition | Root of the "objectclass" definition tree: a flat namespace with object classes identified by their name or OID. |
| SyntaxDefinition | Root of the syntax definition tree: a flat namespace with syntaxes identified by their OID. |
| MatchingRule | Root of matching rule tree: a flat namespace with matching rules identified by their name or OID. |
| ExtensionDefinition | Root of the extensions tree: a flat namespace with extensions identified by their OID. |
| ControlDefinition | Root of the controls tree: a flat namespace with controls identified by their OID. |
| SASLMechanism | Root of the SASL tree: a flat namespace with SASL authentication mechanisms identified by their string name. |
Any or all of these bindings may be absent if the underlying directory does not publish such schema information, or the service provider does not support retrieving them. If these names are present in the root schema context, however, they must have the binding specified in the above table.
The attribute names and values of these entries' attributes are
case-insensitive.
Each object in the "AttributeDefinition" context has the
following mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NUMERICOID (mandatory) | unique identifier (OID) |
| NAME | attribute's name |
| DESC | attribute's description |
| OBSOLETE | "true" if obsolete, "false" or absent otherwise |
| SUP | name of superior attribute type from which this attribute's type is derived |
| EQUALITY | name or OID of matching rule if equality matching allowed, absent otherwise |
| ORDERING | name or OID of matching rule if ordering matching allowed, absent otherwise |
| SUBSTRING | name or OID of matching rule if substring matching allowed, absent otherwise |
| SYNTAX | numeric OID of syntax of values of this type |
| SINGLE-VALUE | "true" if attribute not multi-valued, "false" or absent otherwise. |
| COLLECTIVE | "true" if attribute is collective, "false" or absent otherwise. |
| NO-USER-MODIFICATION | "true" if not user-modifiable, "false" or absent otherwise. |
| USAGE | description of attribute usage |
These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "AttributeTypeDescription." All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the "cn" attribute using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext cnSchema = schema.lookup("AttributeDefinition/cn");
If you then get the attributes of the "cnSchema" DirContext object, you would see:
NUMERICOID 2.5.4.3 NAME cn SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 DESC Standard Attribute, alias for commonName
An equivalent way of getting "cnSchema" is if you already have a "cn" attribute. The following code illustrates this alternative:
Attributes attrs = ctx.getAttributes("cn=John", new String[]{"cn"});
Attribute cnAttr = attrs.get("cn");
DirContext cnSchema = cnAttr.getAttributeDefinition();
Each object in the "ClassDefinition" context has the following
mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NUMERICOID (mandatory) | unique identifier (OID) |
| NAME | object class's name |
| DESC | object class's description |
| OBSOLETE | "true" if obsolete, "false" or absent otherwise |
| SUP | name of superior object class from which this object class is derived |
| ABSTRACT | "true" if object class is abstract, "false" or absent otherwise |
| STRUCTURAL | "true" if object class is structural, "false" or absent otherwise |
| AUXILIARY | "true" if object class is auxiliary, "false" or absent otherwise |
| MUST | a list of type names of attributes that must be present |
| MAY | a list of type names of attributes that may be present |
These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "ObjectClassDescription." All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the "country" object class using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext countrySchema = schema.lookup("ClassDefinition/country");
If you then get the attributes of the "countrySchema" DirContext object, you would see:
NUMERICOID 2.5.6.2 NAME country MAY aci, searchguide, description MUST objectclass, c DESC Standard ObjectClass SUP top
An equivalent way of getting "countrySchema" is if you already have a "country" object. The following code illustrates this alternative:
// Read object from directory
DirContext countryObj = (DirContext)ctx.lookup("c=us", new String[]{"country"});
// Get all of object's object class definitions
DirContext objClasses = countryAttr.getSchemaClassDefinition();
// Pick out "country" object class in particular
DirContext countryClass = (DirContext)objClasses.lookup("country");
NOTE: JNDI 1.1's specification of
getSchemaClassDefinition() implies that the service
provider should return any one of an object's object class
definitions. This specification is inadequate because an object
usually has multiple object classes and the application might
require knowledge about any of those object classes depending on
what it is doing. The proposal as illustrated by the example above
is to return a context containing all of the object class
definitions.
Each object in "SyntaxDefinition" context has the following
mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NUMERICOID (mandatory) | unique identifier (OID) |
| DESC | syntax's description |
These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "SyntaxDescription." All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the "1.3.6.1.4.1.1466.115.121.1.15" syntax using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext dirStringSchema =
schema.lookup("SyntaxDefinition/1.3.6.1.4.1.1466.115.121.1.15");
If you then get the attributes of the "dirStringSchema" DirContext object, you would see:
NUMERICOID 1.3.6.1.4.1.1466.115.121.1.15 DESC Directory String
An equivalent way of getting "dirStringSchema" is if you already have an attribute that has that syntax (such as, the "country" attribute). The following code illustrates this alternative:
Attributes attrs = ctx.getAttributes("c=us", new String[]{"country"});
Attribute countryAttr = attrs.get("country");
DirContext dirStringSchema = countryAttr.getSyntaxAttributeDefinition();
When a matching rule is an extensible matching rule, it must also contain an "APPLIES" attribute listing the attributes to which this extensible matching rule can be applied.
Each object in "MatchingRule" context has the following
mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NUMERICOID (mandatory) | unique identifier (OID) |
| NAME | name of matching rule |
| DESC | matching rule's description |
| OBSOLETE | "true" if obsolete, "false" or absent otherwise |
| SYNTAX | numeric oid of syntax to which this rule applies |
| APPLIES | a list type names of attributes to which this extensible matching rule applies |
These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "MatchingRuleDescription" and "MatchingRuleUseDescription." All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the "soundAlikeMatch" syntax using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext soundMatchSchema =
schema.lookup("MatchingRule/soundAlikeMatch");
If you then get the attributes of the "soundMatchSchema" DirContext object, you would see:
NUMERICOID 1.2.3.4.5 NAME soundAlikeMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 (for directory string) APPLIES 2.5.4.41, 2.5.4.15 DESC Home-grown Phonetic match
Each object in "ExtensionDefinition" context has the following
mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NUMERICOID (mandatory) | unique identifier (OID) |
| DESC | extension's description |
All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the Start TLS extension ("1.3.6.1.4.1.1466.20037") using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext startTLSSchema =
schema.lookup("ExtensionDefinition/1.3.6.1.4.1.1466.20037");
If you then get the attributes of the "startTLSSchema" DirContext object, you would see:
NUMERICOID 1.3.6.1.4.1.1466.20037 DESC Start TLS (see RFC 2830)
Each object in "ControlDefinition" context has the following
mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NUMERICOID (mandatory) | unique identifier (string) |
| DESC | control's description |
All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the server-side sorting control ("1.2.840.113556.1.4.473") using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext svrSortSchema =
schema.lookup("ControlDefinition/1.2.840.113556.1.4.473");
If you then get the attributes of the "svrSortSchema" DirContext object, you would see:
NUMERICOID 1.2.840.113556.1.4.473 DESC server-side sorting of search results
Each object in "SASLMechanism" context has the following
mandatory and optional attributes:
| Attribute Identifier | Attribute Value Description |
|---|---|
| NAME (mandatory) | SASL mechanism's name |
| DESC | SASL mechanism's description |
All the attribute values are represented by the java.lang.String class.
You can, for example, obtain the object representing the EXTERNAL SASL mechanism using the following code:
DirContext schema = ctx.getSchema(""); // get schema tree
DirContext saslExternalSchema =
schema.lookup("SASLMechanism/EXTERNAL");
If you then get the attributes of the "saslExternalSchema"
DirContext object, you would see:
NAME EXTERNAL DESC EXTERNAL SASL mechanism (RFC 2222)
| LDAP error code | Exception or Action |
|---|---|
| success (0) | Report success. |
| operationsError (1) | NamingException |
| protocolError (2) | CommunicationException |
| timeLimitExceeded (3) | TimeLimitExceededException |
| sizeLimitExceeded (4) | SizeLimitExceededException |
| compareFalse (5) | Used by DirContext.search() and does not generate an exception. |
| compareTrue (6) | Used by DirContext.search() and does not generate an exception. |
| authMethodNotSupported (7) | AuthenticationNotSupportedException |
| strongAuthRequired (8) | AuthenticationNotSupportedException |
| partialResults (9) | If java.naming.referral is set to ignore, or contents of error does not contain a referral, throw PartialResultException. Otherwise, use the contents to build a referral. |
| referral (10) | If java.naming.referral is set to ignore then throw PartialResultException. If it is set to throw then throw ReferralException. If it is set to follow then the provider shall follow the referral. If the value for java.naming.ldap.referral.limit is exceeded while following the referral then throw LimitExceededException. |
| adminLimitExceeded (11) | LimitExceededException |
| unavailableCriticalExtension (12) | OperationNotSupportedException |
| confidentialityRequired (13) | AuthenticationNotSupportedException |
| saslBindInProgress (14) | Used internally by LDAP provider during multi-stage SASL authentication. |
| noSuchAttribute (16) | NoSuchAttributeException |
| undefinedAttributeType (17) | InvalidAttributeIdentifierException |
| inappropriateMatching (18) | InvalidSearchFilterException |
| constraintViolation (19) | InvalidAttributeValueException |
| attributeOrValueExists (20) | AttributeInUseException |
| invalidAttributeSyntax (21) | InvalidAttributeValueException |
| noSuchObject (32) | NameNotFoundException |
| aliasProblem (33) | NamingException |
| invalidDNSyntax (34) | InvalidNameException |
| isLeaf (35) | Used by provider; usually doesn't generate exception. |
| aliasDereferencingProblem (36) | NamingException |
| inappropriateAuthentication (48) | AuthenticationNotSupportedException |
| invalidCredentials (49) | AuthenticationException |
| insufficientAccessRights (50) | NoPermissionException |
| busy (51) | ServiceUnavailableException |
| unavailable (52) | ServiceUnavailableException |
| unwillingToPerform (53) | OperationNotSupportedException |
| loopDetect (54) | NamingException |
| namingViolation (64) | InvalidNameException |
| objectClassViolation (65) | SchemaViolationException |
| notAllowedOnNonLeaf (66) | ContextNotEmptyException |
| notAllowedOnRDN (67) | SchemaViolationException |
| entryAlreadyExists (68) | NameAlreadyBoundException |
| objectClassModsProhibited (69) | SchemaViolationException |
| affectsMultipleDSAs (71) | NamingException |
| other (80) | NamingException |
Update context's environment properties. If multiple contexts share the same set of environment properties, the provider should take care to only modify the intended context's environment. Changing an environment property might require changes to the existing connection the context is using.
Remove context's environment properties. If multiple contexts share the same set of environment properties, the provider should take care to only modify the intended context's environment. Changing an environment property might require changes to the existing connection the context is using.
In the forms of search that accept a string filter as argument, the syntax of the filter follows RFC 2254 with the exception that Unicode characters are also allowed. The use of Unicode characters is preferable to the use of encoded UTF-8 octets. The service provider is responsible for translating the Unicode characters into their corresponding UTF-8 representation for transmission to the server. For example, the Greek letter alpha can be specified in the string filter either as "\u03B1" or as "\\CE\\B1".
In the form search(Name, Attributes) and related methods, the Attributes argument is converted into a string filter by creating a conjunctive expression out of its elements. Each attribute value is treated as a literal; therefore '*' and other special characters defined in RFC 2254 that appear in the values of an attribute should be escaped according to the rules in RFC 2254. For example, an attribute value of '*' should be encoded as the string "\\2a".
In the form search(Name, String filterExpr, Object[] filterArgs) and its String overloaded method, "{num}" expansion is done in the filter by putting in values from filterArgs. Each "{num}" component may appear in the place of "attr" or "value" in Section 4 from RFC 2254.
The objects in filterArgs should be encoded in the
following way:
The Java SASL API depends on the Java Authentication and Authorization Service (JAAS), which provides callback support for SASL mechanisms that need to obtain or supply user/application information directly.
Some SASL mechanisms require the identity of the entity being authenticated. This is known as the authentication ID. Some SASL mechanisms, like DIGEST-MD5, require the use of a password and/or a realm. By default, the provider supplies the value of java.naming.security.principal property as the authentication ID to any SASL mechanism that requires the authentication ID, the value of the java.naming.security.credentials property as the password, and the value of the java.naming.security.sasl.realm property as the realm. To override these defaults, use the java.naming.security.sasl.callback property.
SASL mechanisms support the notion of authorization identity or authorization ID, which is the entity to which the server should grant access if the authentication succeeds. If the java.naming.security.sasl.authorizationId property has been set, then its value is used as the authorization ID. Otherwise, the empty string is used as the authorization ID, which directs the server to derive an authorization ID from the client's authentication credentials.
See SASL properties for a description of the properties used by an LDAP service provider for supporting SASL.
In addition to these properties, there might be properties required for specific SASL mechanisms. For example, a SASL mechanism that supports privacy and integrity needs to know the quality of protection that the client requires. Properties such as these are passed to the SASL mechanism via the environment properties. See the JNDI documentation for how to set environment properties.
For example, if the application needs privacy, it can do so by using a call such as:
env.put("javax.security.sasl.qop", "auth-conf");
before passing env to the initial context constructor. See the Java SASL API for details about these properties.
Several LDAP extensions and controls are defined by the IETF LDAPEXT working group.
The "Start TLS" extension ("1.3.6.1.4.1.1466.20037") is supported by the StartTlsRequest and StartTlsResponse classes. The LDAP provider must provide a concrete implementation of the abstract StartTlsResponse class and make its implementation available to the LDAP provider. See the description in StartTlsRequest.createExtendedResponse. Typically, the StartTlsResponse implementation would need access to the LDAP provider's data structures.
The LDAP service provider should perform hostname verification after Start TLS negotiation as specified in RFC 2830. If the LDAP server was discovered automatically by using information in DNS (as described in the URLs section), the provider should use the domain name derived from the distinguished name as the hostname to verify, as recommended by draft-ietf-ldapext-locate-08.txt.
A JNDI application can register for events that occur in the directory, such as the addition or removal of an entry, or the modification of an entry. Applications can also register for unsolicited notifications.
The provider supports SSL according to the Java Secure Socket Extension (JSSE) specification. SSL is activated by setting the java.naming.security.protocol environment property as follows:
env.put(Context.SECURITY_PROTOCOL, "ssl");and by selecting the hostname and port number of an LDAP server that supports SSL. Once an SSL connection has been established subsequent LDAP protocol exchanges take place over that secure connection.
If, in addition, LDAP authentication is also required then the java.naming.security.authentication, java.naming.security.principal, and java.naming.security.credentials environment properties should be set, as appropriate. If LDAP authentication is required and the SSL credentials should be reused for LDAP authentication then set the java.naming.security.authentication environment property to select the SASL EXTERNAL mechanism, as follows:
env.put(Context.SECURITY_AUTHENTICATION,
"EXTERNAL");
