4 Developing Custom Pages

The OAM Server provides default login, logout, and error pages. You can also create custom login and error pages tailored for your company look and feel to use with Access Manager. This chapter explains how to develop custom pages and how to deploy them in your environment. This chapter provides the following sections:

• Section 4.1, "Introduction to Custom Pages"

• Section 4.2, "Developing Custom Login Pages"

• Section 4.3, "Developing Custom Error Pages"

• Section 4.4, "Developing Using the Detached Credential Collector"

• Section 4.5, "Deploying the Custom Login Page"

• Section 4.6, "Programmatic Authentication"

• Section 4.7, "Setting Custom OSSO Cookies After Authentication"

4.1 Introduction to Custom Pages

This section contains the following topics:

• About Developing Custom Pages

• About Authentication and Custom Pages

4.1.1 About Developing Custom Pages

Access Manager provides an extensible framework for creating customized user login experience. You can create custom interactive pages for authentication during login, logout, and error conditioning processing. In its simplest form, Access Manager provides a set of static HTML pages that are displayed to the user. However, the user interface is generally dynamic, which requires that it be implemented as a script or an application that can perform the required logic.

Access Manager provides a set of default dynamic pages for user interaction. These default pages may be customized for your company look and feel, or replaced entirely with custom pages. For example, you can design, implement, and deploy a custom dynamic page that displays a different version of the login form depending on whether the user is accessing via a mobile browser or a desktop browser.

A custom page can be developed to use in combination with existing Access Manager authentication modules or in combination with a custom authentication plug-in. This chapter provides information about developing custom pages for login, logout, and errors. For more information about developing a custom authentication plug-in, see Chapter 3, "Developing Custom Authentication Plug-ins".

The following two OAM Server credential collection components can be alternatively enabled to serve as the communication endpoint and facilitate interaction with the customized user interface:

• The Embedded Credential Collector (ECC) can be used with no additional installation and setup steps.

• The Detached Credential Collector (DCC) is recommended for greater scalability and security isolation in production deployments.

For more information about the OAM Server credential collectors, see "Configuring 11g Webgate for Dynamic Credential Collection" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

Regardless which credential collection component is enabled for communicating with users, the design and implementation of custom pages in your environment is almost identical. For information about development differences between the two credential collection options, see Section 4.4, "Developing Using the Detached Credential Collector".

4.1.2 About Authentication and Custom Pages

The authentication process involves determining what credentials a user must supply when requesting access to a resource, gathering the credentials over HTTP, and returning an HTTP response that is based on the results of credential validation.

Figure 4-1 shows the end-to-end request flow for authenticating a user accessing an OAM protected resource that results in an error page.

Figure 4-1 Authentication Request Flow

Description of "Figure 4-1 Authentication Request Flow"

Process Overview: Authentication Request Flow

1. A user requests a protected resource. An authentication flow is triggered and the login page is displayed. The required credentials are submitted to the authentication engine.

2. The resource is protected by a specific authentication scheme, which uses the authentication (AuthN) plug-in. The AuthN plug-in uses the Identity Store APIs to authenticate the credentials. The AuthN plug-in can also call a third-party API (not shown).

3. The Identity Store API establishes a connection to the backend store to complete authentication. AD and OVD are shown as example identity stores.

4. The results, including any authentication error codes, are returned by the Identity Store layer and sent to the plug-in and the authentication engine layer. The authentication layer maps the error codes from the backend to the corresponding OAM Server error codes. For more information about the standard error codes, see Table 4-2.

   The results include native error codes acquired from the identity stores, and returning those error codes to the login page as unmapped secondary error codes (p_sec_error_msg). For more information about secondary error codes, see Section 4.3.6, "Secondary Error Message Propagation".

5. The error codes are returned as query parameters to the error or login page. Error codes are transmitted as HTTP Request parameters to the error page. The query parameter is named p_error_code.

6. The primary error code message is a localized string containing the detailed text for the error code. This can be obtained from the appropriate resource bundle file using the error code.

4.2 Developing Custom Login Pages

This section contains the following topics:

• Creating a Form-Based Login Page

• Page Redirection Process

4.2.1 Creating a Form-Based Login Page

Form-based authentication enables the development of customized Web forms that process login credentials using Access Manager's authentication mechanisms. These forms are HTML pages that enable you to present login information in different languages, to display user interface elements that comply with your company's presentation standards, and to add functions required for password management.

The form or login application can be written using your preferred technology to process the redirect from the user and render the HTML. A custom login page can be written as a JSP page, or using ASP.net, Perl, PHP, and so on. One advantage is you can customize the look and feel of the page so it matches company standards. Another advantage is it enables pre-processing of the user's submission (POST) before their credentials are sent to the OAM Server, if this is desired.

When writing a custom login page for authentication by Access Manager, a common method is to redirect a user to a login page that is hosted outside of the OAM Server. The user is redirected to the custom login page or application you have written. For more information, see Section 4.2.2, "Page Redirection Process".

Three modes of request cache are supported: basic, cookie, and form. When working in basic mode, the request_id is a mandatory parameter and should be sent back. In form mode, the OAM_REQ token is mandatory and should be sent back if available. In cookie mode, OAM_REQ is set as a cookie.

A custom login form page has the following requirements:

• The page must be built to support the desired authentication module.

• The page must support retrieval of the OAM_REQ token. See Section 4.2.1.1, "Returning OAM_REQ Token".

• The page must retrieve the end point. See Section 4.2.1.2, "Returning the End Point".

4.2.1.1 Returning OAM_REQ Token

OAM_REQ is a transient cookie that is set or cleared by the OAM Server if the authentication request context cookie is enabled. This cookie is protected with keys known to the OAM Server only. For more information, see "Introduction to SSO Cookies" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

OAM_REQ must be retrieved from the query string and sent back as a hidden form variable.

When a resource is requested, the OAM Server redirects or forwards to the credential collector page to collect credentials. The OAM Server also send an OAM_REQ token to the login page. In the case of a customized login application, the login application should ensure that the OAM_REQ token is retrieved from the request and posted back to the OAM Server along with the credentials. OAM_REQ must be retrieved from the query string and sent back as a hidden form variable. For example:

String reqToken = request.getParameter(GenericConstants.AM_REQUEST_TOKEN_IDENTIFIER);
 
<%
if(reqToken != null && reqToken.length() > 0) { %>
<input type="hidden" name="<%=GenericConstants.AM_REQUEST_TOKEN_IDENTIFIER%>" value="<%=reqToken%>">
<%
}
%>

4.2.1.2 Returning the End Point

The end point, /oam/server/auth_cred_submit, must be returned to the OAM Server. For example:

<form action="/oam/server/auth_cred
_submit"> or "http://oamserverhost:port/oam/server/auth
_cred_submit".

4.2.2 Page Redirection Process

When a form-based authentication scheme has been created with an external challenge type, the OAM agent redirects the user first to the obrareq.cgi URL, which in turn redirects the user to the login page specified as the Challenge URL for the authentication scheme. The Challenge Redirect URL declares the DCC or ECC endpoint. The Challenge URL is the URL associated with the Challenge method such as FORM.

On the redirect page, request_id and redirect_url are added to the query string. For example:

?request_id=5092769420627701289&redirect_url=http%3A%2F%2Fexample.com%3A7777%2Fscripta%2Fprintenv

When using the x509 authentication scheme there is no separate page for login credentials as authentication occurs transparently. However, page redirection also applies to non-form based authentication methods. For example, when using an x509 Authentication Scheme, you can direct users to a confidentiality disclaimer statement, or similar, before a protected resource is displayed. In this case, enter the path to the disclaimer page and have that page redirect to the /oam/CredCollectServlet/X509 page. Be sure to present the original query scheme.

4.3 Developing Custom Error Pages

This section discusses the following topics:

• Process Overview: Creating a Custom Error Page

• Standard Error Codes

• Default Page Locations

• Security Level Configuration

• Password Policy Validation Error Codes

• Secondary Error Message Propagation

• Retrieving Error Codes

• Error Data Sources Summary

See Also:

Section 3.5.3, "Error Codes in an Authentication Plug-In"

4.3.1 Process Overview: Creating a Custom Error Page

The custom error page is packaged as part of the custom login application. Under authentication policy, set the failure redirect URL to be the absolute URL to the page.

An out-of-the-box custom UI Web application archive (WAR) file is provided that can be used as a starting point to develop customized login and password pages. This WAR file is located in MW_HOME/OAM1/oam/server/tools/custompages/oamcustompages.war.

To create a custom error page, follow these steps:

1. Create the HTML page required to display the error message. For more information, see Section 4.2, "Developing Custom Login Pages".

2. Consider how error code query parameters p_error_code and p_sec_error_msg will map to the custom error codes in your environment. For more information, see Section 4.3.7, "Retrieving Error Codes".

4.3.2 Standard Error Codes

Access Manager provides standard error codes that indicate the reason for failure. Common reasons for failure include providing an invalid username and password combination, a user account is locked or disabled, or an internal processing error occurred. The reason for the authentication error is received from the backed identity store, which is then mapped to a specific error code maintained in the OAM Server. This error code is then propagated to the login or error page. For more information about the authorization request flow, see Section 4.1, "Introduction to Custom Pages".

Table 4-1 summarizes the standard error information that available in login and error pages.

Table 4-1 Types of Error Information

Message Type	Description
Error code	A string containing a specific number. The error codes are managed solely by Access Manager. Query string parameter is named p_error_code.
Primary error message	A localized string containing the detailed text for the error code. Is based on the client locale, namely, the user's browser language setting.
Secondary error message	A non localized string containing the real cause for the failure. Secondary error message can be provided by a custom authentication plug-in or be returned by an identity store. Query string parameter is named p_sec_error_msg.

Table 4-2 lists all the error message codes sent by the OAM Server and the corresponding primary error message. If a primary error message has been customized for an application, the application must map this custom message to the corresponding standard error message maintained by OAM Server. There is no difference between OAM-1 and OAM-2 error codes.

Table 4-2 Standard Error Codes and Message

Error Code	Primary Error Message
OAM-1	An incorrect Username or Password was specified.
OAM-2	An incorrect Username or Password was specified.
OAM-3	Unexpected Error occurred while processing credentials. Please retry your action again!
OAM-4	System error. Please contact the System Administrator.
OAM-5	The user account is locked or disabled. Please contact the System Administrator.
OAM-6	The user has already reached the maximum allowed number of sessions. Please close one of the existing sessions before trying to login again.
OAM-7	System error. Please re-try your action. If you continue to get this error, please contact the Administrator.
OAM-8	Authentication failed.
OAM-9	System error. Please re-try your action. If you continue to get this error, please contact the Administrator.
OAM-10	The password has expired. Please contact the System Administrator.

4.3.3 Default Page Locations

In the case where the Embedded Credential Collector (ECC) is used, the default pages are accessed as follows:

• Login page: http(s)://host:port/oam/pages/login.jsp

• Error page: http(s)://host:port/oam/pages/servererror.jsp

In the case where the Detached Credential Collector (DCC) is used, the default pages are accessed as follows:

• Login page: /oamsso-bin/login.pl

• Login action URL: /oam/server/auth_cred_submit. This is the default action URL if no action is configured in the authentication scheme parameters. No corresponding physical page is located with the default URL. A physical page is needed at the URL location only when an action has been configured in the authentication scheme and a runtime action type results in a pass through on the action URL.

• Error page: /oberr.cgi. This is a URL pattern recognized by DCC and is not a physical location.

4.3.4 Security Level Configuration

An error code's security level determines the error code that is returned by OAM Server. The security level is configured by an administrator using the Access Manager Configuration panel in the administration console. The following security level settings are available when configuring error codes for custom login pages:

• SECURE: Most secure level. Provides a generic primary error message that gives little information about the internal reason for the error.

• EXTERNAL: The recommended level and is the default.

• INTERNAL: The least secure level. Enables propagation of error code to login or error page.

Table 4-3 lists the standard error codes (see Table 4-2) that are propagated to the login or error page according to security level.

Table 4-3 Error Condition Mapping by Security Level

Error Condition	Internal Mode	External Mode	Secure Mode
Invalid login attempt.	OAM-1	OAM-2	OAM-8
Processing submitted credentials failed for a reason. For example, in WNA mode the spnego token is not received.	OAM-3	OAM-3	OAM-8
An authentication exception is raised for a reason.	OAM-4	OAM-4	OAM-9
User account is locked due to certain conditions. For example, the invalid attempt limit is exceeded.	OAM-5	OAM-5	OAM-8, or OAM-9 if OIM is integrated
User account is disabled.	OAM-5	OAM-5	OAM-9
User exceeded the maximum number of allowed sessions. This is a configurable attribute.	OAM-6	OAM-6	OAM-9
Can be due to multiple reasons. The exact reason is not propagated to the user level for security reasons. Is the default error message displayed when no specific error messages are propagated up.	OAM-7	OAM-7	OAM-9

When an error condition occurs, the OAM Server will forward to the default error page, unless the default page has been overridden as a failure-redirect-url in the authentication policy. When using a custom error page, the absolute error page URL must be set as the failure_redirect_url in the authentication policy so that the server will redirect to the custom page. The custom login page typically has the logic to serve as the error page.

In the case of error conditions OAM-1 and OAM-8, which enable the credentials to be collected again, the user is returned to the login page.

4.3.5 Password Policy Validation Error Codes

The password plug-in redirects to the password pages and the corresponding message is received from the password policy. These error codes are sent to the password policy pages as HTTP Request parameter named ruleDes.

Table 4-4 lists the available error codes, message key, and the corresponding message that can be returned during password validation.

Table 4-4 Password Validation Error Codes

Message Key in URL	Message Key for Resource Bundle	Message Text
PSWD-1	passwordPolicy.message.minLength	Password must be at least {0} characters long
PSWD-2	passwordPolicy.message.maxLength	Password must not be longer than {0} characters
PSWD-3	passwordPolicy.message.minAlpha	Password must contain at least {0} alphabetic characters
PSWD-4	passwordPolicy.message.minNumber	Password must contain at least {0} numeric characters
PSWD-5	passwordPolicy.message.minAlphaNumeric	Password must contain at least {0} alphanumeric characters
PSWD-6	passwordPolicy.message.minSpecialChars	Password must contain at least {0} special characters
PSWD-7	passwordPolicy.message.maxSpecialChars	Password must not contain more than {0} special characters
PSWD-8	passwordPolicy.message.maxRepeated	Any particular character in the password must not be repeated more than {0} times
PSWD-9	passwordPolicy.message.minUnique	Password must contain at least {0} unique characters
PSWD-10	passwordPolicy.message.minUpperCase	Password must contain at least {0} uppercase letters
PSWD-11	passwordPolicy.message.minLowerCase	Password must contain at least {0} lowercase letters
PSWD-12	passwordPolicy.message.maxAge	Password will expire {0} days after the last password change
PSWD-13	passwordPolicy.message.warnAfter	Password change reminder will be sent {0} days after the last password change
PSWD-14	passwordPolicy.message.reqdChars	Password must contain the following characters: {0}
PSWD-15	passwordPolicy.message.invalidChars	Password must not contain the following characters: {0}
PSWD-16	passwordPolicy.message.validChars	Password can contain the following characters: {0}
PSWD-17	passwordPolicy.message.invalidStrings	Password must not contain the following strings: {0}
PSWD-18	passwordPolicy.message.startsWithChar	Password must start with an alphabetic character
PSWD-19	passwordPolicy.message.disAllowUserId	Password must not match or contain user ID
PSWD-20	passwordPolicy.message.disAllowFirstName	Password must not match or contain first name
PSWD-21	passwordPolicy.message.disAllowLastName	Password must not match or contain last name
PSWD-22	passwordPolicy.message.dictMessage	Password must not be a dictionary word
PSWD-23	passwordPolicy.message.enforceHistory	Password must not be one of {0} previous passwords
PSWD-24	passwordPolicy.message.minAge	Password cannot be changed for {0} days after the last password change
PSWD-25	passwordPolicy.message.minUnicode	Password must contain at least {0} Unicode characters
PSWD-26	passwordPolicy.message.maxUnicode	Password must not contain more than {0} Unicode characters

4.3.6 Secondary Error Message Propagation

The authentication engine layer maps exceptions from the backend identity store to error codes specific to OAM Server. These codes are then propagated. Plug-ins can retrieve the secondary error code and then propagate so that appropriate action can be taken.

Note:

The primary error codes are propagated to the error or login page in all modes. The secondary error message is propagated only when the security level is configured to be INTERNAL. For more information, see Section 4.3.4, "Security Level Configuration".

Secondary error messages are sent as HTTP Request parameters to the error page. The query parameter is named p_sec_error_msg. This message is a concatenated string of code and message text from the backend and is not translated.

For example, in the case where OVD is the backend and invalid credentials are entered, authentication fails and the cause is returned from the backend as LDAP:error code 49-Invalid Credentials and the OAM Server error code is returned as OAM-1. In this case the following data will appear in the log in page:

Entity	Description
Error Code	OAM-1
Primary Message (retrieved from the code)	An incorrect Username or Password was specified
Secondary Error Code	LDAP:error code 49- Invalid Credentials

4.3.7 Retrieving Error Codes

An error code is sent as HTTP Request parameters to the error page. The query parameter is named p_error_code. This parameter value will contain error code values, such as OAM-1, that is returned by the OAM Server. See Table 4-2 for standard Access Manager error codes and corresponding message. These error codes do not have supplementary information.

A custom login page can be associated with a custom resource bundle to transform the error codes to be meaningful messages that are displayed to the end user. However, if the custom login page does not require meaningful error messages or translations, then the custom resource bundle is not required.

4.3.7.1 Code Samples

A local resource bundle file must be created with and the error condition mapped to Access Manager error codes as summarized in Table 4-3. The file can be consumed in the login or error page.

Example 4-1 provides a resource bundle code sample and Example 4-2 provides an error code page sample.

Example 4-1 Resource Bundle Code

package mytest.error;
     Import java.util.ListResourceBundle;
  public class ExampleErrorMsg extends ListResourceBundle {
        /* (non-Javadoc)
         * @see java.util.ListResourceBundle#getContents()
         */
        public Object[][] getContents()
    {
        return m_contents;
    }
    /** The Constant m_contents. */
    private static final Object[][] m_contents =
     {
        {"OAM-1", " An incorrect Username or Password was
 specified "},
        {"OAM-2", " An incorrect Username or Password was
 specified "},
        {"OAM-3", "Unexpected Error occurred while processing
 credentials. Please retry your action again!"},
        {"", ……};
             }
     }

Example 4-2 Error Code Page

<%@page import="mytest.error.ExampleErrorMsg"%>
  //initializing the messageBundle first
  String defaultResourceBundle = "mytest.error.ExampleErrorMsg";
  java.util.Locale myLocale = request.getLocale();
  ResourceBundle msgBundle=
 ResourceBundle.getBundle(defaultResourceBundle,myLocale);
String errCode = request.getParameter("p_error_code");
String secondaryErrMessage = request.getParameter("p_sec_error_msg");
  <%
        if(errCode != null && errCode.length() > 0) {
          try {
             simpleMessage = msgBundle.getString(errCode);
          } catch(Exception e) {
             //get the default authn failed message
             simpleMessage = msgBundle.getString("OAM-8");
          }
  %>
  <div class="message-row"> 
      <p class="loginFailed"> <%=simpleMessage%> </p> 
  </div>

4.3.7.2 Retrieving Password Policy Error Codes

A user-facing page has access to the password policy result context and has the ability to obtain applicable messages. Each message may include supplementary information, depending on the message. The following code snippet shows how a page can obtain the message and supplementary information from the password policy result context:

String simpleMessage = "";
  String result = request.getParameter("rejectedRuleDesc");
  if(result.indexOf('~') != -1) {
   String[] results = result.split("~");
   for(String eachResult : results) {
      if(eachResult.indexOf(":") != -1) {
        String messageKey = eachResult.substring(0, eachResult.indexOf(":"));
        String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(messageKey);
        String placeHolderValue = eachResult.substring(eachResult.indexOf(":") + 1, eachResult.length());
        String displayValue = Localizer.localize(resourceBundleKey, placeHolderValue, myLocale);
        simpleMessage += displayValue + "<br>";
      }
      else {
        String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(eachResult);
        String displayValue = Localizer.localize(resourceBundleKey, null, myLocale);
        simpleMessage += displayValue + "<br>";
 
      }
   }
  }

For example, if the password doesn't have enough characters, the following will be the result in context:

• PasswordRuleDescription.getResourceBundleKey() returns "passwordPolicy.error.minLength"

• PasswordRuleDescription.getPlaceHolderValue() returns minimum number of characters

• PassswordRuleDescription.eachDesc.getDisplayValue() returns fully translated message

4.3.7.3 Password Policy Rules

A user-facing page has access to the password policy rules applicable for the user. Each message may include supplementary information, depending on the message. The following code snippet shows how a page can obtain the rules and supplementary information from the password policy result context:

String simpleMessage = "";
String result = request.getParameter("ruleDesc");
if(result.indexOf('~') != -1) {
String[] results = result.split("~");
for(String eachResult : results) {
if(eachResult.indexOf(":") != -1) {
String messageKey = eachResult.substring(0, eachResult.indexOf(":"));
String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(messageKey);
String placeHolderValue = eachResult.substring(eachResult.indexOf(":") + 1, eachResult.length());
String displayValue = Localizer.localize(resourceBundleKey, placeHolderValue, myLocale);
simpleMessage += displayValue + "<br>";
}
else {
String resourceBundleKey = UrlSubstitutionMessages.ERRORCODEMAP.get(eachResult);
String displayValue = Localizer.localize(resourceBundleKey, null, myLocale);
simpleMessage += displayValue + "<br>";
 
}
}
}

For example, if the password does not have enough characters, the following will be the result in context:

• PasswordRuleDescription.getResourceBundleKey() returns "passwordPolicy.error.minLength"

• PasswordRuleDescription.getPlaceHolderValue() returns minimum number of characters

• PassswordRuleDescription.eachDesc.getDisplayValue() returns fully translated message

4.3.8 Error Data Sources Summary

Table 4-5 summarizes the error data sources available to an authentication plug-in.

Table 4-5 Authentication Plug-In Error Data Sources

Source	Parameter
Error code	HTTP Request parameter: p_error_code
Primary error message	Is obtained from the resource bundle, using the error code
Secondary Error Message (sent only in INTERNAL error mode)	HTTP Request parameter: p_sec_error_msg
Concatenated list of server error codes	HTTP Request parameter: p_error_codes_list
Password Plugin error message	HTTP Request parameter: ruleDesc
Plugin client responses	HTTP Request parameter: PLUGIN_CLIENT_RESPONSE
Plugin error responses	HTTP Request parameter: PLUGIN_ERROR_RESPONSE

4.4 Developing Using the Detached Credential Collector

This section contains the following topics:

• Detached Credential Collector Considerations

• Process Overview: Creating a Form-Based Login Page Using DCC

4.4.1 Detached Credential Collector Considerations

The primary differences when developing a custom page that uses the Detached Credential Collector (DCC) are as follows:

• DCC is installed with default pages implemented as Perl scripts using HTML templates located in the following Webgate Oracle Home (WebgateOH) directories:

  • WebgateOH/webgate/ohs/oamsso

  • WebgateOH/webgate/ohs/oamsso-bin

• In addition to login pages for supported authentication mechanisms, the default error page and default logout pages can be customized.

  The default error page is triggered when an error condition occurs outside of the authentication flow, or if the failure redirect URL is not specified in the authentication scheme. The default error page template and associated error messages are located in a language and locale specific subdirectory within the Webgate Oracle Home. For example, for en-us the exact location is: WebgateOH/webgate/ohs/lang/en-us/WebGate.xml.

  The default logout page is located in WebgateOH/webgate/ohs/oamsso-bin/logout.pl.

• DCC by itself does not constrain the choice of the language to develop the custom pages in. The pages can be either deployed on the Oracle HTTP Server hosting the DCC, or in the case of JSP or Servlets, they need to be deployed on a web container that is fronted by it.

• HTML forms used to post collected data to the DCC can do it by using a configurable URL. The action challenge parameter in the authentication scheme specifies the URL where the credentials are expected.

• requestid query parameter handling is not required.

4.4.2 Process Overview: Creating a Form-Based Login Page Using DCC

1. Create an HTML form where the user's credentials, such as user name and password, can be submitted. For more information, see Section 4.2.1, "Creating a Form-Based Login Page".

2. Place the form in an unprotected directory, or in a directory protected by an Anonymous authentication scheme, on your Web server with DCC.

3. Create a form-based authentication scheme and specify the path to the login form as the Challenge URL. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

4. Call the form action using HTTP GET or POST.

5. Protect the target URL in the action of the login form with a policy.

6. Configure the challenge parameters in the authentication scheme.

7. Specify the authentication module to use to process the credentials.

4.5 Deploying the Custom Login Page

The custom login page can be created as a WAR file and packaged with the necessary resource bundle files. The WAR file can then be deployed on an application behind a DCC, or if DCC is not used, the page can be deployed on the same server where ECC is running. When using ECC, the following settings must be specified for the Authentication scheme using the custom WAR file:

• Context Type = CustomWar

• Challenge URL = Relative path for the URL of the login page inside the WAR file

• Context Value = Custom WAR's root path. If a customized error page is included as part of the Custom WAR file, you must specify the absolute URL in the authentication policy-failure redirect URI. For example: http://host:port/SampleLoginWar/pages/MFAError.jsp.

For more information about authentication schemes and managing them, see "About the Authentication Schemes Page" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

4.6 Programmatic Authentication

This section contains the following topics:

• Using mod_osso Agent

• Using Unsolicited Post

4.6.1 Using mod_osso Agent

Programmatic authentication using HTTP client APIs is supported for both OSSO 10g and 11g OAM Server.

4.6.1.1 OSSO 10g

An OSSO 10g programmatic client typically looks for URL redirects to identify the authentication flow. The default authentication schemes are configured to use embedded login pages. OAM Server will forward to the login page instead of using redirection. For OSSO 10g style programmatic clients to work, the credential collector must be configured in external mode.

In cases of upgrade from 10g release, configure the authentication scheme SSOCoexistMigrateScheme to use the new custom login page. In cases of new 11g release installation, edit the scheme used for authenticating a resource, namely LDAPScheme.

Set the challenge URL to point to a fully qualified custom URL. For example, http://host:port/sample-web/login.jsp. Also set the context type to external. For more information, see "Managing Authentication Schemes" in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

4.6.1.2 11g OAM Server

In 11g release, the OAM Server uses javascript to transmit the login form for credential input to the client. In the case where the client or device cannot understand a script-based redirect, the user-agent the client uses must be configured as a programmatic client. OAM Server is then recognized the client as a programmatic one and not as a browser based one. In this case, OAM Server will not use javascript based redirect.

The following is an example of the configuration setting in oam-config.xml. Multiple entries can be added under the userAgentType setting.

<Setting Name="userAgentType" Type="htf:map">
   <Setting Name="Mozilla/4.0 (compatible; Windows NT 5.1)
 OracleEMAgentURLTiming/3.0" Type="xsd:string">PROGRAMATIC</Setting>
 </Setting>

4.6.1.3 Process Overview: Developing Programmatic Clients

Use the following process when developing both OSSO 10g and Access Manager 11g programmatic clients.

1. The application invokes a protected resource via HTTP channel using the client API.

2. The mod_osso partner protecting the accessed resource generates the site2pstoretoken and redirects to OAM Server for authentication.

3. OAM Server redirects to the login page with the request parameters: site2pstoretoken and p_submit_url.

   p_submit_url contains the programmatic authentication endpoint. For example: http(s)://host:port/sso/auth. The default browser action URL creates a session on the server side and is not present in the programmatic authentication endpoint. The programmatic authentication endpoint will not create a session for every authentication, rather it will use a global session for a user. This session will be the same for all authentication performed programmatically for a specific user.

4. Programmatic clients are expected to submit credentials to the programmatic endpoint.

5. Clients must submit the following information to p_submit_url: ssousername, password, s2pstoretoken (obtained in Step 3).

6. OAM Server validates credentials, and if valid, redirects the request to the initial protected application.

7. In case of credential validation error, p_error_code is returned.

4.6.2 Using Unsolicited Post

In 11g release, use the following process for programmatic authentication using unsolicited POST.

1. Enable Direct Authentication.

   In oam-config.xml, ensure that ServiceStatus under DirectAuthenticationServiceDescriptor is set to true. (DirectAuthenticationServiceDescriptor is under OAMServicesDescriptor).

2. Submit the following information to the endpoint https://oam_host:oam_port/oam/server/authentication:

   • username

   • password

   • successurl, for example, http://machinename.example.com:7778/sample-web/headers.jsp.

3. Once the credentials are validated, OAM Server redirects to the success URL after setting OAM_ID cookie as part of HTTP redirect (HTTP response code 302).

To allow direct authentication only for POST, or vice-versa:

1. Login to Oracle Access Management administration console and navigate to Policy Configuration, then Application Domains.

2. Select edit IAMSuite. Navigate to Resources, then search and edit resource /oamDirectAuthentication.

3. Under Operations, de-select all operations that are not to be supported, except POST. For example, GET, DELETE.

To change how username and password credentials are authenticated for different success URLs:

1. During the direct authentication request, along with username, password and successurl, pass another parameter type with a value specifying the authentication mechanism.

2. Go to IAMSuite application domain. Create a new resource with the resource URL /oamDirectAuthentication, and query string with name type and value specified in Step 1.

3. Associate this resource to the authentication scheme that supports the type selected.

4. Create multiple resources with the URL /oamDirectAuthentication and different values for the query string type (for example, type=FORM, type=CREDS) and associate it to corresponding authentication schemes.

4.7 Setting Custom OSSO Cookies After Authentication

For mod_osso agents, 11g release supports setting custom cookies. For 10g and 11g Webgates, this is achieved through an authentication and authorization response type cookie.

To configure OSSO custom cookies:

1. Login to Oracle Access Management administration console.

2. Navigate to the application domain for the OSSO agent.

3. Select the protected resource policy for authentication.

4. Click Responses tab.

5. Add the cookie responses. The cookies for your deployment should be created with a Name and Value that follow Access Manager 11g authentication response format. For example:

   • Name: ORASSO_AUTH_HINT, Type: Cookie, Value: v1.0~${session.expiration}

   • Name: ORASSO_UCM_COOKIE1, Type: Cookie, Value: v2.0~${user.attr.displayname}~${user.attr.given}

   • Name: ORASSO_UCM_COOKIE2, Type: Cookie, Value: v3.0~${user.attr.uid}~${user.attr.mail}

6. Save the changes.

7. Access the mod_osso protected application to verify that the cookies are being created after authentication.

The OSSO cookies are set by default on .example.com domain and the cookies are set to expire after one year. The settings can be changed using the WLST commands:

• updateOSSOResponseCookieConfig

• deleteOSSOResponseCookieConfig

For example, using updateOSSOResponseCookieConfig:

help('updateOSSOResponseCookieConfig')
 
Description:
 
Updates OSSO Proxy response cookie settings in system configuration.
Syntax:
 
 
 updateOSSOResponseCookieConfig(cookieName = "<cookieName>",cookieMaxAge = "<cookie age in minutes>", isSecureCookie = "true | false",cookieDomain="<domain of the cookie>", domainHome = "<wls_domain_home_path>")
 cookieName = Name of the cookie for which settings are updated. This is optional parameter. If parameter is not specified global setting is updated.
 cookieMaxAge = Max age of cookie in minutes. A negative value will set a session cookie.
 isSecureCookie = Boolean flag specifies if cookie should be secure which wouldbe sent only in SSL channel.
 cookieDomain = The domain of the cookie.
 domainHome = location of domain home <mandatory for offline commands,not required for online>
 
Example:
 
 
 updateOSSOResponseCookieConfig(cookieName = "ORASSO_AUTH_HINT",cookieMaxAge = "525600", isSecureCookie = "false", cookieDomain=".example.com",domainHome = "<wls_domain_home_path>") 

For example, using deleteOSSOResponseCookieConfig:

help('deleteOSSOResponseCookieConfig')
 
Description:
 
Deletes OSSO Proxy response cookie settings in system configuration.
Syntax:
 
 
 deleteOSSOResponseCookieConfig(cookieName = "<cookieName>",domainHome = "<wls_domain_home_path>")
 cookieName = Name of the cookie for which settings are updated. This is mandatoryparameter. The global cookie setting cannot be deleted.
 domainHome = location of domain home <mandatory for offline commands,not required for online>
 
Example:
 
 
 deleteOSSOResponseCookieConfig(cookieName = "ORASSO_AUTH_HINT",domainHome = "<wls_domain_home_path>")

In the update command, if cookie name is not specified, global settings for all the cookies are updated. If cookie name is specified, the parameters are overridden for the specific cookie. For example:

updateOSSOResponseCookieConfig(cookieMaxAge = "525600", isSecureCookie = "false", cookieDomain=".example.com")
 
updateOSSOResponseCookieConfig(cookieName="ORASSO_AUTH_HINT", cookieMaxAge = "-1", isSecureCookie = "false", cookieDomain=".example.com")
 
updateOSSOResponseCookieConfig(cookieName="ORASSO_UCM_COOKIE2", isSecureCookie = "true", cookieDomain=".us.example.com")
 
deleteOSSOResponseCookieConfig(cookieName = "ORASSO_UCM_COOKIE2")