| Oracle® Access Manager Customization Guide 10g (10.1.4.3) Part Number E12498-01 |
|
|
View PDF |
| Oracle® Access Manager Customization Guide 10g (10.1.4.3) Part Number E12498-01 |
|
|
View PDF |
This chapter covers various ways you can customize the Oracle Access Manager application that do not fall cleanly into any of the categories covered earlier.
This chapter discusses the following:
The Identity System supports a self registration workflow. For the User Manager application only, this can be used to provide an auto-login capability. This capability can be extended to allow users of the workflow to access additional resources immediately following the self registration, without being challenged. In addition, for Oracle Access Manager resources, these users can be automatically authenticated after Self Registration. This section describes the steps necessary to accomplish this.
Task overview: Customizing for auto-login
Add at least one AccessGate profile in the System Console, as described in the Oracle Access Manager Access Administration Guide.
The AccessGate profile that you add must have its Access Management Service option set to On. You add this AccessGate simply to ensure that at least one has been created and configured, to control access to Oracle Access Manager.
Configure the AccessGate, as described in the Oracle Access Manager Access Administration Guide.
From the Identity_install_dir/identity/AccessServerSDK/oblix/tools directory, run the configureAccessGate program to configure the AccessGate. No special configuration data needs to be provided to satisfy Auto-login requirements.
Identity_install_dir is the directory where the Identity System is installed.
Enable auto-login in the Identity System parameter file, basedbparams.xml:
Identity_install_dir/identity/oblix/data/common/basedbparams.xml
In the basedbparams.xml file, particular parameter values must be set, as defined in Table 5-1.
Note:
You need to know the URL and access method for the page that the user will go to immediately following self-registration.Table 5-1 Auto-login parameters
| Parameter Name | Value |
|---|---|
|
true |
|
|
Access method for the next page. |
|
|
false |
|
|
true |
|
|
Location of the next page. |
|
|
A valid domain name, for example, example.com |
|
|
Location of the next page. |
Here is an example of this file content after these changes have been made.
<?xml version="1.0"?>
<ParamsCtlg xmlns="http://www.oblix.com" CtlgName="basedbparams">
<CompoundList ListName="">
<SimpleList>
<NameValPair ParamName="default_policy"
Value="false"/>
<NameValPair ParamName="doAccessServerFlush"
Value="false"/>
<NameValPair
ParamName="SelfRegGeneratesSSOCookie"
Value="true"/>
<NameValPair ParamName="SR_SSOCookieMethod"
Value="GET"/>
<NameValPair ParamName="enableAllowAccessCache"
Value="true"/>
<NameValPair ParamName="SR_SSOCookieURL"
Value="/identity/oblix"/>
<NameValPair ParamName="SR_SSOCookieIP"
Value="192.168.1.109"/>
<NameValPair ParamName="SR_SSOCookiePath"
Value="/"/>
<NameValPair ParamName="SR_SSOCookieDomain"
Value="example.com"/>
</SimpleList>
</CompoundList>
</ParamsCtlg>
<?xml version="1.0"?>
<ParamsCtlg xmlns="http://www.oblix.com" CtlgName="basedbparams">
<CompoundList ListName="">
<SimpleList>
<NameValPair ParamName="default_policy"
Value="false"/>
<NameValPair ParamName="doAccessServerFlush"
Value="false"/>
<NameValPair
ParamName="SelfRegGeneratesSSOCookie"
Value="true"/>
<NameValPair ParamName="SR_SSOCookieMethod"
Value="GET"/>
<NameValPair ParamName="enableAllowAccessCache"
Value="true"/>
<NameValPair ParamName="SR_SSOCookieURL"
Value="/identity/oblix"/>
<NameValPair ParamName="SR_SSOCookieIP"
Value="192.168.1.109"/>
<NameValPair ParamName="SR_SSOCookiePath"
Value="/"/>
<NameValPair ParamName="SR_SSOCookieDomain"
Value="example.com"/>
</SimpleList>
</CompoundList>
</ParamsCtlg>
Protect the URL specified in the SR_CookieURL parameter in the Identity Server basedbparams.xml file with a Basic over LDAP authentication scheme in the Access System.
If any other type of authentication scheme is used, the ObSSOCookie will not be created for the user and auto-login will fail.
Stop and restart the Identity server.
This step, now or later, is essential in order to load the new content of the parameter file.
Configure the WebGate to accept auto-login by using an Access System Parameter Catalog.
In the Access System configuration page for the WebGate, do one of the following:
Set the IPValidation field to false
Set IPValidation to true and enter the value that was used for the IP address (SR_SSOCookieIP) in the IPValidationExceptions list.
See Oracle Access Manager Access Administration Guide for details. The IPValidationExceptions field is a list of IP addresses that are excluded from IP address validation. It is often used for excluding IP addresses that are set by proxies. Since the IP validation is a universally applied parameter and you might want to validate the IP in other cases, the second option is likely the one you will follow.
Following the change(s), stop and restart the Web server associated with the WebGate.
This step, now or later, is essential in order to load the new content of the WebGate parameters.
To ensure that the URL specified in basedbparams.xml is protected by a policy domain in the Access System, copy the URL and paste it in the Access Tester. If the URL is not recognized, you may need to preface it with the correct host identifier. For instance, the URL of /identity/oblix may not be protected, but the URL //12345:99/identity/oblix might be.
Finally, you must configure a Self Registration workflow in User Manager, as follows.
Task overview: Configuring a Self Registration workflow
Create a workflow, as described in the Oracle Access Manager Identity and Common Administration Guide.
The first step of the workflow must be Self Registration. This step must have the login and password semantic type attributes configured. The password attribute must be part of the self-registration step for auto-login to work.
Optionally, you can add non-interactive steps, such as external actions. Interactive steps in the workflow are impossible, because the user is not considered logged in until after the workflow completes.
Configure Enable as the last step.
This workflow will generate SSO cookies that can be used for authentication if the workflow completes successfully. In addition, the new user can use Oracle Access Manager without having to log in.
If you need it, the cookie generated as part of auto-login can be obtained from the auto-login page output using IdentityXML. Look for the cookie under the ObSSOCookie element and extract the data for ObValue.
The pertinent part of the XML string will look something like:
<ObSSOCookie>
<ObDisplay obdisplayName="SSOCookie"
obdisplayType="textS" obname="ObSSOCookie"
obmode="view" obcanRequest="false"
obrequired="false">
<ObTextS>
<ObValue>
ghv6XNmGZefMq8cgIte08alq477M
nvaivG+tSaxHRzaOXBcfMkzmf/
UeTrKcg2jJmyo3PpNbLKS+UgmRi/
rg8Ac2LlU9a7rprYjqocs
QGQEgymqELZC0VQo6KqGguv7ujrBt9JtzwQ6/
sDJFlVaLDwLs0vJbg5kop5
FASBF9ohGOwQcUtDGlVal
DwktElNskHYgtjvjc9pBBGtlU9sGuYA/cTw==
</ObValue>
</ObTextS>
</ObDisplay>
</ObSSOCookie>
If the Web pass is protected by a WebGate, you can set up self registration through IDXML for those users who can register themselves. To avoid lockout conditions, you may want to allow self-registration for Master Administrators and for users who lost their passwords.
You use the following URL for the self-registration request:
/identity/oblix/apps/userservcenter/bin/userservcenter.cgi?/from_prog=workflowSelfRegistration
The URL for self-registration is not the usual /identity/oblix/apps/userservcenter/bin/userservcenter.cgi.
See also:
See the chapter on workflows in the Oracle Access Manager Identity and Common Administration Guide for more information on self-registration.As described in "Designing the GUI with PresentationXML", you can customize the user interface by modifying various stylesheets. When a user completes self-registration, a confirmation page appears.
To customize the self-registration confirmation page
Open the following file:
Identity_install_dir/oblix/lang/shared/wf_selfregdone.xsl
Where identity_install_dir is the directory where the Identity System is installed.
Re-start the Identity Server for your changes to take effect.
Apply these changes to all Identity Server installations.
As described in the Oracle Access Manager Access Administration Guide, Oracle Access Manager provides a way to specify an single sign-on logout URL. As part of the installation process, Oracle Access Manager automatically sets up the logout URL
/identity/oblix/apps/userservcenter/bin/ userservcenter.cgi?/from_prog=workflowSelfRegistration
The logout URL is configurable in the LogOutUrls parameter in the AccessGate configuration page.
The logout.html file activates JavaScripts which perform the actual logout. Users may change this to a different URL, which would for example activate an HTML, CGI or even a PERL file created by the user.
If you have multi-domain SSO, then each domain must be iterated to remove the ObSSOCookie. If the cookie is not completely removed, the last authenticated user could appear (similar to an impersonator).
On a customized logout page, ensure that the ObSSOCookie is handled independently for each domain. To do this, confirm that the JavaScript removes the ObSSOCookie. Otherwise, you experience find the following situation.
If the previous guidelines are not followed, you could face the following situation.
User1 logs in to an application and his profile appears based on the authorization headers.
User1 logs out, which kills all session cookies, but does not close the browser window.
User2 logs in and sees the User1 headers even though the User2 ObSSOCookie and session cookie are new.
To avoid the previous situation Oracle recommends that each user log out, and then close the browser window to clear all headers.
Task overview: Customizing logout
Create a different HTML or CGI file to perform the logout steps. This file must have the characters logout. somewhere in its name, for example, mybanklogout.cgi.
Store it in a defined location. Oracle recommends using /access/oblix/apps/common/bin.
In the Access System landing page, click Access System Console, then click System Configuration, then click Server Settings, then click Configure SSO Logout URL.
Replace the default URL with one pointing to the location of your new logout process.
Within the Access System, navigate to Policy Manager > Create Policy Domain. Create a new policy domain for this logout resource using the Anonymous authentication scheme. The URL Prefix entered to the Resource page should be one that includes the logout resource file or its the parent folder.
The Identity System's workflow feature enables the user to associate a pre- or post-notification email with a workflow step, using standard PresentationXML techniques to build the email messages. An OutPutXML data stream is combined with a stylesheet to create a logical file. This file is passed to a Mail Server queue from which it is eventually sent to its final destination.
The Identity System expects to find the necessary stylesheets in the following directory:
Identity_install_dir/identity/oblix/lang/langTag/style0
where Identity_install_dir is the directory where the Identity System is installed and langTag is a language tag in RFC 1766 format.
The Mail Server will have been previously configured to use either the Text-only mail style or the HTML mail style. (The MHTML mail style cannot be customized.) That setting controls the choice of the default stylesheet. The default stylesheet is wf_prepostnotification_txt, if the mail style is set to Text-only or wf_prepostnotification_html if the mail style is set to HTML. If an error occurs during workflow processing, CORE Id uses the stylesheets wf_errornotification_txt for mail style Text-only and wf_errornotification_html for mail style HTML.
Users can expand this functionality to provide distinct message formats for pre- and post-notification, and distinct message formats by workflow ID and the step number within the workflow. To do this, users add new stylesheets to the directory. Oracle Access Manager looks for these files first and if they are present uses them instead of the default files.
The file names added by the user must follow this naming structure:
WfDefId_WfStepDefId_preorpostnotify_mailtype
Following are the meanings of each part of the name:
WfDefId: This is the Id for the workflow for which the notification is to be sent. It is the rdn of the workflow. The ID is automatically created when a workflow is created. You can obtain the ID by using the 'View' feature in the work flow definition screen.
WfStepDefId: This is the workflow step for which the notification is to be sent. It is a number.
preorpostnotify: This is the exact text prenotify or postnotify.
mailtype: This is the exact text txt or html. Understand that this suffix does not determine whether the message is sent as text or HTML. It serves solely as a way for Oracle Access Manager to find the correct file. For example, if the Mail Server is configured for Text-only, Oracle Access Manager looks for a file with the suffix txt. In this case, if you have created a stylesheet with the html suffix, Oracle Access Manager does not look for it and uses wf_prepostnotification_txt instead.
Following are some example file names:
This provides a customized prenotification email message for step 2 of Workflow 1864aaa89df04422bfd33afcdfb45641, if the Mail Type has been set to Text-only.
1864aaa89df04422bfd33afcdfb45641 _2_prenotify_txt.xsl
This provides a customized postnotification email message for step 4 of Workflow 1864aaa89df04422bfd33afcdfb45641, if the Mail Type has been set to HTML.
Note:
You must put the customized email stylesheets in the style0 directory, even if you have made some other directory the master style directory. Email processing looks for the email stylesheets only in the style0 directory.You can configure three types of notification email:
pre-notify
post-notify
escalation notification
The Subject line for these email notifications is set in the following message catalog file:
Identity_install_dir/oblix/lang/lang/workflowdbmsg.xml
Where Identity_install_dir is the installation directory for the Identity Server and lang is the language name, for example, en-us, fr-fr, and so on. The following snippet in the message catalog file illustrates the strings that you can customize to change the email Subject line:
<Message MsgTab="WfPreNotifyMailSub" >Pre-notification of workflow step</Message> <Message MsgTab="WfPostNotifyMailSub" >Post-notification of workflow step</Message> <Message MsgTab="WfEscallationNotifyMailSub" >Escallation-notification of workflow step</Message>
Certain characters in XML files in certain instances require special handling in order to be correctly interpreted by Oracle Access Manager.
The current version of the XML standard calls for certain characters to be escaped using the & sign followed by additional text. OutPutXML follows this requirement. Users will need to translate these characters when reading from OutPutXML or provide their escaped equivalents when creating OutPutXML.
A table of these characters, with their escaped values, follows.
XML files, for example message files after internationalization, may contain characters that will need to be translated to Oracle Access Manager. It is not possible to provide an exhaustive list of these characters. The general technique is to replace the offending character with its escaped hex equivalent. For example, an accented o, which has the hex equivalent F2, must be shown in the XML file as ò.
See also:
See "XML Schema".At the Oracle Access Manager application level, you can optionally control the view and modify functions of the DN type attributes, such as manager or uniquemember, by validating the DN attribute's values. The login user can be allowed to view or modify only those values of the DN for which they have view access (on the class attribute of the objectclass of the DN) as well as localized access; that is, this DN falls under the user's searchbases with respect to the type of objectclass of the DN.
This DN validation is optional and it can be turned on or off through the parameter catalog modifications. Note that the DN validation is an expensive operation, therefore if you do not want so much security, Oracle recommends this validation be turned off. But if security is important, this DN validation must be turned on.
The parameters are in this file:
Identity_install_dir/identity/oblix/apps/common/bin/oblixappparams.xml
and can be overridden by each application.There are two parameters each for view mode and modify mode. For view mode, there is a Boolean parameter called "validateAllDnViewMode". There is also a parameter in ValList format, called validateDnAttrsViewMode. This is used only if the Boolean parameter is false.
The Boolean parameter provides a way to turn the validation on or off globally. The ValList provides the option of turning the validation on/off on an attribute by attribute basis. Thus, the ValList parameters will only be used if the Boolean parameter is false.
Similarly, there are two corresponding parameters for the modify mode called validateAllDnViewMode and validateDnAttrsModifyMode. By default, in the shipped product, only the Boolean parameters are listed and they are set to false.
Note:
The DN validation is always on for IdentityXML calls, for all DN type attributes.The IIS Web server on Windows supports Challenge/Response Authentication, which defaults to on when IIS is installed. This enables users to use their domain log-ins when requesting resources from IIS and can conflict with Oracle Access Manager's authentication.
For example, on the first request from an Internet Explorer (IE) browser to a resource on IIS protected by Oracle Access Manager requiring basic authentication, IE displays a login dialog box requesting a domain along with the user name and password login provided by Oracle Access Manager.
To disable Windows Challenge/Response Authentication
Run the Microsoft Management Console for IIS.
Select the Web Server Host under Internet Information Server in the left hand panel.
Right click and select Properties.
Scroll down and select Edit the Master Properties for WWW Service.
Select the Directory Security tab.
Select Edit Anonymous Access and Authentication Control.
Complete the appropriate step for your platform:
NT: Deselect the Windows NT Challenge/Response checkbox.
Windows 2000: Deselect the Integrate Windows Authentication checkbox.
Click OK.
In the Windows IIS properties screen, click OK.
Close the Microsoft Management Console.
In this scenario, you have in place a satisfactory method for authenticating users but would also like to use Oracle Access Manager's authorization services.
The solution is to add an authentication scheme to be used in this instance. Using LDAP tools, change the challenge method for this scheme to a special value that the Access Server recognizes for this situation, and instruct the Web server to do the Oracle Access Manager authentication/authorization processing after the other authentication method has been applied.
Note:
The technique described here is specific to and verified only with iPlanet's Web Server 4.1 and Directory Server 4.11.The key to this solution is to define an authentication scheme using the challenge method ext, which is provided through Oracle Access Manager's GUI. This scheme is coupled to the iPlanet variable auth-user, which the existing authentication method is expected to set when it authenticates. Oracle Access Manager finds this variable already set when it attempts verification, and therefore does not send a challenge back to the browser, but instead goes on to perform authorization.
The following tasks must be completed in order to support Oracle Access Manager for authentication only.
Task overview: Implementing Oracle Access Manager authentication
Within the directory, ensure that all user records contain an attribute that can be used by the authentication scheme. The user name attribute, uid, is an example.
Within Access System Console, add a new authentication scheme, which will use a special challenge method. See the Oracle Access Manager Access Administration Guide for details.
Within the directory server obj.conf file, change the processing order to allow the another authentication process to set the authentication result before Oracle Access Manager is used. With the authentication check already completed, Oracle Access Manager will simply go on to do authorization processing.
All user records in the directory have an instance of an attribute that is checked as part of the existing authentication method. Most likely, this is the user name, uid.
To use Oracle Access Manager for authorization only
Define an External Authentication Scheme.
For example:
Log in to the Access System Console.
Go to the Access System Configuration screen, click Authentication Management, and click Add.
Create a new authentication scheme, as described in the Oracle Access Manager Access Administration Guide, and note the following:
The display Name and description can be any text you choose.
Level should be consistent with other authentication schemes you might be using, but can be any value.
For the Challenge Method, use ext.
For the Challenge Parameter, you must enter creds:auth_user, to match the name of the internal variable carried by iPlanet.
For SSL Required, use No. This will not be used, since no redirection will take place.
Required Challenge Redirect is left blank, for the same reason.
The value for Plugin(s) is critical. Enter only one.
Order: is set to 1.
Plugin Name must be credential_mapping.
Plugin Parameters are two values separated by a comma. First is the name of the Oracle Access Manager mapping base. The second is an LDAP filter specifying the name of the attribute in the directory whose value is expected to match auth-user. An example of this entry is:
ObMappingBase="o=Company, c=US", obMappingFilter="
(&(objec\]"
M NB\=-09876UYT5R4E3tclass=inetOrgPerson)
(uid=%auth-user%))"
Change the processing order in the iPlanet Obj.conf, to allow the existing authentication method to execute first, and set the iPlanet user-auth variable.
For example:
In the obj.conf file for the Web Server, locate the line:
AuthTrans fn="OBWebGate_Authent"
Comment it out by inserting a "#" at the beginning of the line.
Copy the line, without the "#", to the line directly after the line reading:
PathCheck fn="check-acl" acl="default"
In this new line, change AuthTrans to ObjectType.
The obj.conf file content would then appear as follows:
<Object name="default">
#AuthTrans fn="OBWebGate_Authent"
NameTrans fn="pfx2dir" from="/oblix/apps/webgate/bin/
webgate.cgi" dir="/" name="web_gate"
NameTrans fn="pfx2dir" from="/oberr.cgi" dir="/"
name="oberr"
. . .
PathCheck fn="check-acl" acl="default"
ObjectType fn="OBWebGate_Authent" dump="true"
Note:
This change, done in this way, is necessary in order to force WebGate to run after check-acl authentication. Netscape ACL processing, including authentication, is done in the PathCheck check-acl directive. WebGate needs to run after check-acl in order to pick up the auth-user variable whose value is expected to have been set by the authentication method. It will not work to simply put a PathCheck directive for WebGate after the check-acl directive because check-acl is always the last PathCheck directive run, regardless of the order given in obj.conf. The method described here, putting WebGate in as an ObjectType directive, has been tested and works.Stop and start the Web Server and the Access Server to ensure that these changes go into effect.
Oracle Access Manager normally enables access to all resources that are not specifically protected by a policy domain. You can deny access to any user if the requested resource is not protected by a policy domain by setting the DenyOnNotProtected field to true in the WebGate configuration GUI. The DenyOnNotProtected field is set to false by default. See Oracle Access Manager Access Administration Guide for details.
Note:
Be sure to modify this parameter for each WebGate.To modify an AccessGate through the Access System Console
Launch the Access System Console, click the Access System Configuration tab, then click the AccessGate Configuration link in the left navigation pane.
The Search for AccessGates page appears.
Select the search attribute and condition from the lists, or select All to find all AccessGates.
The Search list is a selection list of attributes that can be searched. The remaining fields allow you to specify search criteria that are appropriate for the selected attribute.
Click Go.
The search results are displayed on the page.
Click the name of the WebGate that you want to modify.
The AccessGate Details page appears.
Click Modify.
The Modify AccessGate page appears. You can enter new information on this page
You cannot change a WebGate's name. To rename it, you must delete it from the Access System Console and then uninstall it. You then create a new WebGate.
Type new values as needed.
Click Save to save your changes or click Cancel to exit the page without saving.
|
 Copyright © 2000, 2009, Oracle. All rights reserved. Legal Notices |
|