8 Integrating with Oracle Delegated Administration Services

This chapter explains how to integrate applications with Oracle Delegated Administration Services. This Web tool enables you to more easily develop tools for administering application data in the directory.

It contains the following sections:

What Is Oracle Delegated Administration Services?
Integrating Applications with the Delegated Administration Services
Java APIs Used to Access URLs

8.1 What Is Oracle Delegated Administration Services?

Oracle Delegated Administration Services consists of a set of pre-defined, Web-based service units for performing directory operations on behalf of users. These units enable directory users to update their own information.

The delegated administration services provide most of the functionality that directory-enabled applications require. You can use the service units to create user and group entries, search for entries, and change user passwords.

You can embed delegated administration service units in your applications. If, for example, you are building a Web portal, you can add service units that enable users to change application passwords stored in the directory. Each service unit has a corresponding URL stored in the directory. At runtime, an application can find the URL by querying the directory.

Figure 8-1 Overview of Delegated Administration Services

8.1.1 How Applications Benefit from Oracle Delegated Administration Services

An application based on Oracle Delegated Administration Services is more advanced than one based on earlier types of APIs. First, an application developed using the service units is language independent because the units are Web based. This means that the application can handle input and requests from any type of user or application, eliminating the need for a costly custom solution or configuration. Second, Oracle Delegated Administration Services comes with the Oracle Internet Directory Self-Service Console, a GUI development tool that automates many of the directory-oriented application requirements (such as Create, Edit, and Delete). Third, Oracle Delegated Administration Services is integrated with Oracle Application Server Single Sign-On. The application is automatically authenticated by the single sign-on server. This means that the application can query the directory on a user's behalf.

8.2 Integrating Applications with the Delegated Administration Services

This section contains these topics:

Integration Profile
Integration Methodology and Considerations

8.2.1 Integration Profile

An application integrated with Oracle Delegated Administration Services has the following characteristics:

It is a Web-based GUI.
It is integrated with Oracle Application Server Single Sign-On through mod_osso.
It has operations that it must perform by way of a signed-on user. It can perform these operations using Oracle Delegated Administration Services.
It has users or groups stored in Oracle Internet Directory and can use Oracle Delegated Administration Services for user and group management.
It runs on the Oracle Application Server infrastructure or middle-tier. The discovery mechanism for the service URLs is inaccessible otherwise.

8.2.2 Integration Methodology and Considerations

Table 8-1 identifies the tasks that are required to integrate an application with Oracle Delegated Administration Services.

Table 8-1 Integration Considerations

Point in Application Lifecycle	Considerations
Application design time	Examine the various services that Oracle Delegated Administration Services provides. Identify integration points within the application GUI. Make code changes to pass parameters to the Oracle Delegated Administration Services self-service units and to process return parameters from Oracle Delegated Administration Services. Introduce code in the bootstrap and installation logic to dynamically discover the location of Oracle Delegated Administration Services units from configuration information in Oracle Internet Directory. To do this, use Oracle Internet Directory Service Discovery APIs.
Application installation time	Determine the location of Oracle Delegated Administration Services units and store them in local repository.
Application runtime	Display Oracle Delegated Administration Services URLs in application GUI shown to users. Pass the appropriate parameters to the Oracle Delegated Administration Services by using URL encoding. Process return codes from Oracle Delegated Administration Services through the URL return.
Ongoing administrative activities	Provide the capability to refresh the location of Oracle Delegated Administration Services and its URLs in the administrator screens. Do this in case the deployment moves the location of Oracle Delegated Administration Services after the application has been installed.

Use Case 1: Create User

This use case shows how to integrate the Create User unit with a custom application. In the custom application page, Create User is shown as a link.

Identify the base URL for Oracle Delegated Administration Services by using this Java API string:
```
baseUrl = Util.getDASUrl(ctx,DASURL_BASE)
```
This API returns the base URL in this form: http://host_name:port/

Get the URL for the Create Userunit by using this string:
```
relUrl = Util.getDASUrl ( ctx , DASURL_CREATE_USER )
```
The return value is the relative URL to access the Create User unit.

The specific URL is the information needed to generate the link dynamically for the application.

You can customize the parameters in Table 8-2 for this unit.

Table 8-2 URL Parameters for Oracle Delegated Administration Services

Parameter	Description
`homeURL`	The URL that is linked to the global button Home in the Oracle Delegated Administration Services unit. When the calling application specifies this value, you can click Home to redirect the Oracle Delegated Administration Services unit to the URL specified by this parameter.
`doneURL`	This URL is used by Oracle Delegated Administration Services to redirect the Oracle Delegated Administration Services page at the end of each operation. In the case of Create User, once the user is created, clicking OK redirects the URL to this location.
`cancelURL`	This URL is linked with all the Cancel buttons shown in Oracle Delegated Administration Services units. Any time the user clicks Cancel, the page is redirected to the URL specified by this parameter.
`enablePA`	This parameter takes a Boolean value of true or false. This will enable the Assign Privileges section in a User or Group operation. If `enablePA` is passed with value of true in the Create User page, then the Assign Privileges to User section will also appear on the Create User Page.

Build the link with the parameters set to the following values:

baseUrl = http://acme.mydomain.com:7777/
relUrl =  oiddas/ui/oracle/ldap/das/admin/AppCreateUserInfoAdmin
homeURL = http://acme.mydomain.com/myapp
cancelURL = http://acme.mydomain.com/myapp
doneURL = http://acme.mydomain.com/myapp
enablePA = true

The complete URL looks like this:

http://acme.mydomain.com:7777/oiddas/ui/oracle/ldap/das/admin/
AppCreateUserInfoAdmin?homeURL=http://acme.mydomain.com/myapp& cancelURL=http://acme.mydomain.com/myapp&
doneURL=http://acme.mydomain.com/myapp&
enablePA=true

You can now embed this URL in the application.

Use Case 2: User LOV

List of Values (LOV) is implemented using JavaScript to invoke and pass values between the LOV calling window and the LOV page. The application invoking the LOV needs to open a popup window using JavaScript. Because Java scripts have security restrictions, no data may cross domains. Due to this limitation, only pages in the same domain can access the LOV units.

Base and relative URLs can be invoked the same way as they are for Create User. Sample files are located at:

$ORACLE_HOME/ldap/das/samples/lov

The samples illustrate how the LOV can be invoked and data can be passed between the calling application and the Oracle Delegated Administration Services unit. A Complete illustration of the LOV invocation is beyond the scope of this chapter.

8.3 Java APIs Used to Access URLs

Java APIs can be used to discover URLs for Oracle Delegated Administration Services. More details about these APIs are provided in Chapter 3, "Developing Applications with Oracle Extensions to the Standard APIs" and in Chapter 15, "DAS_URL Interface Reference". The API functions that address URL discovery are getDASUrl(DirContext ctx, String urlTypeDN) and getAllDASUrl(DirContext ctx).