|Oracle® Access Manager Developer Guide
Part Number B25346-01
IdentityXML provides a programmatic interface for carrying out the actions that a user can perform when accessing an Identity System application from a browser. For instance, a program can send an IdentityXML request to find members of a group defined in the Group Manager application, or to add a user to the User Manager. This chapter describes how to create IdentityXML requests and the process for submitting the requests and handling the responses from the Identity System.
The Web Services Description Language (WSDL) is a schematic description of an XML request. You can use the Identity System's WSDL files as input for generating IdentityXML requests. This chapter describes how you can use the Identity System's WSDL solution as an automated method of generating IdentityXML requests.
Universal Description, Discovery, and Integration (UDDI) is a registry (analogous to the White Pages or Yellow Pages) that enables users to access Web services that are created using WSDL. The Identity System's UDDI and WSDL features together constitute the Web Services for Identity Management.
The chapter contains the following sections:
IdentityXML provides a programmatic interface for carrying out the actions that a user can perform when accessing an Identity System application from a browser. Instead of interacting with the application through a browser, you can write a program. For example, if your company moves and you need to change the area code for the phone number of 100,000 employees, you can use IdentityXML to do a bulk update. Or, if you regularly add employees, instead of doing double entry between your Human Resources application and the Identity System, you can write a script to call an IdentityXML function to create new users in the User Manager, taking the data from the Human Resources application.
Figure 1-1 illustrates how IdentityXML works:
IdentityXML enables you to process simple actions and multi-step workflows to change user, group, and organization object profiles.
IdentityXML enables external applications to access these Identity System functions:
User: Create, delete, and manage user data within or outside of a workflow or an asynchronous workflow.
Group: Create, delete, and manage groups and subscriptions.
Organization: Create, delete, and manage organization object data.
To create an IdentityXML request, you look up the request syntax, function names and parameters using the information in this chapter and in "IdentityXML Functions and Parameters". After creating the IdentityXML request, you construct a SOAP wrapper to send the IdentityXML request to WebPass using HTTP. Figure 1-2 illustrates how IdentityXML requests are processed:
IdentityXML requests only work with LDAP attributes that are used on a panel in the User, Group, or Organization Manager.
The IdentityXML API uses XML over SOAP. As shown in Figure 1-2, you pass IdentityXML parameters to the Identity Server using an HTTP request. This HTTP request contains a SOAP envelope. When WebPass receives the HTTP request, the SOAP envelope indicates that it is an IdentityXML request rather than the usual browser request. The request is forwarded to the Identity Server, where the request is carried out and a response is returned. Alternatively, you can use WSDL to construct the SOAP request.
Data that is sent in a response to an IdentityXML request is similar to the XML output that the Identity System combines with a style sheet to create the HTML that is returned to a browser. You must parse the XML response to extract and use the information you requested.
See also:For a listing of IdentityXML functions and parameters, see "IdentityXML Functions and Parameters".
A number of IdentityXML samples are provided with your Oracle Access Manager installation. While these samples are not supported, they can provide you with an idea of how specific functions are specified. For a look at the samples, go to:
Implementing an IdentityXML request requires the procedures identified in the following task overview.
Decide what Identity System operation you want to perform; see the Oracle Access Manager Identity and Common Administration Guide for more information.
Read "IdentityXML Functions and Parameters" to find the function name and parameters that correspond to the operation that you want to perform.
Ensure that the IdentityXML request works with LDAP attributes that are configured on a panel in the User, Group, or Organization Manager.
See the Oracle Access Manager Identity and Common Administration Guide for details.
Develop the IdentityXML request and the SOAP envelope for the request, as described in this chapter.
Write a program to send an HTTP/S request to the Identity System.
The program can be written in any language. The HTTP/S request must contain an XML payload that consists of the IdentityXML request that you created. You can write a Java program or a Perl script to send the request to a Web server that understands SOAP requests.
The program or script will do the following:
Identify the host that is responsible for sending the request.
Read in the file that contains the IdentityXML request.
Identify the port to send the data to (port 80).
Identify the cgi that the IdentityXML is being sent to, for example, userservcenter.cgi for the User Manager.
The cgi files are described in "Locations for Each Application".
Create a program to parse the XML response and perform any additional processing required.
The Identity System traps the XML request and returns output in the form of an XML document. You need to parse and process this document.
Note:WSDL provides a method for submitting IdentityXML requests through a Java proxy object. This may be more convenient for some developers than the method outlined in the previous paragraphs. See for "Creating IdentityXML Requests Using WSDL".
Note that each IdentityXML file contains a single request consisting of a single operation. In all likelihood, you will want to use IdentityXML to perform repetitive tasks. For example, suppose that you implement an IdentityXML solution to update an employee's home address. You may want to re-use this information for subsequent employee address updates. To do this, you need to update the data in the IdentityXML file and resend the request.
You can write a shell or Perl script to dynamically update the data in the IdentityXML request. The script can take information from the original data source and substitute this data in the IdentityXML file that you have set up. This is how, for instance, you could ensure that information about new users entered in your Human Resources database is automatically translated into a Create User operation in the Identity System.
The IdentityXML syntax is compatible with WSDL and UDDI. See "Creating IdentityXML Requests Using WSDL" for details.
Example 1–1 shows the request format:
Example 1-1 IdentityXML Request Format
<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:oblix="http://www.oblix.com" xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <oblix:authentication type="basic"> <oblix:login>login name</oblix:login> <oblix:password>login password</oblix:password> </oblix:authentication> <oblix:request application="application name" function="function name" version="NPWSDL1.0"> <oblix:params> <oblix:param1>value1</oblix:param1> <oblix:param2>value2</oblix:param2> <oblix:param3>value3</oblix:param3> </oblix:params> </oblix:request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Note:This chapter describes the latest syntax for IdentityXML. This syntax is optimized for use with WSDL and has been in use since version 6.5. The older syntax is deprecated, however, code that uses the old syntax will continue to work.
Documentation of the earlier IdentityXML syntax is available on the Oracle Technology Network at:
XML must start with the following string:
Within this required string you can use a tag to select an encoding specification. Without the encoding string, the default encoding specification is UTF-8.
10g (10.1.4.0.1) supports two encoding formats for requests: ISO-8859-1 (Latin-1) and UTF-8. The response, however, will be in UTF-8 encoding only.
With new 10g (10.1.4.0.1) installations, use the UTF-8 encoding tag (
encoding="UTF-8"), as follows.
<?xml version="1.0" encoding="UTF-8" ?>
For backward compatability with older plug-ins in an upgraded environment, use the Latin-1 encoding tag (
encoding="ISO-8859-1"). For example:
<?xml version="1.0" encoding="ISO-8859-1" ?>
The required SOAP tag starts the SOAP root element, the envelope:
<SOAP-ENV:Envelope> xmlns:oblix="http://www.oblix.com" xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">
It is closed by the
</SOAP-ENV:Envelope> tag. The namespace attribute
xmlns:oblix enables the use of Identity System-specific tags in the envelope element.
This tag starts the body of the SOAP envelope:
It is closed by the
</SOAP-ENV:Body> tag. The body contains two SOAP elements: authentication information and request information.
This required element specifies the authentication type to be used:
Currently, basic authentication is the only supported type. This means that the Oracle Access Manager login ID and password are needed for authentication. The
</oblix:authentication> tag closes this element.
For servers in an Active Directory forest, you need to specify the login domain as well as the login and password. You do this by specifying a <oblix:domain> element within the <oblix:authentication> tag.
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic"> <oblix:login>user1k1</oblix:login> <oblix:password>abc</oblix:password> <oblix:domain> DC=locations,DC=oblix,DC=com </oblix:domain> </oblix:authentication>
The login tag:
provides the login ID for an Oracle Access Manager user.
The password tag:
provides the actual password of an Oracle Access Manager user.
If your HTTP client can receive and resend the Access System single sign-on cookie, you only need to include the authentication element for the first request in a session. This can reduce the overhead incurred by multiple logins. For an example, see the cookie settings in the sample Java code in "ObSSOCookie Example". If you submit the single sign-on cookie as part of the HTTP(S) request, change the IPValidation setting on the WebGate which protects the WebPass that processes the IdentityXML request. Disable IPValidation for the IP address where the request originates. This is usually the Web server hosting the application that submits the IdentityXML request.
There are special considerations if you use both of the following types of request:
IdentityXML requests that use the SSO cookie on behalf of applications that perform an action for an SSO-authenticated user.
IdentityXML requests that use Basic authentication for applications that use credentials for privileged operations such as Identity Event API IdentityXML calls.
If your environment supports both types of request, you may require one or more dedicated WebGates and WebPasses for the SSO IdentityXML requests and a separate set of WebGates and WebPasses for the Basic authentication requests.
The request line:
<oblix:request application="application name" function="function name" mode = "modename" version="NPWSDL1.0">
tells the Identity System the function to use for the request, for example, search. You replace function name with the accurately spelled and capitalized name of the function in double quotation marks. A list of functions starts at "Common Functions".
The application name can be one of the following:
groupservcenter: For Group Manager functions.
objservcenter: For Organization Manager functions.
asynch: For asynchronous workflows.
You specify the application to send the request to by inputting the correct URL. See "Locations for Each Application" and the function descriptions starting with "Common Functions" for information on the correct application URL to use with each function.
You can optionally limit the output from this function by providing mode="modename" in the request tag. Modename takes one of two values.
silent: Returns status information, but no other output. This is useful for IdentityXML functions that test access. The returned status is 0 if the function succeeded, 1 otherwise. To use silent mode, add the following in the line that begins with <oblix:request>:
<oblix:request application="userservcenter" function="view" mode="silent">
dataonly: Omits display information from the output. The default mode returns all display-related elements in the XML output, including buttons, forms, and so on. Dataonly mode eliminates display-related elements to minimize the size of the output XML.
<oblix:request application="userservcenter" function="view" mode="dataonly">
Note:For the IdentityXML parameter viewGroupMembers, some user interface information is included in the output even in data only mode.
version: The version tag is required:
Documentation of the pre-6.5 IdentityXML version tag is available on the Oracle Technology Network at:
Delimits a list of parameter name:value pairs. Note the keyword is params, plural. The tag
</oblix:params> closes this element. The params tag may be replaced by other tags, depending on the parameters being invoked. See "Search Parameters" and "Attribute Parameters" for details.
Each occurrence of this element provides a specific parameter name:value pair. You replace param1 with the parameter name in quotes. Replace value1 with the actual value. An example:
<oblix:param name="uid"> cn=Marketing Team, ou=Marketing, o=Company, c=US </oblix:param>
Note that this older syntax is supported if you have legacy IdentityXML files (pre-NetPoint 6.5). Refer to the documentation for the appropriate version of the product for details.
The method for specifying a parameter is as follows:
<oblix:uid> cn=Marketing Team, ou=Marketing, o=Company, c=US </oblix:uid>
This method is required for use with the WSDL and UDDI functionality. Parameters for each function are described starting with "Common Functions".
You can supply more than one parameter:value pair:
Example 1–2 illustrates an IdentityXML function to change a password. Key words of interest are shown in bold:
Example 1-2 Sample Change Password Request
<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/" xmlns:oblix="http://www.oblix.com"> <SOAP-ENV:Body> <oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic"> <oblix:login>dadmin</oblix:login> <oblix:password>password</oblix:password> </oblix:authentication> <oblix:request application="userservcenter" function="modifyUser" mode="" version="NPWSDL1.0"> <oblix:attributeParams> <oblix:uid>uid=jones,ou=People,ou=NA,ou=DEALER,dc=company,dc=com</oblix:uid> <oblix:PasswordAttribute> <oblix:attrName>userPassword</oblix:attrName> <oblix:attrNewValue>password</oblix:attrNewValue> <oblix:attrConfirmValue>password</oblix:attrConfirmValue> <oblix:attrOldValue>d</oblix:attrOldValue> <oblix:attrOperation>REPLACE</oblix:attrOperation> <oblix:attrNoOfFields">1</oblix:attrNoOfFields> </oblix:PasswordAttribute> </oblix:attributeParams> </oblix:request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
In the previous examples:
oblix:authentication: This is the authentication tag that enables the user to log in.
oblix:attributeParams: The uid identifies the user whose password is to be changed.
attrName: This identifies the names of one or more attributes to be viewed or changed.
attrNewValue: This identifies the value that is to be provided for the attribute identified by the attrName parameter.
Example 1-3 shows an IdentityXML function that performs a query. This query asks if the logged in user has permission to view a particular group profile. This request might be sent to the User Manager at the following URL:
Oracle Access Manager first authenticates John Smith as a valid user, and verifies that the user is authorized to do a password change. The Identity System searches the User Manager for all entries under the Employees tab that have john as a substring match in their cn attribute. Because mode="silent" is part of the request, the response only contains status information.
Example 1–3 illustrates an IdentityXML request.
Example 1-3 Sample IdentityXML Request
<?xml version="1.0"?> <SOAP-ENV:Envelope . . . </oblix:authentication> <oblix:request function="search" mode="silent" version="NPWSDL1.0"> <oblix:Params> <oblix:tab_id>Employees</oblix:tab_id> <oblix:SearchParams> <oblix:Condition> <oblix:SearchAttr>cn</oblix:SearchAttr> <oblix:SearchOperation>OSM</oblix:SearchOperation> <oblix:SearchString>john</oblix:SearchString> </oblix:Condition> </oblix:SearchParams> </oblix:Params> </oblix:request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Note:As shown in Example 1-3, you must set the version string to NPWSDL1.0. For example, myrequest.setVersion("NPWSDL1.0");.
In an XML document, if you want special characters, such as the angle bracket "<" to be treated as text, they must be encoded. The following table summarizes the handling of special characters in XML:
|>||Begins a tag.||>|
|<||Ends a tag.||<|
The applications that respond to IdentityXML input and the files that they use are as follows.
URLs to the applications are as follows:
The schema files are as follows:
XML schema documentation files:
UDDI sample Java files:
The style sheets are as follows (see also the Oracle Access Manager Customization Guide):
Group Manager, Organization Manager, User Manager:
Asynchronous Workflows: none
There are three types of IdentityXML functions:
Test: These functions test whether the user is allowed to perform a particular function. Test functions can be used before doing large scale batch operations. Test functions return a yes or no type of response.
Get: These functions show current directory content.
Set: These functions change current directory content.
All functions are listed in "IdentityXML Functions and Parameters" . Note that parameters for these functions can be specified in any order. You do not need to follow the order provided in the parameter descriptions.
Use IdentityXML test functions to determine if you or another user can perform a specific function. Functions that begin with CanI are a direct (first-person) test. Functions that begin with CanUser are an indirect (third-person) test. These functions ask "may user J. Smith do something." A third person test is also called a proxy test. You identify the person who is the target of the test using the proxysourceuid parameter.
Example 1–4 is an example test request.
Example 1-4 Test Request Example
<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:oblix="http://www.oblix.com" xmlns:SOAP-ENV="http: //schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <oblix:authentication type="basic"> <oblix:login>J.Smith</oblix:login> <oblix:password>J.Smith</oblix:password> </oblix:authentication> <oblix:request function="canIViewGroupProfile" version="NPWSDL1.0"> <oblix:AttrParams> <oblix:uid> cn=Marketing Team,ou=Marketing,o=Company,c=US </oblix:uid> </oblix:AttrParams> </oblix:request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
The result of the request appears as the value in an ObTextMessage element, within the ObAccessAPIResult element. There are three possible results.
Allowed: You or the specified user may do the requested activity.
Denied: You or the specified user may not do the requested activity.
Not authorized to use service: You lack the rights necessary to make the request, as described in "Privileges to View and Modify".
Example 1-5 is an example test response.
Note:10g (10.1.4.0.1) supports two encoding formats: ISO-8859-1 and UTF-8 for these requests. You can continue to send requests as Latin-1 data with ISO-8859-1 encoding. However, the response will be in UTF-8 encoding only.
Example 1-5 Test Response Example
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:oblix="http://www.oblix.com" xmlns:SOAP-ENV="http:// schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <Oblix> <ObAccessAPIResult> <ObRequestInfo>187658080</ObRequestInfo> <ObTextMessage>Allowed</ObTextMessage> </ObAccessAPIResult> </Oblix> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Some IdentityXML functions gather and return information from the directory. For functions that get data for a logged in user, the user must have view privileges for the target object naming attribute and the specified attribute.
Example 1-6 is an example of a request for workflow ticket information.
Example 1-6 Request for Workflow Ticket Information
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http:// schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <oblix:authentication xmlns:oblix="http:// www.oblix.com" type="basic"> <oblix:login>J.Smith</oblix:login> <oblix:password>J.Smith</oblix:password> </oblix:authentication> <oblix:request function="workflowTicketInfo" version="NPWSDL1.0"> <oblix:AttrParams> <oblix:workflowInstanceDn> obwfinstanceid=20001019T1609090, obcontainerId=workflowInstances, o=Oblix,o=Company,c=US </oblix:workflowInstanceDn> <oblix:workflowStepInstanceId> 2 </oblix:workflowStepInstanceId> <oblix:AttrParams> </oblix:request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
These functions change directory content.
For functions that allow a user to set data for themselves:
The user must have view privileges for the target object naming attribute.
For a workflow or a request to set an attribute, the logged in user must have view privileges for the target object naming attribute and the attribute requested to be set, and the user must be a participant of the appropriate workflow.
For a workflow or request to delete a user, group, or object, the logged in user must have view access to the target object naming attribute and be a participant of the appropriate workflow.
For a workflow or request to create a user, group or object, the searchbase rule does not apply. If a domain is specified the logged in user must be a participant of the matching workflows for that target domain. If no domain is specified, the logged in user must be a participant of any matching workflows.
For functions that allow a logged in user to set data for another user:
All of the privileges that allow a user to set data for themselves must apply to the proxysourceuid (that is, the user in the "CanUser. . ." call).
The logged in user must have view privileges for the class attribute of the proxysourceuid and the targetuid if it exists. For example, a CanUserView type of call has a targetuid but a CanUserCreate call does not.
The logged in user must have grant and read privileges for the class attribute of the proxysourceuid and the targetuid if one exists.
For common IdentityXML functions and application specific IdentityXML functions:
All the applications should have the same access privileges as the equivalent GUI function.
Exceptions: the rules that apply to the indirect access functions that allow a logged in user to set data for another user also apply to the following group functions: userGroupsProfile, subscribeUserToGroup, unsubscribeUserFromGroup.
Example 1-7 illustrates subscribing to a group.
Example 1-7 Subscription to a Group
<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http:// schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <oblix:authentication xmlns:oblix="http:// www.oblix.com" type="basic"> <oblix:login>J.Smith</oblix:login> <oblix:password>J.Smith</oblix:password> </oblix:authentication> <oblix:request function="subscribeToGroup" version="NPWSDL1.0"> <oblix:params> <oblix:uid> cn=Marketing Team, ou=Marketing, o=Company, c=US </oblix:uid> </oblix:params> </oblix:request> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
You use IdentityXML requests to look at or change data in the directory. The ability to view or change data is controlled by the
grant rights that a Master Administrator assigns to you. See the Oracle Access Manager Identity and Common Administration Guide for details.
For most functions, except where noted, the data you are attempting to view or change must be in the searchbase that the administrator set for you. For example, if your searchbase is limited to the Sales organization, you cannot view or change data in the Accounting organization.
Direct functions test your own ability to view or change data.
For functions that test your ability to view a value without using a workflow:
You must have view privileges for the target object naming attribute
If an attribute is specified, you must have permission to view the attribute
T he attribute must be included in a panel configured for an Identity System application.
For functions that test your ability to modify a value without using a workflow:
You must have view privileges for the target object naming attribute.
You must have write privileges for the target attribute to be set.
T he attribute must be on a panel configured for an Identity System application.
For functions that use a workflow:
To test for the ability to modify attributes, you must:
Have view permissions for the target object naming attribute (for example, the uid or tab_id).
Have view permissions for the target attribute.
Be a participant in the workflow that is used to set that attribute.
To test for the ability to delete, you must:
Have view permissions for the target object naming attribute.
Be a participant in the workflow that is used to delete the object.
To test for the ability to create, you must:
If a domain is specified: Be a participant in the workflow that is used to create the data in that domain.
If a domain is not specified: Be a participant of at least one workflow that creates that data.
Note:Workflow governs in all three categories. For the create test, if you are a participant in the workflow, you will be granted access even if the object is outside of your assigned searchbase. For all of the tests, if you are not a participant in the workflow, you will get a negative response even if you have modify rights to the attribute.
Indirect functions test the ability of another user, represented by the proxysourceuid parameter, to view data or make changes. This parameter is required for a number of IdentityXML functions, as described in "IdentityXML Functions and Parameters". Required privileges are as follows:
All the access privileges described in the previous paragraphs must be satisfied for the person represented by the proxysourceuid parameter.
You must have view privileges for the class attribute of the proxysourceuid and the targetuid (if used).
The object classes for the proxysourceuid and targetuid must be in your searchbase.
You must have the ability to grant the right to read on the class attribute of the proxysourceuid and the targetuid (if used).
Application-specific IdentityXML requests are the
set functions that view or change data. Each is equivalent to an operation that can be carried out through the GUI, and the rights are those that would apply to the GUI.
Exceptions are the following three functions. Rights for these must be the same as for the Indirect Access APIs.
Note:In any IdentityXML request, the LDAP attributes that can be specified or used are only those that have been configured in the Identity System and are part of a panel in the profile of the user, group, or organization. All other attributes are considered invalid.
Some parameters take values of type DN. Privileges required for DN operations are as follows:
View: If you submit a request to view a DN attribute value (for example, by using the attrName function), only values for which you have view permissions and localized permissions are returned. That is, you must have read access to the class attribute of that DN, and the DN value should fall under your searchbases with respect to the type of its object class.
Modify: If you submit a request to add, modify, or delete a DN attribute value (for example, through any modify or workflow function), values are considered valid only if you have view permissions and localized permissions for them. That is, you should have read access to the class attribute of that DN, and that DN value should fall under your searchbases with respect to the type of its object class. If you specify an invalid DN value, an error message such as "Invalid value for parameter uniqueMember" is returned.
Some examples of invalid DN values are junk values, deactivated users, or DNs that do not satisfy your access rights.
Depending upon the Identity System application being used, you locate the matching XML registration file (userservcenterreg.xml for example). Within the registration file, look for the following element:
where xxxxx is the function you are using. In this example, you look for ObProgram name="search". Within that element is another:
where yyyy is the name of the XML schema file that defines the expected output. In this example, that line reads as follows:
The XML schema file generally begins with several includes, but the output XML starts with the first element which contains a reference to ObRequestInfo, and will contain only the information specified by that element.
For example, within the usc_search.xsd file the element ObSearch contains the ObRequestInfo element, as shown in Example 1-8, taken from that file.
Example 1-8 Response Format
<xsd:element name="ObSearch"> <xsd:complexType> <xsd:sequence> <xsd:element ref="ObRequestInfo"/> <xsd:element ref="ObScripts"/> <xsd:element ref="ObForm"/> <xsd:element ref="ObTextMessage"/> <xsd:element ref="ObColumnInfo"/> <xsd:element ref="ObEntry" maxOccurs="unbounded"/> <xsd:element ref="ObButton" maxOccurs="unbounded"/> <xsd:element ref="ObViewModeButtonsForSearchResults"/> <xsd:element ref="ObStatus"/> </xsd:sequence> </xsd:complexType> </xsd:element>
Detailed search results are returned within ObAttribute elements nested within an ObEntry element. An ObStatus element returns the status value for the request:
An ObStatus value of 0 means the request was accepted and processed.
A value of 1 means that an error has occurred.
The recommended strategy for working with the response data is to use a tool, such as the HTTPClient discussed in "XML Background", to get a sample of the output returned by the Identity System. With the corresponding XML schema as a guide, you can determine which parts of the data you want your application to use.
IdentityXML responses adhere to a particular XML schema. Due to the nature of attribute mapping in the Identity System, an attribute can be configured as one of many possible data types, for instance, as a single-valued string, a multi-valued string, various date formats, integers, selection lists, checkboxes, and so on. As a result, Oracle does not recommend hard-coding the attribute-to-data-type parsing dependencies. It is recommended that you implement a parser that can recognize the data type and extract the relevant data and attribute properties.
The IdentityXML response structure follows the data definition for a particular object class type. For example, a profile for an object such as user, group, or organization consists of at least one panel of attributes. An attribute may appear in more than one panel in the Identity System application. The order of the attributes is determined by configuration settings. It is a common mistake in IdentityXML implementations to make invalid assumptions such as the number of occurrences of an attribute in an XML response or that an attribute will always have a value.
Example 1-9 is an actual response to the example search request. There would be an ObEntry element returned for each directory entry satisfying the search.
Example 1-9 Response Example.
<?xml version="1.0" encoding="UTF-8" ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http:// schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <Oblix> <ObSearch> <ObRequestInfo>181481520</ObRequestInfo> <ObScripts> ... </ObScripts> <ObForm ....> ... </ObForm> <ObTextMessage/> <ObColumnInfo> ... </ObColumnInfo> <ObEntry> <ObAttribute obattrName="cn"> <ObDisplay obdisplayName="Name" obdisplayType="dn" obname="cn" obmode="view" obcanRequest="false" obrequired="false"> <ObDn> <ObLink obdisplayName="John Fulton" obhref="userservcenter.cgi ?program=view&tab_id=Employees &uid=cn%3DJohn%20Fulton%2C %20ou%3DEngineering %2C%20o%3DCompany%2C%20c%3DUS" obmouseOver="View personal information"> cn=John Fulton, ou=Engineering, o=Company, c=US <ObImage obhref="CIMAGEperson" obalt="View personal information" /> </ObLink> </ObDn> </ObDisplay> </ObAttribute> <ObAttribute obattrName="mail"> <ObDisplay obdisplayName="E-Mail Address" obdisplayType="email" obsemanticType="ObSEmail" obname="mail" obmode="view" obcanRequest="false" obrequired="false"> <ObEmail> <ObValue>J.Fulton@company.com</ObValue> </ObEmail> </ObDisplay> </ObAttribute> . . . <ObAttribute obattrName="telephonenumber"> <ObDisplay obdisplayName="Phone Number" obdisplayType="textSÓobname="telephonenumber" obmode="view" obcanRequest="false" obrequired="false"> <ObTextS> <ObValue>408-555-1173</ObValue> </ObTextS> </ObDisplay> </ObAttribute> <ObAttribute obattrName="ou"> <ObDisplay obdisplayName="Organization" obdisplayType="select" obname="ou" obmode="view" obcanRequest="false" obrequired="false"> <ObSelect> <ObChoice obdisplayName="Engineering" obselected="true">Engineering </ObChoice> </ObSelect> </ObDisplay> </ObAttribute> </ObEntry> ... <ObViewModeButtonsForSearchResults> ... </ObViewModeButtonsForSearchResults> <ObStatus>0</ObStatus> </ObSearch> <ObStatus>0</ObStatus> </Oblix> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
If a request contains invalid data, or if you try to access data for which you have no authorization, you will get an error. The error response shown here is the result of using XXX as the value for the SLk1 parameter in the request. It is worth mentioning that the response includes the element ObError and the element ObStatus with the value 1, at the same indent level as ObError. Look for both of these parameters to identify error responses.
Example 1-10 illustrates a response to an error.
Example 1-10 Error Response
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelopexmlns:SOAP-ENV="http:// schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <Oblix xmlns:oblix="http://www.oblix.com/" xmlns="http://www.oblix.com/"> <ObError> <ObRequestInfo>187658080</ObRequestInfo> <ObTextMessage> The attribute specified for this search (XXX) is either not searchable or not a valid attribute. </ObTextMessage> <ObStatus>1</ObStatus> </ObError> <ObStatus>1</ObStatus> </Oblix> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
The following are some possible errors:
Invalid parameter value: %1.
This is returned when an input parameter has an invalid value. This could be because the parameter is not provided in a DN format, or does not exist in the schema. %1 is replaced with the name of the parameter that was in error, for example
This is returned when the required or optional attributes provided for a workflow are not valid; for example, if the password is set to a minimum of eight characters and the input is only three characters.
You do not have access rights.
You do not have the right to perform the operation.
There is an XML syntax error.
That is, there is an error in the code, such as a typo.
There is no profile configured for this kind of user.
This is a generic error generated when the input is invalid and is not caught by other error catching.
A value is required for %1.
This error indicates that a required parameter is missing, perhaps for a workflow attribute or as part of a delete request.
Not authorized to use service.
You have not been authenticated, or lack the authorization, to make requests to particular application.
A Web Service consists of programmable application logic that is accessed using standard Internet protocols. XML Web Services expose useful functionality to Web users through a standard Web protocol. In most cases, the protocol used is SOAP. XML Web Services provide a way to describe an interface in enough detail to allow a developer to build a client application to talk to it. The description of the interface is usually provided in an XML document called a Web Services Description Language (WSDL) document.
WSDL provides a convenient method for working with Web requests that are created in XML. A WSDL file is a schematic description of an XML request. The contents of a WSDL file consists of information about an XML function name, its parameters, and so on.
The following sections describe using the Identity System's WSDL files and working with them as an alternative method for generating IdentityXML requests.
WSDL enables you to create services that can anyone can access on the Web. This enables others to build new, more powerful applications that use XML Web services as building blocks. The section "Making WSDL Functions Available Using UDDI" describes how to register WSDL functions so that they are available to anyone who needs to use them.
WSDL also provides an abstraction layer for IdentityXML. If you rely on IdentityXML for integration with Web application servers or third-party applications, or if you work with a variety of application frameworks and separate development teams, it is unlikely that all of the application developers would have expertise in IdentityXML. WSDL provides tools that allow you to bypass directly coding IdentityXML calls. Developers can use tools to generate proxy code for the IdentityXML function, and use the proxy code to make the calls. This enables the developer to use WSDL to avoid hands-on XML programming.
As noted in "About IdentityXML", you hand-craft an IdentityXML request document by looking up the request syntax, function names and parameters in this guide, constructing an XML-based SOAP request, and sending the IdentityXML request to the WebPass using HTTP. With WSDL, you only work with objects, rather than hand-crafting the XML request. Using WSDL, the code for sending the request is generated automatically in the language of your choice, for example, Java. You only need to set the parameters in the request, rather than constructing the entire request. For example, the parameters would be function calls on Java objects.
The Identity System provides WSDL files for each of the IdentityXML functions described in "IdentityXML Functions and Parameters". The WSDL files are in the following location:
The file names reflect the name of the function, for instance, one WSDL file contains the name "search" because it corresponds to the IdentityXML search function. Another WSDL file contains the name workflowTicketSearch, which corresponds to another IdentityXML function. For a complete list of function names, see "IdentityXML Functions and Parameters".
The directory oblix\WebServices is structured as follows:
Samples: Contains the following:
UDDI: Contains sample files for implementing UDDI functions. See "Making WSDL Functions Available Using UDDI" for details.
In the directory oblix\WebServices\WSDL\*.wsdl, WSDL files are named as follows:
common_*.wsdl: Each file contains the information required for generating a Common IdentityXML request.
gm_*.wsdl: Each file contains the information required for generating a Group Manager IdentityXML request.
um_*.wsdl: Each file contains the information required for generating a User Manager IdentityXML request.
om_*.wsdl: Each file contains the information required for generating an Organization Manager IdentityXML request.
The Oracle implementation of WSDL follows the recommended model for publishing into UDDI. This model calls for two files to be present for each function:
There is one file for each IdentityXML function that contains the URL location of the function. The name of this WSDL file contains the IdentityXML function name, with a prefix of "common_", "gm_", "um_", or "om_". For example, the search function is a common function, so the corresponding WSDL file is called common_search.wsdl. The function to view a group profile is called view, so the corresponding WSDL file is called gm_view.wsdl.
There is a second WSDL file for the function interface. This file always contains the string "interface" in the file name.
A WSDL document has two main sections. The first section consists of abstract definitions. These are provided in the Identity System-supplied WSDL documents:
Types: Machine- and language-independent type definitions.
Messages: These contain function parameters.
PortTypes: These contain descriptions of function components (operation name, input parameters, and output parameters).
The second section consists of concrete definitions. This information is specific to your environment:
Bindings: The binding(s) of each operation in the PortTypes section.
Services: The port address(es) for each binding.
Each WSDL file imports another WSDL file of the same name plus a suffix of "_interface." For example, gm_view.wsdl file imports a file called gm_view_interface.wsdl. The interface WSDL file contains the attribute types, function name, binding and so on. This file is the abstract representation.
The file that corresponds to the name of the IdentityXML function contains the implementation definition. It contains the URL where this Web service can be invoked. This is the URL to the Identity System installation. This file imports the file with the name that is a concatenation of the name of this file and "_interface", for example gm_view_interface.wsdl.
Providing two WSDL files for each IdentityXML function is helpful if you need multiple implementations of the same interface. You can expose the interface files once through UDDI, and the multiple implementation files can also be published through UDDI.
The following are examples of an actual Identity System WSDL document and a second WSDL file that is included in the first file. Note that the function name is shown in bold.
Example 1-11 shows the WSDL document that corresponds to the IdentityXML search function:
Example 1-11 Common_search.wsdl file
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap" xmlns:http="http://schemas.xmlsoap.org/wsdl/http" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:oblix="http:www.oblix.com" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://www.oblix.com/wsdl/common_search" targetNamespace="http://www.oblix.com/wsdl/common_search"> <import namespace="http://www.oblix.com/" location="common_search_interface.wsdl"/> <service name="OblixIDXML_common_search_Service"> <port name="OblixIDXML_common_search_Port" binding="tns:OblixIDXML_common_search_Binding"> <soap:address location ="http://echo.oblix.com:5555/identity/oblix/apps/ userservcenter/bin/userservcenter.cgi"/> </port> </service> </definitions>
Example 1-12 shows the interface file that provides many of the definitions used in the common_search.wsdl file in the previous example:
Example 1-12 Common_search_interface.wsdl
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" . . . xmlns:oblix="http://www.oblix.com/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://www.oblix.com/wsdl/common_search" targetNamespace="http://www.oblix.com/wsdl/common_search"> <import namespace="http://www.oblix.com/" location="../XMLSchema/ common_parameters.xsd"/> <import namespace="http://www.oblix.com/" location="../XMLSchema/ common_authentication.xsd"/> <import namespace="http://www.oblix.com/" location="../XMLSchema/ common_component_search.xsd"/> <types> <xsd:schema targetNamespace="http://www.oblix.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:element name="request"> <xsd:complexType> <xsd:sequence> <xsd:element name="params"> <xsd:complexType> <xsd:sequence> <xsd:element ref="oblix:tab_id" minOccurs="0"/> <xsd:element ref="oblix:startFrom" minOccurs="0"/> <xsd:element ref="oblix:noOfRecords" minOccurs="0"/> <xsd:element ref="oblix:noOfFields" minOccurs="0"/> <xsd:element ref="oblix:showAllResults" minOccurs="0"/> <xsd:element ref="oblix:sortBy" minOccurs="0"/> <xsd:element ref="oblix:sortOrder" minOccurs="0"/> <xsd:element ref="oblix:attrName" minOccurs="0" maxOccurs="unbounded"/> . . . <!--All of these functions can be invoked for any Identity System application --> <!--User Manager, Group Manager, or Organization Manager to get the --> <!--right search results. They are described in this one WSDL file. --> <xsd:pattern value="userservcenter\groupservcenter\objservcenter"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> <xsd:attribute name="function" type="xsd:string" use="required"/> <xsd:attribute name="mode" type="xsd:string" use="optional"/> </xsd:complexType> </xsd:element> </xsd:schema> </types> <message name="OlibxIDXMLInput"> <part name="authentication" element="oblix:authentication"/> <part name="request" element="oblix:request"/> </message> <message name="OblixIDXMLOutput"> <part name="body" element="oblix:Oblix"/> </message> <portType name="OblixIDXMLPortType"> <operation name="OblixIDXML_common_search"> <input message="tns:OblixIDXMLInput"/> <output message="tns:OblixIDXMLOutput"/> </operation> <portType> <binding name="OblixIDXML_common_search_Binding" type="tns:OblixIDXMLPortType"> <soap:binding style="document" transport="http://schemas:xmlsoap.org/soap/http"/> <operation name="OblixIDXML_common_search"> <soap:operation soapAction="http://www.oblix.com/"/> ... </definitions>
As illustrated in Figure 1-3, IdentityXML calls can substitute for user interaction with the Identity System:
You can either construct IdentityXML requests and SOAP envelopes manually, or you can use WSDL to automatically generate a client object. You then only need to edit the client object to set the appropriate parameters.
Edit the appropriate WSDL files.
Generate a Java or .NET proxy object.
Develop a Java or .NET client.
The following sections provide details on how to develop a Java or .NET WSDL solution.
If you are familiar with Java programming, the Identity System's Web Services for Identity Management enables you to use WSDL instead of working directly with IdentityXML. The Identity System provides two WSDL files for each IdentityXML function. You use these files to generate a Java proxy object for your IdentityXML requests.
Identify the IdentityXML request you want to generate.
Look up the function that you wish to use in "IdentityXML Functions and Parameters".
Optionally, you can locate the corresponding WSDL file in a UDDI registry. The Identity System provides WSDL files in a local installation directory. However, if you have access to a UDDI registry containing the WSDL function, this can be a convenient method of locating the function. See "Making WSDL Functions Available Using UDDI" for details.
Edit the host name and port number in the soap:address statement in a corresponding WSDL document.
For example, for Common_Search.wsdl, you would edit the following line:
<soap:address location ="http://echo.oblix.com:5555/identity/oblix/apps/ userservcenter/bin/userservcenter.cgi"/>
For a Java client, you develop a proxy object and a Java client that submits the request.
You use a WSDL-to-Java conversion tool to process the Identity WSDL file and automatically generate a Java proxy object for the IdentityXML request.
An example of a WSDL-to-Java tool is the Apache Axis package.
If you are familar with .NET, you use the following process:
In a .NET environment, you submit the correct WSDL common files to Visual Studio, which creates a.NET client. You edit the parameters in the generated client code, build the code, and use it as you would any other Web service.
Oracle provides samples for invoking Web services using C#.
Prerequisites for creating a .NET WSDL client:
Be sure your Web services directory is exposed through your Web server so that you can add Web references using Visual Studio.
Install .NET Studio 2003 with .NET Framework 1.1.
Install two Microsoft hot fixes:
Look up the function that you wish to use in Chapter 2, "IdentityXML Functions and Parameters".
Edit the location information in the soap:address statement in a corresponding WSDL document.
For example, for Common_Search.wsdl, you would edit the following line:
<soap:address location ="http://echo.oblix.com:5555/identity/oblix/apps/ userservcenter/bin/userservcenter.cgi"/>
Create .NET code that submits the request.
Launch Visual Studio.
From the Visual C# Projects folder, select Console Application Template and click OK.
Click Project, then click Add Web Reference.
In the Add Web Reference dialog, select the location where you have the Web services directory.
The Web services directory is the location of your Oracle Access Manager WSDL input files.
For example, this could be your local machine or your UDDI server.
The WSDL files from the selected location are displayed.
Select the file containing the WSDL service that is relevant to your application.
These are the files with names that contain the function that you want to work with and do not contain "_interface" in the file name. For example, for a search function, you would edit common_search.wsdl, not common_search_interface.wsdl.
The service is displayed.
Note:Be sure that the URL location in the WSDL file points to the URL of your installed Identity System.
The displayed window will show an error, "No ports or methods were found on this page." You can ignore this error. What is important is shown in the right-hand pane on this page.
Click the Add Reference button in the pane on the right.
A project window will appear that shows that the link to the Web reference has been added. Visual Studio creates the proxy object code, and puts all elements of the object in one file called reference.cs.
In the main window, add the proxy object code.
Specify the application, version, function parameters, and any other information required to complete the client code.
A sample .NET client is provided in the directory oblix\WebServices\samples.
To compile the .NET proxy object code, click Build, then click Build solution.
Once the solution is compiled, you should be able to run it like any other executable, from within Visual Studio or another location.
Oracle Access Manager ships with three sample client code files that demonstrate how to invoke and consume a Web service using Java. These files are located in WebPass_install_dir\identity\oblix\WebServices\samples\WSDL\java_axis:
testwsdl_gm_view.java: shows an example of invoking the Web service when WebPass is protected by a WebGate.
To use this sample code, a WebPass must be installed and protected by a WebGate that uses an Oracle Access and Identity authentication scheme. See the Oracle Access Manager Access Administration Guide for details.
testwsdl_search_deactivated_users.java: shows an example of making a search request, for deactivated users.
testwsdl_viewgroupmembers.java: shows an example of making a request to view the members of a group.
testwsdl_reactivate_user.java: shows how to reactivate a user.
There is also a help file named WSDL_java_axis_README.html in the directory WebPass_install_dir\identity\oblix\lang\<language>\html.
If you want to test additional WSDL functions, for example, adding a group to the group manager, you can add the appropriate WSDL functions to the sample files.
The following sections describe how to compile and run the code. If no exception is thrown when you run the code, the Web service invocation worked. If there are errors, the errors will be printed in the response.
The sample client code requires the following software to run. The following versions are required, lower versions do not work with the sample code:
Java 1.4 or higher (JDK 2, version 1.4), obtainable from http://java.sun.com/j2se/1.4.1/download.html.
Apache Axis 1.3 or higher, obtainable from http://ws.apache.org/axis/
Javax mail and Javax activation jars, available from: http://java.sun.com/products/javamail/downloads/index.html and http://java.sun.com/products/javabeans/glasgow/jaf.html
The following task overview summarizes Access Manager SDK setup. This task is only required if your WebPass is protected by a WebGate.
Install the Access Manager SDK on the local machine where you plan to make the Web service calls.
Configure a new AccessGate in the Access System Console.
See the Oracle Access Manager Access Administration Guide for details. Provide a unique ID for the AccessGate and the host name of the local machine where the Web service calls will be made.
On the local machine, run the configureAccessGate command to configure an AccessGate on this machine.
See the Oracle Access Manager Access Administration Guide for details.
From the Access System Console, turn off IP Validation for the AccessGate and for the WebGate that will receive the Web service calls.
The following procedure describes the commands required to run the sample code.
Set the path to the java and javac compilers from your installed directory. For example, if your installation directory is c:/j2sdk1.14.1\bin, you would set the path as follows:
Where java_home is the path for the installation directory.
Set the path to your Access Manager SDK installation, as follows:
Where Access_Server_install_dir is the directory where the Access Server was installed.
Set the CLASSPATH variable to contain the following jar files:
The jobaccess.jar from the Access Manager SDK
The javx mail jar
The activation jar files.
You must include these jar files before any others that are already in the CLASSPATH, for example:
set CLASSPATH=F:\axis\axis-1_3\lib\axis.jar;F:\axis\axis-1_3\lib\jaxrpc.jar; F:\axis\axis-1_3\lib\commons-discovery-0.2.jar; F:\axis\axis-1_3\lib\commons-logging-1.0.4.jar; F:\axis\axis-1_3\lib\saaj.jar;F:\xerces\xerces-1_4_4\xerces.jar; F:\axis\axis-1_3\lib\wsdl4j-1.5.1.jar;.; F:\TEMP\AcessServerSDK\oblix\lib\jobaccess.jar; F:\javax\javamail-1.3.3_01\mail.jar;F:\javax\jaf-1.0.2\activation.jar; %CLASSPATH%
If your WebPass is protected by a WebGate, set the PATH to contain the Access Manager SDK, for example:
Where path is the location where the Access Manager SDK is installed.
Run the following commands to compile the sample:
java org.apache.axis.wsdl.WSDL2Java -o f:\temp\mywsdl -p com.oblix.www d:\oblix\WebServices\WSDL\gm_view.wsdl
A directory named com\oblix\www is created and is populated with java code.
Go to the directory that was created by running the previous command:
Copy the file that Oracle provides to perform a simple view operation when a WebPass is not protected by a WebGate.
This file is named testwsdl_viewgroupmembers.java and resides in the following location:
Copy this file to the com\oblix\www directory.
This file contains code to view members of a group. You can run this file unchanged, or you can use it as the basis for testing another operation, for example, modifying a user or group.
Alternatively, you can copy the file that Oracle provides to perform a view operation when WebPass is protected by a WebGate.
This file contains code for setting the obSSOCookie. It is named testwsdl_gm_view and it resides in the following location:
You will need to edit the sample code in this file as follows:
Edit the static string accessSDKinstalldir, substituting the location of your Access Manager SDK.
Change the host name and port to reflect your environment.
Change the values for userName and password to those for an actual administrator in your Identity System.
Once you have obtained the ObSSOCookie (as shown in the code sample), you can make multiple Web service calls without the need to provide the user name and password each time. Instead, you can use the ObSSOCookie.
Enter the following command from the com\oblix\www directory:
Go up three levels from the com\oblix\www directory:
Run the Web service, as follows:
The status of the request is output to the command window. A status of 0 indicates success.
You can parse the response object to get other information.
For example, you can extract the search results. An example of this is shown in the file testwsdl_search_deactivated_users.java in the same directory as the other sample files:
The sample code prints the name of the first deactivated user.
The Universal Description, Discovery, and Integration (UDDI) registry is a database for people who require WSDL functions. UDDI provides a way to publish and categorize Web services created using WSDL. UDDI is analogous to the White Pages or Yellow pages, in that you can browse the UDDI registry for functions that you need, and you can add new functions to the registry. Global UDDI registries that can be accessed by anyone from any organization are provided by companies such as IBM and Microsoft. Instructions for creating and using a registry account is provided at these UDDI sites. Other organizations have their own internal UDDI registries.
As an illustration of how people make use of UDDI, suppose a car dealer needs to interact with remote dealers. This dealer can use their organization's UDDI registry as a type of Yellow Pages where they can find Web-based services for locating other dealers. To continue the illustration, suppose the UDDI registry contains the directory software_publishers/identity management/Oracle. The hypothetical car dealer might retrieve an entry in this directory for a Web service that enables users to find remote dealers. The entry would consist of a URL that points to a WSDL file that is capable of generating the desired search request.
In general, UDDI registries contain the following information for each Web service:
The business name, for instance, Oracle
The service (sometimes called an interface in UDDI parlance), which is the XML function, for example, view, plus the input and output parameters in XSD format.
The implementation, which is the URL that points to the corresponding WSDL.
Follow the conventions used in your organization for locating the appropriate UDDI registries.
When you work with the Identity System's Web services functionality, you can register your own functions in UDDI. If you want to build an interface to interact with the IdentityXML system, you can use UDDI to find the appropriate WSDL definitions and use these definitions to develop the Java client that interacts with the IdentityXML service.
Sample UDDI registration programs in .NET and Java format are provided in the following location:
There are readme files in both directories.These directories also contain a sample file for testing the function after it is registered.