|
Oracle® Identity Management Application Developer's Guide
10g Release 2 (10.1.2) B14087-02 |
|
 Previous |
 Next |
|
Oracle® Identity Management Application Developer's Guide
10g Release 2 (10.1.2) B14087-02 |
|
|
Previous |
Next |
This chapter introduces the Oracle extensions to the Java and PL/SQL LDAP APIs. Chapter 4 explains how the Java extensions are used. Chapter 5 is about the PL/SQL extensions. Oracle does not support extensions to the C API.
This chapter contains these topics:
Sample code is available at this URL:
http://www.oracle.com/technology/sample_code/
Look for the Oracle Identity Management link under Sample Applications–Oracle Application Server.
The APIs that Oracle has added to the existing APIs fulfill these functions:
User management
Applications can set or retrieve various user properties
Group management
Applications can query group properties
Realm management
Applications can set or retrieve properties about identity management realms
Server discovery management
Applications can locate a directory server in the Domain Name System (DNS)
SASL management
Applications can authenticate to the directory using SASL Digest-MD5
Subsequent sections examine each of these functions in detail. Note that applications must use the underlying APIs for such common tasks as establishing and closing connections and looking up directory entries not searchable with the API extensions.
Figure 3-1 shows what program flow looks like when the API extensions are used.
Figure 3-1 Programmatic Flow for API Extensions
As Figure 3-1 shows, an application first establishes a connection to Oracle Internet Directory. It can then use the standard API functions and the API extensions interchangeably.
Before an application can use the LDAP APIs and their extensions, it must establish an LDAP connection. Once it establishes a connection, it must have permission to perform operations. But neither task can be completed if the application lacks an identity in the directory.
Creating an application identity in the directory is relatively simple. Such an entry requires only two object classes: orclApplicationEntity and top. You can use either Oracle Directory Manager or an LDIF file to create the entry. In LDIF notation, the entry looks like this:
dn: orclapplicationcommonname=application_name changetype: add objectclass:top objectclass: orclApplicationEntity userpassword: password
The value provided for userpassword is the value that the application uses to bind to the directory.
To learn about the privileges available to an application, see the chapter about delegating privileges for an Oracle technology deployment in Oracle Internet Directory Administrator's Guide. After identifying the right set of privileges, add the application entity DN to the appropriate directory groups. The link just provided explains how to perform this task using either Oracle Directory Manager or the ldapmodify command.
This section describes user management features of the LDAP APIs.
Directory-enabled applications need to perform the following operations:
Retrieve properties of user entries
These properties are stored as attributes of the user entry itself—in the same way, for example, that a surname or a home address is stored.
Retrieve extended user preferences
These preferences apply to a user but are stored in a DIT different from the DIT containing user entries. Extended user preferences are either user properties common to all applications or user properties specific to an application. Those of the first type are stored in a common location in the Oracle Context. Those of the second type are stored in the application-specific DIT.
Query the group membership of a user
Authenticate a user given a simple name and credential
Typically an application uses a fully qualified DN, GUID, or simple user name to identify a user. In a hosted environment, the application may use both a user name and a realm name for identification.
Groups are modeled in Oracle Internet Directory as a collection of distinguished names. Directory-enabled applications must access Oracle Internet Directory to obtain the properties of a group and to verify that a given user is a member of that group.
A group is typically identified by one of the following:
A fully qualified LDAP distinguished name
A global unique identifier
A simple group name along with a subscriber name
An identity management realm is an entity or organization that subscribes to the services offered in the Oracle product stack. Directory-enabled applications must access Oracle Internet Directory to obtain realm properties such as user search base or password policy.
A realm is typically identified by one of the following:
A fully qualified LDAP distinguished name
A global unique identifier
A simple enterprise name
Directory server discovery (DSD) enables automatic discovery of the Oracle directory server by directory clients. It enables deployments to manage the directory host name and port number information in the central DNS server. All directory clients perform a DNS query at runtime and connect to the directory server. Directory server location information is stored in a DNS service location record (SRV).
An SRV contains:
The DNS name of the server providing LDAP service
The port number of the corresponding port
Any parameters that enable the client to choose an appropriate server from multiple servers
DSD also allows clients to discover the directory host name information from the ldap.ora file itself.
This section contains these topics:
|
See Also:
|
Typically, the LDAP host name and port information is provided statically in a file called ldap.ora which is located on the client in $ORACLE_HOME/network/admin. For large deployments with many clients, this information becomes very cumbersome to manage. For example, each time the host name or port number of a directory server is changed, the ldap.ora file on each client must be modified.
Directory server discovery eliminates the need to manage the host name and port number in the ldap.ora file. Because the host name information resides on one central DNS server, the information must be updated only once. All clients can then discover the new host name information dynamically from the DNS when they connect to it.
DSD provides a single interface to obtain directory server information without regard to the mechanism or standard used to obtain it. Currently, Oracle directory server information can be obtained either from DNS or from ldap.ora using a single interface.
The first step in discovering host name information is to create a discovery handle. A discovery handle specifies the source from which host name information will be discovered. In case of the Java API, the discovery handle is created by creating an instance of the oracle.ldap.util.discovery.DiscoveryHelper class.
DiscoveryHelper disco = new DiscoveryHelper(DiscoveryHelper.DNS_DISCOVER);
The argument DiscoveryHelper.DNS_DISCOVER specifies the source. In this case the source is DNS.
Each source may require some inputs to be specified for discovery of host name information. In the case of DNS these inputs are:
domain name
discover method
SSL mode
Detailed explanation of these options is given in "Determining Server Name and Port Number From DNS".
// Set the property for the DNS_DN disco.setProperty(DiscoveryHelper.DNS_DN,"dc=us,dc=fiction,dc=com"); // Set the property for the DNS_DISCOVER_METHOD disco.setProperty(DiscoveryHelper.DNS_DISCOVER_METHOD ,DiscoveryHelper.USE_INPUT_DN_METHOD); // Set the property for the SSLMODE disco.setProperty(DiscoveryHelper.SSLMODE,"0");
Now the information can be discovered.
// Call the discover method disco.discover(reshdl);
The discovered information is returned in a result handle (reshdl). Now the results can be extracted from the result handle.
ArrayList result =
(ArrayList)reshdl.get(DiscoveryHelper.DIR_SERVERS);
if (result != null)
{
if (result.size() == 0) return;
System.out.println("The hostnames are :-");
for (int i = 0; i< result.size();i++)
{
String host = (String)result.get(i);
System.out.println((i+1)+".'"+host+"'");
}
}
Determining a host name and port number from a DNS lookup involves obtaining a domain and then searching for SRV resource records based on that domain. If there is more than one SRV resource record, they are sorted by weight and priority. The SRV resource records contain host names and port numbers required for connection. This information is retrieved from the resourcerecords and returned to the user.
There are three approaches for determining the domain name required for lookup:
Mapping the distinguished name (DN) of the naming context
Using the domain component of local machine
Looking up the default SRV record in the DNS
The first approach is to map the distinguished name (DN) of naming context into domain name using the algorithm given here.
The output domain name is initially empty. The DN is processed sequentially from right to left. An RDN is able to be converted if it meets the following conditions:
It consists of a single attribute type and value
The attribute type is dc
The attribute value is non-null
If the RDN can be converted, then the attribute value is used as a domain name component (label).
The first such value becomes the rightmost, and the most significant, domain name component. Successive converted RDN values extend to the left. If an RDN cannot be converted, then processing stops. If the output domain name is empty when processing stops, then the DN cannot be converted into a domain name.
For the DN cn=John Doe,ou=accounting,dc=example,dc=net, the client converts the dc components into the DNS name example.net.
Sometimes a DN cannot be mapped to a domain name. For example, the DN o=Oracle IDC,Bangalore cannot be mapped to a domain name. In this case, the second approach uses the domain component of the local machine on which the client is running. For example, if the client machine domain name is mc1.acme.com, the domain name for the lookup is acme.com.
The third approach looks for a default SRV record in the DNS. This record points to the default server in the deployment. The domain component for this default record is _default.
Once the domain name has been determined, it is used to send a query to DNS. The DNS is queried for SRV records specified in Oracle Internet Directory-specific format. For example, if the domain name obtained is example.net, the query for non-SSL LDAP servers is for SRV resource records having the owner name _ldap._tcp._oid.example.net.
It is possible that no SRV resource records are returned from the DNS. In such a case the DNS lookup is performed for the SRV resource records specified in standard format. For example, the owner name would be _ldap._tcp.example.net.
|
See Also: The chapter about directory administration in Oracle Internet Directory Administrator's Guide |
The result of the query is a set of SRV records. These records are then sorted and the host information is extracted from them. This information is then returned to the user.
|
Note: The approaches mentioned here can also be tried in succession, stopping when the query lookup of DNS is successful. Try the approaches in the order as described in this section. DNS is queried only for SRV records in Oracle Internet Directory-specific format. If none of the approaches is successful, then all the approaches are tried again, but this time DNS is queried for SRV records in standard format. |
The following environment variables override default behavior for discovering a DNS server.
Table 3-1 Environment Variables for DNS Discovery
| Environment Variable | Description |
|---|---|
ORA_LDAP_DNS |
IP address of the DNS server containing the SRV records. If the variable is not defined, then the DNS server address is obtained from the host machine. |
ORA_LDAP_DNSPORT |
Port number on which the DNS server listens for queries. If the variable is not defined, then the DNS server is assumed to be listening at standard port number |
ORA_LDAP_DOMAIN |
Domain of the host machine. If the variable is not defined, then the domain is obtained from the host machine itself. |
The programming interface provided is a single interface to discover directory server information without regard to the mechanism or standard used to obtain it. Information can be discovered from various sources. Each source can use its own mechanism to discover the information. For example, the LDAP host and port information can be discovered from the DNS acting as the source. Here DSD is used to discover host name information from the DNS.
|
See Also: For detailed reference information and class descriptions, refer to the Javadoc located on the product CD. |
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.
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: Internet Engineering Task Force Web site, athttp://www.ietf.org
|
This section contains these topics:
Steps Involved in SASL Authentication by Using DIGEST-MD5
JAVA APIs for SASL Authentication by Using DIGEST-MD5
C APIs for SASL authentication using DIGEST-MD5
SASL Authentication by Using External Mechanism
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.
To use the Digest-MD5 authentication mechanism, you can use either the Java API or the C API to set up the authentication.
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.
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–Oracle Application Server.
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.
