Oracle® Fusion Middleware Application Developer's Guide for Oracle Identity Management 11g Release 1 (11.1.1) E10186-02 |
|
![]() Previous |
![]() Next |
This chapter introduces the Oracle extensions to the Java and PL/SQL LDAP APIs. Chapter 5 explains how the Java extensions are used. Chapter 6 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—Fusion Middleware.
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)
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 4-1 shows what program flow looks like when the API extensions are used.
Figure 4-1 Programmatic Flow for API Extensions
As Figure 4-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. After 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 Services 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 Fusion Middleware Administrator's Guide for Oracle Internet Directory. After identifying the right set of privileges, add the application entity DN to the appropriate directory groups. The reference just provided explains how to perform this task using either Oracle Directory Services 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 is 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.example.com
, the domain name for the lookup is example.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
.
After 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
.
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 4-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. |