| Oracle® Access Manager Customization Guide 10g (10.1.4.2.0) Part Number E10354-01 |
|
|
View PDF |
| Oracle® Access Manager Customization Guide 10g (10.1.4.2.0) Part Number E10354-01 |
|
|
View PDF |
Tools are available for you to use to make changes to the installed Oracle Access Manager files, such as parameter files and directories. This chapter discusses these tools. Topics include:
Oracle Access Manager operation is influenced by the content of various ASCII text files, in particular parameter files, also called *.xml files. These can be edited with a text editor.
Here are some guidelines to observe when editing these text files:
Always make and save a backup copy of the original file. This provides a way to recover if you make a mistake.
Do not insert blank lines.
Do not insert comments in the file.
Remember to stop and restart the Identity Server to force to force reloading of the changed data, whose original values may have been cached. For certain changes, you will also have to restart your Web server.
Verify that the intended change has taken effect.
Make one change at a time if possible, to make it easy to find any mistakes. Whether or not you do this, keep a record of what you changed and when, so that if users start to report problems you can quickly find out if they relate to your configuration changes.
Use a simple text editor, such as NotePad on NT or vi on UNIX, to avoid introducing non-ASCII characters into the file. You can also use an XML editor if you have one to reduce the chance of introducing errors when editing XML files. Some XML editors will check the file for well-formedness for you.
Directory applications use Lightweight Directory Access Protocol (LDAP) as a standard tool to create, modify and report data stored within the directory. Specific tools are available to allow relatively easy manipulation of this data directly, using LDAP.
This section provides a short introduction of these tools and methods for using them. More detail is available from the manufacturer of your server application, specifically for its version of these tools.
The structure of a directory, and the data contained within it, is represented by the content of an LDAP Data Interchange Format (LDIF) file. The file can be output, the formatted result of a request made to the directory by an LDAP reporting tool, such as LDAPSEARCH. It can also be input, data that is intended for insertion to the directory, either as entirely new data, or as an update to existing data, using an updating tool such as LDAPMODIFY.
The following is an example, part of an LDIF file taken from an Oracle Access Manager Demo Directory:
dn: cn=John Kramer, ou=Sales, o=Company, c=US objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson objectclass: companyOrgPerson cn: John Kramer sn: Kramer telephonenumber: 415-555-5269 facsimiletelephonenumber: 415-333-1005 title: Account Manager departmentnumber: 1204 employeetype: Fulltime employeenumber: 521-321-4560 givenname: John . .
LDAPSEARCH is one possible tool that can be used to report directory content. There are others, which use a different syntax, but the concepts are the same.
LDAPSEARCH can be used in either a command line or interactive mode. The command line approach is preferable, as it enables users to provide the text of the report request by means of a input file. It is easy to verify the content of this file before making the request. Errors are corrected by changing a few characters in the file rather than retyping the full request, which would be necessary in the interactive mode.
The command line format for LDAPSEARCH is:
ldapsearch(params)(filter) (attr_list)
Each of the three categories shown in italics between ( ) is optional; if all are omitted, LDAPSEARCH drops into interactive mode, which is not discussed here.
The categories are as follows:
params: These parameters tell LDAPSEARCH how to operate. One of them, -f, is used to specify a filter file. If instead the search filter is provided on the command line, all parameters must be stated before the filter is stated.
filter: The filter instructs LDAPSEARCH to provide a subset of the data that would otherwise be provided. For example, a filter could require that only names beginning with N be reported. A filter provided on the command line must be enclosed within quotes.
attr_list: The attribute list, if included on the command line, overrides the default attribute listing. The default list shows all attributes belonging to the directory entry, except operational attributes. If you wish to see only some of these attributes listed, provide their names in the command line, following the filter and separated by spaces. If you want to see operational attributes, provide their names in the command line. If you follow the operational attributes with a * you get the default list of attributes as well.
Parameters are always provided in the form:
-p pdata
where p is the parameter, preceded by a dash, and pdata is the information required for the parameter, if any. If the data contains a space, it must be completely enclosed in double quotes:
-p "pdata with spaces"
Following is an alphabetical list of commonly used parameters. There are others. See the reference document for your version of LDAPSEARCH, or use the parameter /? to see them listed.
-A: Tells the search to retrieve the attribute names only, not the attribute values.
-b: Searchbase, the starting point for the search. The value specified here must be a distinguished name that is in the directory. Data provided for this parameter MUST be in double quotation marks. For example:
-b "cn=Barbara Jensen, ou=Development, o=Oracle.com"
-D: Distinguished name of the server administrator, or other user authorized to search for entries. This parameter is optional if anonymous access is supported by your server. For example:
-D "uid=j.smith, o=Oracle.com"
-f: Specifies the file containing the search filter(s) to be used in the search. For example:
-f filterfile
-h: Hostname or IP address of the machine on which the directory server is installed. This entry is optional; if no hostname is provided, LDAPSEARCH uses the local host. For example:
-h myserver.com
-H: This generates a list of all possible LDAPSEARCH parameters.
-p: Port number that the directory server listens at. For example:
-p 1049
-s: Scope of the search. The data provided for the scope must be one of the following:
base: Search only the entry specified in the -b option.
one: Search only the immediate children of the entry specified in the -b parameter; do not search the actual entry specified in the -b parameter.
sub: Search the entry specified in the -b parameter, and all of its descendants. That is, perform a subtree search starting at the point identified in the -b parameter. This is the default, if the -s parameter is not used.
-S: Designates the attribute(s) to use as sort criteria, controlling the order in which the results are displayed. You can use multiple -S arguments if you want to sort on multiple criteria. The default behavior is not to sort the returned entries. In the following example, the search results are sorted first by surname and then, within surname, by first name:
-w: Password associated with the distinguished name that is specified in the -D option. If you do not specify this parameter, anonymous access is used. For example:
-S sn -S firstname
-w password
-x: Specifies that the search results are sorted on the server rather than on the client. This is useful if you want to sort according to a matching rule, as with an international search. In general, it is faster to sort on the server than on the client.
-z: Specifies the maximum number of entries to return in response to a search request. For example:
-z 1000
If you wanted to get the surname (sn), common name (cn), and given name for every employee within the sales organization whose given name is John, from the directory server listening at port 392, entirely from the command line, you could provide the following information:
ldapsearch -p 392 -b "ou=sales, o=company, c=US" -s sub "givenname=John" sn cn givenname
Results could be something like:
dn: cn=John Jackson, ou=Sales, o=Company, c=US sn: Jackson cn: John Jackson givenname: John dn: cn=John Kramer, ou=Sales, o=Company, c=US sn: Kramer cn: John Kramer givenname: John
dn: cn=John Jackson, ou=Sales, o=Company, c=US sn: Jackson cn: John Jackson givenname: John dn: cn=John Kramer, ou=Sales, o=Company, c=US sn: Kramer cn: John Kramer givenname: John
You can get the same results by using a filter file. For example, a file called namejohn containing the filter:
givenname=John
can be used, with the command line being the following:
ldapsearch -p 392 -b "ou=sales, o=company, c=US" -s sub -f namejohn sn cn givenname
LDAPMODIFY is a tool that can be used to change or add directory content. There are others, but the concepts are similar.
LDAPMODIFY opens a connection to the specified server, using the distinguished name and password you supply, and modifies the entries based on LDIF update statements contained in a specified file. LDAPMODIFY can also be run in interactive mode, a method that is not discussed here.
If schema checking is active when you use LDAPMODIFY, the server performs schema checking for the entire entry before applying it to the directory. If the directory server detects an attribute or object class in the entry that is not known to the schema, then the entire modify operation fails. Also, if a value for a required attribute is not present, the modify operation fails. Failure occurs even if the value for the problem object class or attribute is not being modified.
Note:
Turn on schema checking at all times, as a matter of good practice, to avoid accidently adding data to the directory that could later be unusable or cause schema violations when schema checking is turned back on. Schema checking is controlled at the directory administration server console and is generally on by default.The command line format for LDAPMODIFY is:
ldapmodify <params>
Note:
The params category is optional; if it is omitted, LDAPMODIFY drops into interactive mode, which will not be discussed here.where (params)are parameters that tell LDAPMODIFY how to operate. One of them, -f, can be used to specify a file describing modifications to be made to the directory.
Parameters are always provided in the form:
-p pdata
where p is the parameter, preceded by a dash and followed by a space, and pdata is the information required for the parameter, if any. If the data contains a space, it must be completely enclosed in double quotes:
-p "pdata with spaces"
Following is an alphabetical list of commonly used parameters. There are others. Use the parameter /? to see them listed.
-c: Forces the utility to run in continuous operation mode. Errors are reported, but the utility continues with modifications. Default is to quit after reporting an error.
-a: Enables you to add LDIF entries to the directory without requiring the changetype:add LDIF update statement, which is necessary in the interactive mode. This provides a simplified method of adding entries to the directory; in particular, this enables you to directly add a file created by LDAPSEARCH and modified to make changes.
-D: The distinguished name of the server administrator or other user authorized to change directory entries. This parameter is optional if anonymous access is supported by your server. For example:
-D "uid=j.smith, o=Oracle.com"
-f: Provides the name of the file containing the LDIF update statements used to define the directory modifications. For example:
-h mozilla
-f changestomake.txt
-h: Hostname or IP address of the machine on which the directory server is installed. This entry is optional; if no hostname is provided, LDAPSEARCH uses the local host. For example:
-H: Lists all possible LDAPMODIFY parameters.
-p: Port number that the directory server uses. For example:
-p 1049
-w: Password associated with the distinguished name that is specified in the -D option. If you do not specify this parameter, anonymous access is used. For example:
-w password
Suppose you want to change the stored given name of John Kramer, as reported under the discussion of LDAPSEARCH. The data reported back was:
dn: cn=John Kramer, ou=Sales, o=Company, c=US
sn: Kramer
cn: John Kramer
givenname: John
This output can be used to derive an input file, ToHarvey, whose content might be:
dn: cn=John Kramer, ou=Sales, o=Company, c=US
changetype:modify
replace:givenname
givenname: Harvey
The command line would then be:
ldapmodify - p 392 -f ToHarvey
If you were to now search the directory with the command line:
ldapsearch -p 392 -b "ou=sales, o=company, c=US" -s sub "givenname=Harvey" sn cn givenname
The response would be:
dn: cn=John Kramer, ou=Sales, o=Company, c=US sn: Kramer cn: John Kramer givenname: Harvey
The following are some links to editors that might be useful in working with XML and XSL files:
(under the XSL-Enabled Authoring Tools)
Oracle recommends you thoroughly validate XSL stylesheets before using them in production. The following are freeware validators:
Xalan (testxslt)
http://xml.apache.org/xalan-c/index.html
This contains a validator called testxslt, version 1.1
Saxon
http://users.iclway.co.uk/mhkay/saxon/
XT
All three tools will parse and check for syntax errors. The second two do the better job of listing and locating syntax errors, while the first most closely approximates Oracle Access Manager's XSLT processor.
The Identity System uses the Xalan/Xerces XSLT processor. The Xalan processor is orders of magnitude faster than the built-in XSLT engine.
Suppose you add templates derived from basic.xsl to a custom xslStyleFunctions.xsl and both are included in almost any customized stylesheet). In this case, Xalan may report a number of problems, including an inability to resolve any of the oblix:ObScript/oblix:ObValue/. This results in empty JavaScript includes, for example:
<script="JavaScript" xml:space="preserve"\ </script> <script="JavaScript" xml:space="preserve"\ </script> ... <script="JavaScript" xml:space="preserve"\ </script>
The XSLT standard does not impose requirements on how processors should handle template conflict resolution. As a result, the XMLSPY internal processor does not report errors. However, Xalan would and the Identity System returns a stylesheet processing error.
In this case, there was a conflict due to multiple same-name templates sharing the same priority. A good description of template priorities can be found at:
http://www.vbip.com/books/1861003323/chapter_3323_09.asp
Default priorities are assigned by the processor based on certain criteria. Some processors apply smart logic to determine which conflicting template wins, for example, the template closest to the source stylesheet (wf_create.xsl or usc_profile.xsl).
Adopting the following style would protect against template conflict resolution:
Add a priority of `1' to any templates in basic.xsl.
Add a priority of `2' to any xslStyleFunctions.xsl templates with the potential for a name conflict.
Add a priority of `3' to any source (bottom-level) xsl in case there is another override to a template defined in included xsl-s.
The following two procedures prepare you to troubleshoot Xalan-specific stylesheet processing errors reported by the Identity System within XMLSPY.
To use XMLSPY with Xalan/Xerces on Windows 2000 and higher
Download a Xalan-C 1.7.0 binary distribution, which is not compatible with Xerces-C 2.5.0 distribution.
Download a Xerces-C 2.4.0 binary distribution.
Unzip the downloaded archives.
For example:
C:\opt
Navigate to your system PATH variable.
For example:
From the Control Panel select System, from System select Advanced, from Advanced select Env Vars, from Env Vars select System Variables, from System Variables select Path.
Append the following to your system PATH variable:
C:\opt\xml-xalan\c\Build\Win32\VC6\Release;C:\opt\xerces-c2_4_0-windows_nt-msvc_60\bin;
Configure XMLSPY to use an external XSL processor, as discussed next.
To configure XMLSPY to use an external XSL processor
From the Tools menu choose Options, fro m options choose XSL.
Restart XMLSPY to pick up the newly updated PATH.
Select External XSL transformation program.
In the text box, enter Xalan.exe -o %2 %1 %3
Click OK.
