| Oracle® Access Manager Developer Guide 10g (10.1.4.3) Part Number E12491-01 |
|
|
View PDF |
| Oracle® Access Manager Developer Guide 10g (10.1.4.3) Part Number E12491-01 |
|
|
View PDF |
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.
Note:
New WSDL, XML schema, and UDDI files are provided with Oracle Access Manager 10g (10.1.4.3). For more information, see "WSDL and XML Schema Files for Building Web Services that Access Multiple Services".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.
Note:
There are no changes to UDDI files in 10g (10.1.4.3).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:
Figure 1-2 IdentityXML Request and Response Flow
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:
IdentityServer_install_dir\identity\oblix\unsupported\integsvcs
Implementing an IdentityXML request requires the procedures identified in the following task overview.
Task overview: Implementing an IdentityXML Request
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.
See sample programs in "Code Examples of Deployed IdentityXML Functions" and the "SOAP and HTTP Client" for details.
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 does 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 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.
All IdentityXML requests use the syntax shown in the following paragraphs. For more information on XML see "XML Background". More information on SOAP is provided in "SOAP and HTTP Client".
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" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<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">
xmlns="http://www.oblix.com/OblixXMLLocalSchema >
<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 continues to work.Documentation of the earlier IdentityXML syntax is available on the Oracle Technology Network at:
XML must start with the following string:
<?xml version="1.0"?>
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.
10.1.4 supports two encoding formats for requests: ISO-8859-1 (Latin-1) and UTF-8. The encoding of the response is the same as the encoding of the request. For example, if the request uses the Latin-1 encoding tag (encoding="ISO-8859-1") the response also uses Latin-1 encoding; if the request uses UTF-8 encoding, the response uses UTF-8 encoding.
In new installations, Oracle recommends that you use the UTF-8 encoding tag (encoding="UTF-8"):
<?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"?>
If an IdentityXML request uses encoding="ISO-8859-1" and the response to it contains any characters outside the Latin-1 character set, such characters are garbled. For example, when ISO-8859-1 is used for the request and the response includes Japanese or Arabic characters, those characters in the response can be garbled.
The required SOAP tag starts the SOAP root element, the envelope:
<SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
The namespace attribute xmlns:oblix enables the use of Identity System-specific tags in the envelope element. Oracle recommends that you include the namespace attribute.
This tag starts the body of the SOAP envelope:
<SOAP-ENV:Body>
The body contains two SOAP elements: authentication information and request information. The body of the SOAP envelope is closed by the following tag:
</SOAP-ENV:Body>
The SOAP root element, the envelope, is closed by the following tag:
</SOAP-ENV:Envelope>
You can use the following syntax with the same result as long as you are consistent within each request:
<SOAP-ENV:Envelope ... <SOAP-ENV:Body> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
or
<soapenv:Envelope... <soapenv:Body> </soapenv:Body> </soapenv:Envelope>
This required element specifies the authentication type to be used:
<oblix:authentication type="basic">
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.
An example:
<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:
<oblix:login>login name</oblix:login>
provides the login ID for an Oracle Access Manager user.
The password tag:
<oblix:password>login password</oblix:password>
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" xmlns="http://www.oblix.com/OblixXMLLocalSchema >
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>:
mode="silent"
For example:
<oblix:request application="userservcenter" function="view" mode="silent" version="NPWSDL1.0" xmlns="http://www.oblix.com/OblixXMLLocalSchema >
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.
For example:
<oblix:request application="userservcenter" function="view" mode="dataonly" version="NPWSDL1.0" xmlns="http://www.oblix.com/OblixXMLLocalSchema >
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:
version="NPWSDL1.0"
Documentation of the pre-6.5 IdentityXML version tag is available on the Oracle Technology Network at:
The following:
<oblix:params>
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:param1>value1</oblix:param1>
For example:
<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:
<oblix:param2>value2</oblix:param2> <oblix:param3>value3</oblix:param3>
Example 1–2 illustrates an IdentityXML function to change a password. Key words of interest are shown in bold. In this example, a Master Administrator is changing another user's password, which does not require the old password value. If a user were changing his own password, the old password value is required.
Example 1-2 Sample Change Password Request
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance"
xmlns:oblix="http://www.oblix.com">
<soapenv:Body>
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic">
<oblix:login>orcladmin</oblix:login>
<oblix:password>welcome1</oblix:password>
</oblix:authentication>
<oblix:request function="modifyUser"
version="NPWSDL1.0" xmlns="http://www.oblix.com/OblixXMLLocalSchema">
<oblix:params>
<oblix:uid>cn=newuser,ou=QA,dc=us,dc=oracle,dc=com</oblix:uid>
<oblix:noOfFields >1</oblix:noOfFields>
<oblix:AttributeParams >
<oblix:PasswordAttribute>
<oblix:AttrName>userPassword</oblix:AttrName>
<oblix:AttrOperation>REPLACE</oblix:AttrOperation>
<oblix:AttrNewValue>welcome1</oblix:AttrNewValue>
<oblix:AttrConfirmValue>welcome1</oblix:AttrConfirmValue>
</oblix:PasswordAttribute>
</oblix:AttributeParams>
</oblix:params>
</oblix:request>
</soapenv:Body>
</soapenv:Envelope>
In the previous examples:
modifyUser: This is the name of an IdentityXML function. This function changes a user attribute in the User Manager.
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:
http://www.customer.com/identity/oblix/apps/userservcenter/bin/ userservcenter.cgi
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" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<authentication type="basic"
xmlns="http://www.oblix.com/">
<login>admin</login>
<password>oblix</password>
</authentication>
<request function="search"
version="NPWSDL1.0" xmlns="http://www.oblix.com/OblixXMLLocalSchema">
<params>
<ns1:tab_id xmlns:ns1="http://www.oblix.com/">Employees</ns1:tab_id>
<ns2:noOfFields xmlns:ns2="http://www.oblix.com/">3</ns2:noOfFields>
<ns3:SearchParams xmlns:ns3="http://www.oblix.com/">
<ns3:Condition>
<ns3:SearchAttr>cn</ns3:SearchAttr>
<ns3:SearchOperation>OSM</ns3:SearchOperation>
<ns3:SearchString>Johns</ns3:SearchString>
</ns3:Condition>
</ns3:SearchParams>
</params>
</request>
</soapenv:Body>
</soapenv: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:
| Special character | Description | Encoding |
|---|---|---|
| > | Begins a tag. | > |
| < | Ends a tag. | < |
| " | Quotation mark. | " |
The applications that respond to IdentityXML input and the files that they use are described here.
URLs to the applications are as follows:
http://www.domain.com:port/identity/oblix/apps/ groupservcenter/bin/groupservcenter.cgi
http://www.domain.com:port/identity/oblix/apps/ objservcenter/bin/objservcenter.cgi
http://www.domain.com:port/identity/oblix/apps/ userservcenter/bin/userservcenter.cgi
http://www.domain.com:port/identity/oblix/apps/ asynch/bin/asynch.cgi
The schema files are as follows:
XML schema documentation files:
10g (10.1.4.3) XML Schema:
WebPass_install_dir\oblix\WebServices\CompositeWebServices\XMLSchema\*.xsd
Earlier XML Schema:
WebPass_install_dir\oblix\WebServices\XMLSchema\*.xsd
10g (10.1.4.3) WSDL Schema:
WebPass_install_dir\oblix\WebServices\CompositeWebServices\WSDL\*.wsdl
Earlier WSDL Schema:
WebPass_install_dir\oblix\WebServices\WSDL\*.wsdl
UDDI sample Java files:
10g (10.1.4.3): None included because there have been no changes to UDDI samples. Refer to those in the earlier version.
Earlier UDDI Sample Java:
WebPass_install_dir\oblix\WebServices\samples\UDDI\*.*
Note:
Oracle recommends that you use the 10g (10.1.4.3) files. If you have been using the earlier files with a previous Oracle Access Manager release, Oracle recommends that you make plans to use the new files in CompositeWebServices. For more information, see "WSDL and XML Schema Files for Building Web Services that Access Multiple Services".The style sheets are as follows (see also the Oracle Access Manager Customization Guide):
Group Manager, Organization Manager, User Manager:
IdentityServer_install_dir\oblix\lang\en-us\style0
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" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<authentication type="basic"
xmlns="http://www.oblix.com/">
<login>admin</login>
<password>oblix</password>
</authentication>
<request application="groupservcenter"
function="canIViewGroupProfile"
version="NPWSDL1.0" xmlns="http://www.oblix.com/OblixXMLLocalSchema">
<params>
<ns1:uid xmlns:ns1="http://www.oblix.com/">cn=BAT partner create mixed
member group,ou=Partners, o=company,c=us</ns1:uid>
</params>
</request>
</soapenv:Body>
</soapenv: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:
Oracle Access Manager supports two encoding formats: ISO-8859-1 and UTF-8 for requests. The response uses the same encoding format as the request. You may continue to send requests as Latin-1 data with ISO-8859-1 encoding. However, Oracle recommends that you use UTF-8 encoding with 10.1.4 requests.If an IdentityXML request uses encoding="ISO-8859-1" and the response to it contains any characters outside the Latin-1 character set, such characters are garbled. For example, when ISO-8859-1 is used for the request and the response includes Japanese or Arabic characters, such characters in the response are garbled.
Example 1-5 Test Response Example
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Envelope
xmlns:oblix="http://www.oblix.com"
xmlns:SOAP-ENV="http://
schemas-xmlsoap.org/soap/envelope/">
<soapenv:Body>
<Oblix>
<ObAccessAPIResult>
<ObRequestInfo>187658080</ObRequestInfo>
<ObTextMessage>Allowed</ObTextMessage>
</ObAccessAPIResult>
</Oblix>
</soapenv:Body>
</soapenv: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
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<authentication type="basic"
xmlns="http://www.oblix.com/">
<login>admin</login>
<password>oblix</password>
</authentication>
<request function="workflowTicketInfo"
version="NPWSDL1.0" xmlns="http://www.oblix.com/OblixXMLLocalSchema">
<oblix:AttrParams>
<ns1:workflowInstanceDn
xmlns:ns1="http://www.oblix.com/">obwfinstanceid=20020528T2115229460,obcontainerId
=workflowInstances,o=oblix,o=company,c=us</ns1:workflowInstanceDn>
<ns2:workflowStepInstanceId
xmlns:ns2="http://www.oblix.com/">1</ns2:workflowStepInstanceId>
</oblix:AttrParams>
</request>
</soapenv:Body>
</soapenv: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" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<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" xmlns="http://www.oblix.com/OblixXMLLocalSchema >
<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 view, modify, and 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 are 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 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 get or 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.
userGroupsProfile
subscribeUsertoGroup
unsubscribeUserfromGroup
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.
The chapter on PresentationXML in the Oracle Access Manager Customization Guide discusses the way the HTML response is built up. See "XML Background" for a discussion of XSD and XML content.
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:
ObProgram name="xxxxxx"
where xxxxx is the function you are using. In this example, you look for ObProgram name="search". Within that element is another:
ObSchema name="yyyy"
where yyyy is the name of the XML schema file that defines the expected output. In this example, that line reads as follows:
ObSchema name="usc_search.xsd"
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 contains 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:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="httpl//www.w3.org/2001/XMLSchema-instance">
<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 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 ObWorkflowName .
Invalid parameters.
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 location described in "Locations for Each Application".
WebPass_install_dir\oblix\WebServices\CompositeWebServices\WSDL\*.wsdl
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 containing files for Web services is structured as follows:
WSDL: Contains WSDL template files, each of which corresponds to an IdentityXML function.
XMLSchema: Contains schema required for generating proxy objects.
Samples: Contains the following:
WSDL: Contains sample code for invoking Web services using Java and .NET .
UDDI: Contains sample files for implementing UDDI functions. See "Making WSDL Functions Available Using UDDI" for details.
Note:
Oracle recommends that you use the new files in /WebServices/CompositeWebServices. However, for sample UDDI files, see WebPass_install_dir/identity/oblix/WebServices/Samples/UDDI.In the directory \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:
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:
Figure 1-3 IdentityXML can Substitute for User Interaction
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.
Task overview: Working with the Identity System WSDL files
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.
Task overview: Using WSDL to generate Java 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, to run a search for user entries you would enter a line similar to the following:
<soap:address location ="http://echo.oblix.com:5555/identity/oblix/apps/ userservcenter/bin/userservcenter.cgi"/>
To search for group entries, the URL would be similar to the following:
<soap:address location ="http://example.com:1234/identity/oblix/apps/ groupservcenter/bin/groupservcenter.cgi"/>
To search for organizations and generic entries, the URL would be similar to the following:
<soap:address location ="http://example.com:1234/identity/oblix/apps/ objservcenter/bin/objservcenter.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:
The first fix to apply is for XML messaging with the .Net Framework, Hot Fix Rollup at http://support.microsoft.com?id=822411.
You also need to apply the fix for .NET Framework 1.1 WSDL with Visual Studio .NET 2003 Hot Fix Rollup at http://support.microsoft.com/?id=823639.
Task overview: Using WSDL to generate .NET IdentityXML requests
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.
To generate a .NET WSDL client
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 computer 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.
Example: common_search.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 window shows 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 appears 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 Web services directory named \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 sample client code files that demonstrate how to invoke and consume a Web service using Java. These files have been developed using Axis and Weblogic Workshop libraries. For details, see the following topics:
Compiling and Running Sample Axis Code for Composite Web Services
Using Composite Web Services Examples Developed Using WebLogic Workshop
Examples are located in the following path:
WebPass_install_dir\identity\oblix\WebServices\samples\WSDL\java_axis
The following samples are provided:
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 Manager 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.
Additionally, there is a help file (WSDL_java_axis_README.html) in the following file system path:
WebPass_install_dir\identity\oblix\lang\<language>\html\WSDL_java_axis_README.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.
Following topics describe the required software, how to set up the software developer kit (SDK), and how to compile and run the code. When you run the code:
If no exception occurs, the Web service invocation worked.
If there are errors, the errors are printed in the response.
The sample client code requires the following software versions to run:
Note:
Lower versions of the following software have not been tested and might not work with the sample code.Java 1.4 (JDK 2, version 1.4 (not tested with higher or lower versions), obtainable from http://java.sun.com/j2se/1.4.1/download.html.
Apache Axis 1.4, obtainable from http://ws.apache.org/axis/
Javax mail and Javax activation jars (no specific versions are required), available from: http://java.sun.com/products/javamail/downloads/index.html and http://java.sun.com/products/javabeans/glasgow/jaf.html
This task is only required if your WebPass is protected by a WebGate.
The following task overview summarizes Access Manager SDK setup.
Task overview: Setting up the Access Manager SDK:
Install the Access Manager SDK on the local computer where you plan to make the Web service calls.
Configure a new AccessGate profile 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 computer where the Web service calls are made.
On the local computer, run the configureAccessGate command to configure an AccessGate on this computer.
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 receives the Web service calls.
The following procedure describes the commands required to run the sample code.
To set the CLASSPATH, and compile and run the sample code:
Install and set up the SDK as described in "Setting Up the Access Manager Software Developer Kit (SDK)".
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:
set java_home=c:\j2sdk1.4.2_05
Where java_home is the path for the installation directory.
Set the path to your SDK installation, as follows:
set PATH=SDK_install_dir\oblix\lib;F:\j2sdk1.4.2_05\bin;%PATH%
Where SDK_install_dir is the directory where the SDK was installed.
Set the path to an Apache installation of ant.
set PATH=%PATH%;c:\apache\ant\bin
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
Note:
You must include these jar files before any others that are already in the CLASSPATH, as shown in the following 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\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%
WebPass Pprotected by WebGate: Set the PATH to contain the SDK, for example:
set PATH=SDK_install_dir\oblix\lib;F:\j2sdk1.4.2_05\bin;%PATH%
Where SDK_install_dir is the location where the Access Manager SDK is installed.
Run the following commands to compile the sample for your environment:
java org.apache.axis.wsdl.WSDL2Java -o f:\temp\mywsdl -p com.oblix.www
d:\oblix\WebServices\WSDL\gm_view.wsdl
In this example, 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:
cd com\oblix\www
WebPass Not Protected by WebGate: Copy the testwsdl_viewgroupmembers.java file that Oracle provides to perform a simple view operation when a WebPass is not protected by a WebGate.
Copy From:
WebPass_install_dir\oblix\WebServices\samples\WSDL\java\testwsdl_viewgroupmembers.java
To: com\oblix\www \testwsdl_viewgroupmembers.java
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.
WebPass Protected by WebGate: 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), and then edit the file, as follows:
Copy From:
WebPass_install_dir\oblix\WebServices\samples\WSDL\java_axis\testwsdl_gm_vi
ew.java
To: com\oblix\www\testwsdl_viewgroupmembers.java
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.
From the com\oblix\www directory, enter the following command:
javac *.java
Go up three levels from the com\oblix\www directory:
cd ..\..\..
Run the Web service, as follows:
java com.oblix.www.testwsdl_gm_view
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, such as the search results, as shown in the file testwsdl_search_deactivated_users.java in thesame \WebServices\samples\ path as the other sample files:
WebPass_install_dir\oblix\WebServices\samples\WSDL\java_axis\
The sample code prints the name of the first deactivated user.
The examples for Composite Web Services are located in the following file system path:
WebPass_install_dir\identity\oblix\WebServices\CompositeWebServices\Samples\Axis1.4\
The test client, TestCompWS.java, shows how to invoke multiple Web services from a single client. It specifically invokes the following services: - um_view, gm_view, om_view and um_modifyUser
um_view (User Manager view)
gm_view (Group Manager view)
om_view (Organization Manager view)
um_modifyUser (User Manager modify user)
The test client, TestCompWS.java, depends on the um_gm_om.jar file, which is present in \CompositeWebServices\Samples\Axis1.4. The steps to generate the um_gm_om.jar appear in the following procedure.
For the WSDL files, the soap:address location attribute points to a test Identity Server. You must make appropriate changes to refer to your own Oracle Access Manager installation.
See Also:
Axis1.4 documentation for more details on WSDL2Java:http://ws.apache.org/axis/To compile and run sample Axis code for Composite Web Services
Perform steps in "Setting Up the Access Manager Software Developer Kit (SDK)" to set up required libraries and SDK (only if you need the ObSSOCookie generated using the SDK).
Copy the WSDL and Schema directories from /CompositeWebServices into a new location (for example, c:\Axis1.4\WSDL2JavaGeneration):
Copy From:
WebPass_install_dir\oblix\WebServices\CompositeWebServices\WSDL\
To a New Location: c:\Axis1.4\WSDL2JavaGeneration\
Copy From:
WebPass_install_dir\oblix\WebServices\CompositeWebServices\Samples\WSDL\
To a New Location: c:\Axis1.4\WSDL2JavaGeneration\
In the following files in your new WSDL directory, make appropriate changes to the soap:address location attribute to refer to your own Oracle Access Manager installation:
um_view
gm_view
om_view
um_modifyUser
From the new WSDL directory, execute the following commands to generate the client stubs and a jar file (and rename it: for example, Um_Gm_Om.jar):
c:\Axis1.4\WSDL2JavaGeneration\WSDL java org.apache.axis.wsdl.WSDL2Java -B -S true um_view.wsdl java org.apache.axis.wsdl.WSDL2Java -B -S true gm_view.wsdl java org.apache.axis.wsdl.WSDL2Java -B -S true om_view.wsdl java org.apache.axis.wsdl.WSDL2Java -B -S true um_modifyUser.wsdl ant
Execute the test client (TestCompWS.java) from either a command prompt or from any IDE.
A sample project developed using the Weblogic Workshop IDE, is provided in the following path: :
WebPass_install_dir\identity\oblix\CompositeWebServices\Samples\ProjectsExport.zip
This sample project invokes multiple Web services from a single client. These examples were developed using Workshop for WebLogic 10.0 MP1
Note:
when WebPass is protected by a WebGate, you must setup the SDK, as described in "Setting Up the Access Manager Software Developer Kit (SDK)".To get started with Composite Web Services examples developed using WebLogic Workshop
Install WebLogic Workshop 10.0 MP1.
Import ProjectsExport.zip, as follows:
Unzip ProjectsExport.zip, in a new location. For example:
From:
WebPass_install_dir\identity\oblix\CompositeWebServices\Samples\ProjectsExport.zip
To: c:\compwebservices
In the new directory, confirm that you have two projects:
OAMCompositeWebServicesPrj
OAMCompositeWebServicesPrjEAR
Click File, click Import, and select Existing Projects into Workspace, then click Next.
Confirm that you do not have any projects with the same names already in Project Explorer.
Select the two projects and click Finish.
For details regarding setup, running, and more, see the help provided within the WebLogic Workshop IDE.
Run the test client, OAMCompositeWebServicesTest.java.
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:
WebPass_install_dir\oblix\WebServices\samples\UDDI\dotnet
and
WebPass_install_dir\oblix\WebServices\samples\UDDI\java
There are readme files in both directories.These directories also contain a sample file for testing the function after it is registered.
|
 Copyright © 2000, 2009, Oracle. All rights reserved. Legal Notices |
|