Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Access Management
11g Release 2 (11.1.2)

Part Number E27134-03
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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:

4.1 Introduction to Custom Pages

This section contains the following topics:

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 follows
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:

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:

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%2Fmycompany.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:

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:

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:

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:

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

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=".mycompany.com")
 
updateOSSOResponseCookieConfig(cookieName="ORASSO_AUTH_HINT", cookieMaxAge = "-1", isSecureCookie = "false", cookieDomain=".mycompany.com")
 
updateOSSOResponseCookieConfig(cookieName="ORASSO_UCM_COOKIE2", isSecureCookie = "true", cookieDomain=".us.mycompany.com")
 
deleteOSSOResponseCookieConfig(cookieName = "ORASSO_UCM_COOKIE2")