| Oracle® Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01 |
|
|
View PDF |
| Oracle® Identity Management Application Developer's Guide 10g (10.1.4.0.1) Part Number B15997-01 |
|
|
View PDF |
This chapter describes extensions to the LDAP protocol that are available in Oracle Internet Directory 10g (10.1.4.0.1).
This chapter contains these topics:
Oracle Internet Directory supports two mechanisms for SASL-based authentication. This section describes the two methods. It contains these topics:
SASL Authentication by Using the DIGEST-MD5 Mechanism
SASL Authentication by Using External Mechanism
SASL Digest-MD5 authentication is the required authentication mechanism for LDAP Version 3 servers (RFC 2829). LDAP Version 2 does not support Digest-MD5.
To use the Digest-MD5 authentication mechanism, you can use either the Java API or the C API to set up the authentication. The C API supports only auth mode.
|
See Also:
|
The SASL Digest-MD5 mechanism includes three modes, each representing a different security level or "Quality of Protection." They are:
auth—Authentication only. Authentication is required only for the initial bind. After that, information is passed in clear text.
auth-int—Authentication plus integrity. Authentication is required for the initial bind. After that, check sums are used to guarantee the integrity of the data.
auth-conf—Authentication plus confidentiality. Authentication is required for the initial bind. After that, encryption is used to protect the data. Five cipher choices are available:
DES
3DES
RC4
RC4-56
RC4-40
These are all symmetric encryption algorithms.
Prior to 10g (10.1.4.0.1), Oracle Internet Directory supported only the auth mode of the Digest-MD5 mechanism. As of 10g (10.1.4.0.1), Oracle Internet Directory supports all three modes with the Java Naming and Directory Interface (JNDI) of jdk1.4 API or with the OpenLDAP Java API. The Oracle LDAP SDK supports only auth mode.
Out of the box, Oracle Internet Directory SASL Digest-MD5 authentication supports generation of static SASL Digest-MD5 verifiers based on user or password, but not based on realm. If you want to use SASL Digest-MD5 with realms, you must enable reversible password generation by changing the value of the orclpasswordencryptionenable attribute to 1 in the related password policy before provisioning new users. The LDIF file for modifying the value should look like this:
dn: cn=default,cn=pwdPolicies,cn=Common,cn=Products,cn=OracleContext changetype: modify replace: orclpwdencryptionenable orclpwdencryptionenable: 1
The Digest-MD5 mechanism is described in RFC 2831 of the Internet Engineering Task Force. It is based on the HTTP Digest Authentication (RFC 2617).
|
See Also:
|
SASL Digest-MD5 authenticates a user as follows:
The directory server sends data that includes various authentication options that it supports and a special token to the LDAP client.
The client responds by sending an encrypted response that indicates the authentication options that it has selected. The response is encrypted in such a way that proves that the client knows its password.
The directory server then decrypts and verifies the client's response.
The following is from section 7.4 of RFC 2222 of the Internet Engineering Task Force.
The mechanism name associated with external authentication is "EXTERNAL". The client sends an initial response with the authorization identity. The server uses information, external to SASL, to determine whether the client is authorized to authenticate as the authorization identity. If the client is so authorized, the server indicates successful completion of the authentication exchange; otherwise the server indicates failure.
The system providing this external information may be, for example, IPsec or SSL/TLS.
If the client sends the empty string as the authorization identity (thus requesting the authorization identity be derived from the client's authentication credentials), the authorization identity is to be derived from authentication credentials that exist in the system which is providing the external authentication.
Oracle Internet Directory provides the SASL external mechanism over an SSL mutual connection. The authorization identity (DN) is derived from the client certificate during the SSL network negotiation.
The LDAPv3 Protocol, as defined by RFC 2251, allows extensions by means of controls. Oracle Internet Directory supports several controls. Some are standard and described by RFCs. Other controls, such as the CONNECT_BY control for hierarchical searches are Oracle-specific. You can use controls with either Java or C.
Controls can be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls. The LDAP API also supports a client-side extension mechanism through the use of client controls. These controls affect the behavior of the LDAP API only and are never sent to a server.
For information about using LDAP controls in C, see "Working With Controls".
For information about using LDAP controls in Java, see the documentation for the JNDI package javax.naming.ldap at http://java.sun.com/products/jndi.
The following controls are supported by Oracle Internet Directory 10g (10.1.4.0.1):
Table 3-1 Controls Supported by Oracle Internet Directory
| Object Identifier | Name | Description |
|---|---|---|
|
2.16.840.1.113730.3.4.2 |
GSL_MANAGE_DSA_CONTROL |
Used to manage referrals, dynamic groups, and alias objects in Oracle Internet Directory. For more information, please see RFC 3296, "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories," at |
|
2.16.840.1.113894.1.8.1 |
OID_RESET_PROXYCONTROL_IDENTITY |
Used to perform a proxy switch of an identity on an established LDAP connection. For example, suppose that Application A connects to the directory server and then wishes to switch to Application B. It can simply do a rebind by supplying the credentials of Application B. However, there are times when the proxy mechanism for the application to switch identities could be used even when the credentials are not available. With this control, Application A can switch to Application B provided Application A has the privilege in Oracle Internet Directory to proxy as Application B. |
|
2.16.840.1.113894.1.8.2 |
OID_APPLYUSEPASSWORD_POLICY |
Sent by applications that require Oracle Internet Directory to check for account lockout before sending the verifiers of the user to the application. If Oracle Internet Directory detects this control in the verifier search request and the user account is locked, then Oracle Internet Directory will not send the verifiers to the application. It will send an appropriate password policy error. |
|
2.16.840.1.113894.1.8.3 |
CONNECT_BY |
|
|
2.16.840.1.113894.1.8.4 |
OID_CLIENT_IP_ADDRESS |
Intended for a client to send the end user IP address if IP lockout is to be enforced by Oracle Internet Directory. |
|
2.16.840.1.113894.1.8.5 |
GSL_REQDATTR_CONTROL |
Used with dynamic groups. Directs the directory server to read the specific attributes of the members rather than the membership lists. |
|
2.16.840.1.113894.1.8.6 |
OID_PASSWORD_REQUEST_CONTROL |
Password policy control. Request control that the client sends to get a response from the server. |
|
2.16.840.1.113894.1.8.7 |
OID_PASSWORD_EXPWARNING_CONTROL |
Password policy control. Response control that the server sends when the pwdExpireWarning attribute is enabled and the client sends the request control. The response control value contains the time in seconds to password expiration. |
|
2.16.840.1.113894.1.8.8 |
OID_PASSWORD_GRACELOGIN_CONTROL |
Password policy control. The response control that the server sends when grace logins are configured and the client sends a request control. The response control value contains the remaining number of grace logins. |
|
2.16.840.1.113894.1.8.9 |
OID_PASSWORD_MUSTCHANGE_CONTROL |
Password policy control. The response control that the server sends when forced password reset is enabled and the client sends the request control. The client must force the user to change the password upon receipt of this control. |
|
2.16.840.1.113894.1.8.14 |
OID_DYNAMIC_VERIFIER_REQUEST_CONTROL |
The request control that the client sends when it wants the server to create a dynamic password verifier. The server uses the parameters in the request control to construct the verifier. |
|
2.16.840.1.113894.1.8.15 |
OID_DYNAMIC_VERIFIER_RESPONSE_CONTROL |
The response control that the server sends to the client when an error occurs. The response control contains the error code. |
|
2.16.840.1.113894.1.8.16 |
OID_APPLYALLPWDPOLICIES_CONTROL |
If this control is included in a verifier search request, all password policies that are applicable to the user are applied to the verifier search. |
|
2.16.840.1.113894.1.8.23 |
GSL_CERTIFICATE_CONTROL |
Certificate search control. The request control that the client sends to specify how to search for a user certificate. |
|
1.2.840.113556.1.4.473 |
OID_SEARCH_SORTING_REQUEST_CONTROL |
|
|
1.2.840.113556.1.4.319 |
OID_SEARCH_PAGING_CONTROL |
To find out what controls are available in your Oracle Internet Directory installation, type:
ldapsearch -p port -b "" -s base "objectclass=*"
Look for entries that begin with supportedcontrol=.
Often applications must perform operations that require impersonating an end user. An application may, for example, want to retrieve resource access descriptors for an end user. (Resource access descriptors are discussed in the concepts chapter of Oracle Internet Directory Administrator's Guide.)
A proxy switch occurs at run time on the JNDI context. An LDAP v3 feature, proxying can only be performed using InitialLdapContext, a subclass of InitialDirContext. If you use the Oracle extension oracle.ldap.util.jndi.ConnectionUtil to establish a connection (the example following), InitialLdapContext is always returned. If you use JNDI to establish the connection, make sure that it returns InitialLdapContext.
To perform the proxy switch to an end user, the user DN must be available. To learn how to obtain the DN, see the sample implementation of the oracle.ldap.util.User class at this URL:
http://www.oracle.com/technology/sample_code/
Look for the Oracle Identity Management link under Sample Applications—Fusion Middleware, then look for "Sample Application Demonstrating Proxy Switching using Oracle Internet Directory Java API."
This code shows how the proxy switch occurs:
import oracle.ldap.util.jndi.*;
import javax.naming.directory.*;
import javax.naming.ldap.*;
import javax.naming.*;
public static void main(String args[])
{
try{
InitialLdapContext appCtx=ConnectionUtil.getDefaultDirCtx(args[0], // host
args[1], // port
args[2], // DN
args[3]; // pass)
// Do work as application
// . . .
String userDN=null;
// assuming userDN has the end user DN value
// Now switch to end user
ctx.addToEnvironment(Context.SECURITY_PRINCIPAL, userDN);
ctx.addToEnvironment("java.naming.security.credentials", "");
Control ctls[] = {
new ProxyControl()
};
((LdapContext)ctx).reconnect(ctls);
// Do work on behalf of end user
// . . .
}
catch(NamingException ne)
{
// javax.naming.NamingException is thrown when an error occurs
}
}
The ProxyControl class in the code immediately preceding implements a javax.naming.ldap.Control. To learn more about LDAP controls, see the LDAP control section of Oracle Identity Management User Reference. Here is an example of what the ProxyControl class might look like:
import javax.naming.*;
import javax.naming.ldap.Control;
import java.lang.*;
public class ProxyControl implements Control {
public byte[] getEncodedValue() {
return null;
}
public String getID() {
return "2.16.840.1.113894.1.8.1";
}
public boolean isCritical() {
return false;
}
}
You can modify the LDAP authentication APIs to generate application passwords dynamically—that is, when users log in to an application. This feature has been designed to meet the needs of applications that provide parameters for password verifiers only at runtime.
This section contains the following topics:
Creating a password verifier dynamically involves modifying the LDAP authentication APIs ldap_search or ldap_modify to include parameters for password verifiers. An LDAP control called DynamicVerifierRequestControl is the mechanism for transmitting these parameters. It takes the place of the password verifier profile used to create password verifiers statically. Nevertheless, dynamic verifiers, like static verifiers, require that the directory attributes orclrevpwd (synchronized case) and orclunsyncrevpwd (unsynchronized case) be present and that these attributes be populated.
Note that the orclpwdencryptionenable attribute of the password policy entry in the user's realm must be set to 1 if orclrevpwd is to be generated. If you fail to set this attribute, an exception is thrown when the user tries to authenticate. To generate orclunsyncrevpwd, you must add the crypto type 3DES to the entry cn=defaultSharedPINProfileEntry,cn=common,cn=products,cn=oraclecontext.
The request control looks like this:
DynamicVerifierRequestControl
controlOid: 2.16.840.1.113894.1.8.14
criticality: FALSE
controlValue: an OCTET STRING whose value is the BER encoding of the following type:
ControlValue ::= SEQUENCE {
version [0]
crypto [1] CHOICE OPTIONAL {
SASL/MD5 [0] LDAPString,
SyncML1.0 [1] LDAPString,
SyncML1.1 [2] LDAPString,
CRAM-MD5 [3] LDAPString },
username [1] OPTIONAL LDAPString,
realm [2] OPTIONAL LDAPString,
nonce [3] OPTIONAL LDAPString,
}
Note that the parameters in the control structure must be passed in the order in which they appear. Table 3-2 defines these parameters.
Table 3-2 Parameters in DynamicVerifierRequestControl
| Parameter | Description |
|---|---|
controlOID |
The string that uniquely identifies the control structure. |
crypto |
The hashing algorithm. Choose one of the four identified in the control structure. |
username |
The distinguished name (DN) of the user. This value must always be included. |
realm |
A randomly chosen realm. It may be the identity management realm that the user belongs to. It may even be an application realm. Required only by the SASL/MD5 algorithm. |
nonce |
An arbitrary, randomly chosen value. Required by SYNCML1.0 and SYNCML1.1. |
Table 3-3 lists the four hashing algorithms that are used to create dynamic password verifiers. The table also lists the parameters that each algorithm uses as building blocks. Note that, although all algorithms use the user name and password parameters, they differ in their use of the realm and nonce parameters.
Applications that require password verifiers to be generated dynamically must include DynamicVerifierRequestControl in their authentication APIs. Either ldap_search or ldap_compare must incorporate the controlOID and the control values as parameters. They must BER-encode the control values as shown in "Syntax for DynamicVerifierRequestControl"; then they must send both controlOID and the control values to the directory server.
If you want the application to authenticate the user, use ldap_search to pass the control structure. If ldap_search is used, the directory passes the password verifier that it creates to the client.
ldap_search must include the DN of the user, the controlOID, and the control values. If the user's password is a single sign-on password, the attribute passed is authpassword. If the password is a numeric pin or another type of unsynchronized password, the attribute passed is orclpasswordverifier;orclcommonpin.
If you want Oracle Internet Directory to authenticate the user, use ldap_compare to pass the control structure. In this case, the directory retains the verifier and authenticates the user itself.
Like ldap_search, ldap_compare must include the DN of the user, the controlOID, the control values, and the user's password attribute. For ldap_compare, the password attribute is orclpasswordverifier;orclcommonpin (unsynchronized case).
When it encounters an error, the directory sends the LDAP control DynamicVerifierResponseControl to the client. This response control contains the error code. To learn about the error codes that the response control sends, see the troubleshooting chapter in Oracle Internet Directory Administrator's Guide.
If you want the directory to create password verifiers dynamically, you must add your application identity to the VerifierServices group of directory administrators. If you fail to perform this task, the directory returns an LDAP_INSUFFICIENT_ACCESS error.
One of the server controls you can pass to an LDAP search function is CONNECT_BY. This is an Oracle-specific control that causes the search to traverse a hierarchy. For example, if you search for all the users in group1, without the CONNECT_BY control, the search function will return only users who are direct members of group1. If you pass the CONNECT_BY control, however, the search function will traverse the hierarchy. If group2 is a member of group1, the search will also return users in group2. If group3 is a member of group2, the search will also return users in group3, and so forth.
In 10g (10.1.4.0.1), the CONNECT_BY control has been enhanced in two ways:
You can now traverse the hierarchy in either direction. That is, you can search through all containers in which an entry is contained, as well as through all containers contained within an entry.
You can now specify the number of levels of the hierarchy to search.
In previous releases, the CONNECT_BY control required no values. Because of the new functionality, you can now pass one or both of the following values to CONNECT_BY:
Hierarchy-establishing attribute–A string representing the attribute to be searched. This value is necessary only when searching through all containers in which an entry is contained. When searching through containers contained within an entry, you need not provide this value because the search filter provides that information.
Number of levels–An integer representing the number of levels to traverse. If the value is 0, the search will traverse all levels. The default value is 0, so you need not pass this value if you want the search to traverse all leve.s
Example 1: Find All the Groups to Which a User Belongs
Using a filter such as (member=cn=jsmith), you do not need to provide the hierarchy-establishing attribute member because it is in the search filter. You do not need to pass a value for the number of levels because 0 is the default.
Example 2: Find Only the Groups to Which a User Directly Belongs
Using the same filter as in Example 1, you would pass the integer control value 1. The result would be the same as if you did not use the CONNECT_BY control at all.
Example 3: Find All Members of a Group
In this case, your search filter would specify (objectclass=*), but if you want to find all members of group1, the attribute for traversing the hierarchy is member. For this search, you must pass the string "member" as the hierarchy-establishing attribute. You do not need to pass a value for the number of levels because 0 is the default.
Example 4: Finding all Managers of a User
This is similar to Example 3, except that you want to find all managers of the user jsmith, so manager is the attribute for traversing the hierarchy. For this search, you would pass the string "manager". You do not need to pass a value for the number of levels because 0 is the default.
As of Oracle Internet Directory 10g (10.1.4.0.1), you can obtain sorted results from an LDAP search, as described by IETF RFC 2891. You request sorted results by passing a control of type 1.2.840.113556.1.4.473 to the search function. The server returns a response control is of type 1.2.840.113556.1.4.474. Error processing and other details are described in RFC 2891.
|
See Also: IETF RFC 2891, "LDAP Control Extension for Server Side Sorting of Search Results," athttp://www.ietf.org. |
Sorting and paging may be used together.
The Oracle Internet Directory implementation of RFC 2891 has the following limitations:
It supports only one attributeType in the control value.
It uses the default ordering rule defined in the schema for each attribute.
Linguistic sorting is not supported.
The default sorting order is ascending.
If a sort key is a multi-valued attribute, and an entry has multiple values for that attriute, and there are no other controls that affect the sorting order, then the server uses the least value, according to the ordering rule for that attribute.
The sort attribute must be searchable. That is, it must be a cataloged attribute in Oracle Internet Directory.
As of Oracle Internet Directory 10g (10.1.4.0.1), you can obtain paged results from an LDAP search, as described by IETF RFC 2696. You request sorted results by passing a control of type 1.2.840.113556.1.4.319 to the search function. Details are described in RFC 2696.
|
See Also: IETF RFC 2696, "LDAP Control Extension for Simple Paged Results Manipulation," athttp://www.ietf.org. |
Sorting and paging may be used together.
The Oracle Internet Directory implementation of RFC 2696 has the following limitations:
The number of entries in a page might be less than the page size if an ACI partially blocks some entries from the search results.
The paging response control does not contain the total entry count estimation. The return value is always 0.
