OAM_REQ is a transient cookie that is set or cleared by Access Manager if the authentication request context cookie is enabled. This cookie is protected with keys known to Access Manager only. 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 it to the credential collector page to collect credentials. The OAM Server also sends 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%>">
<%
}
%>

See Also, Understanding SSO Cookies in Fusion Middleware Administering Oracle Access Management.

Programmatic authentication using HTTP client APIs is supported for the OAM Server. The following sections have more information.

• Program based authentication using OAM Server

• Process Overview: Developing Programmatic Clients

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.

1. Configure the DCC WebGate.

   See Configuring a DCC WebGate for X509 Authentication in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

2. Enable Direct Authentication.

   Ensure that ServiceStatus under DirectAuthenticationServiceDescriptor in the oam-config.xml file is set to true. The DirectAuthenticationServiceDescriptor parameter is under OAMServicesDescriptor.

3. Add TunneledUrls=/oam/server/authentication to the User-defined parameters of the DCC WebGate profile.

   /oam/server/authentication is a Direct Authentication URL.

4. Restart the DCC WebGate.
5. Ensure that the host/port variation is added to the resource's WebGate.

   For example, if the resource's WebGate is http://<RWG-Host>:<port>/, add the host variation <RWG-Host> and the port variation <port> to the Host Identifier.

   Note:

   DCC WebGates require no configuration in the Host Identifier so add the host variation to the resource's WebGate host identifier only. The resource WebGate and DCC WebGate have different profiles and sets of host identifiers.

6. Protect /pages/login.jsp and /oam/** and /oamsso-bin/login.pl with the Public Resource Authentication and Authorization Policy of the DCC WebGate application domain.

   /oam/server/authentication should be protected by the Public Resource Authentication and Authorization Policy scheme in the DCC Application Domain. /oamsso-bin/login.pl and /pages/login.jsp are login pages and should be marked as public resources in the DCC. The successurl value needs to be protected and is provided as the post parameter.

   Note:

   See Authentication Using Unsolicited POST to configure the Authentication Scheme for the resources protected using the Direct Authentication URL.

7. The DCC authentication end point can be accessed here at http://<dcc-host>:<dcc-port>/oam/server/authentication.

   There is a TYPE parameter which can be mapped to a specific application. Post the username, password and successurl parameters to this DCC end point to access the resource.

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 to process the redirect from the user and render the HTML using your preferred technology (JSP, ASP.net, Perl, PHP, and so on). This allows you to customize the look and feel of the page so it reflects company standards, and it enables pre-processing of the user's submission (POST) before their credentials are sent to the OAM Server, if desired.

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 Returning the OAM_REQ Token.

• The page must retrieve the end point. See Returning the End Point.

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 page or application you have written.

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.

Once a custom Error page is packaged and deployed as an out-of-the-box Web application archive (WAR) file, use the updateCustomPages WLST command to enable and disable it. The custom Error page has a specific location that must be respected when deploying the custom web application. The location is:

http(s)://<host>:<port>/<context>/pages/Error.<pageExtension>

See Also,

Oracle Fusion Middleware WebLogic Scripting Tool Command Reference for Identity and Access Management. For information on updateCustomPages and other WLST commands.

Specifying the Custom Error and Logout Page Deployment Paths

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.

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:

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 returned by the OAM Server, such as OAM-1.

A custom login page can be associated with a custom resource bundle to transform the error codes to meaningful messages that can be 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.

A local resource bundle file must be created with 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.

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!"},
        {"", ……};
             }
     }

<%@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>

A basic Web archive (WAR) file that includes the required translation bundles for login and password pages is provided when Access Manager is installed. This WAR is called oamcustompages.war and is the starting point for customizing password pages. A custom password service form page has the following requirements:

• The page must support retrieval of the OAM_REQ token as documented in Returning the OAM_REQ Token.

• The page must retrieve the end point as documented in Returning the End Point.

The WAR is located in the $IDM_HOME//oam/server/tools/custompages/ directory. The advantage of using the WAR is that the basic structure is already in place. **INTERNAL XREF ERROR** displays the structure of the WAR; the CSS and images can be customized as per your requirements.

Figure 4-2 Unarchived WAR

Three modes of request cache are supported: basic, form and cookie.

• Basic mode defines the request_id as a mandatory parameter that must be sent back.

• Form mode defines the OAM_REQ token as mandatory and should be sent back, if available.

• Cookie mode sets OAM_REQ as a cookie.

1. Log in to the Access Manager Administration Console as administrator.
2. Click the Password Policy link under Access Manager.
3. Define or modify the value of the Password Service URL attribute.
4. Click Apply.

A user-facing page has access to the number of days before which the password will expire. The following code snippet illustrates how to obtain the number of days or hours before the password expires.

String message = "";
if(errCode != null && errCode.equals("1")) {
message = msgBundle.getString("USER_PSWD_WARNING") + errCode +
msgBundle.getString("USER_PSWD_DAY");
} else if (errCode != null && errCode.equals("0")) { message =
msgBundle.getString("USER_PSWD_WARNING_HOURS"); } else {
message = msgBundle.getString("USER_PSWD_WARNING")+ " " + errCode + " " +
msgBundle.getString("USER_PSWD_DAYS");
}

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 = "";
			if(result !=null && 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("::") + 2, 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

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-5 lists the available error codes, message key, and the corresponding message that can be returned during password validation.

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

The primary differences when using the DCC to collect credentials from a custom page include the following:

• The 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 customizing login pages for supported authentication mechanisms, the default error and 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, the exact location for en-us is: WebgateOH/webgate/ohs/lang/en-us/WebGate.xml.

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

• Custom pages can be deployed on the Oracle HTTP Server hosting the DCC or, in the case of JSP or Servlets, on a web container fronted by it.

• Use a configurable URL to allow HTML forms to post collected data to the DCC. The action challenge parameter in the authentication scheme specifies the URL where the credentials are expected.

• requestid query parameter handling is not required.

1. Create an HTML form from which the user's credentials (user name and password) can be submitted.

   For more information, see Understanding Form-Based Login Page authentication.

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.
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.

Custom login and error pages can be created when using DCC tunneling. The default pages are accessed from the following locations:

• Login page: http(s)://DCChost:DCCport/oam/pages/login.jsp

• Error page: http(s)://DCChost:DCCport/oam/pages/servererror.jsp

A procedure (similar to Creating a Form-Based Login Page Using DCC) should be followed to create and use these custom pages. For more details on credential collection and DCC tunneling, See Understanding Credential Collection and Login.