A Integrating Oracle ADF Applications with Access Manager SSO

The Oracle Application Developer Framework (ADF) and applications that are coded to Oracle ADF standards interface with the OPSS SSO Framework. The Oracle Platform Security Services (OPSS) single sign-on framework provides a way to integrate applications in a domain with a single sign-on (SSO) solution.

You can integrate a Web application that uses Oracle ADF security and the OPSS SSO Framework with an Access Manager SSO security provider for user authentication. This chapter provides the following sections:

A.1 Introduction to Oracle Platform Security Services and Oracle Application Developer Framework

This section provides the following topics:

A.1.1 Oracle Platform Security Services Single Sign-on Framework

A single sign-on (SSO) solution must provide a standard way for applications to login and logout users. After successful authentication, the SSO service is responsible to redirect the user to the appropriate URL.

The Oracle Platform Security Services (OPSS) SSO Framework provides a way to integrate applications in a domain with an SSO solution. Specifically, it provides applications with a common set of APIs across SSO products to handle login, auto login, and logout.

The Oracle Application Developer Framework (ADF) and applications that are coded to Oracle ADF standards interface with the OPSS SSO Framework. For more information about Oracle ADF, see "Oracle Application Developer Framework".

The Access Manager SSO solution is available out-of-the-box and provides the following to applications that are coded to Oracle ADF standards and the OPSS SSO Framework:

  • Login (application-driven): Upon accessing a part of a secured artifact that requires authentication, the application triggers authentication and redirects the user to be authenticated by the appropriate solution.

  • Auto login: A user who has initially accessed an application anonymously registers an account with the application (Oracle Identity Manager, for instance); upon a successful registration, the user is redirected to the authentication URL; the user can also be automatically logged in without being prompted.

  • Global logout: When a user logs out of one application, the logout propagates across to any other application that is enabled by the solution.

Note:

The OPSS SSO framework does not support multi-level authentication.

See Also:

Oracle Fusion Middleware Application Security Guide part "Single Sign-On Configuration" for more information about choosing an SSO solution, and the Access Manager solutions.

A.1.2 Oracle Application Developer Framework

The Oracle Application Development Framework is an end-to-end application framework that builds on Java EE standards and open-source technologies to simplify and accelerate implementing service-oriented applications.

The development and run-time environment required to deploy and manage ADF applications is similar in many ways to the environment required for other Java EE applications.

The difference between a typical Java EE environment and an environment that supports Oracle ADF applications is the availability of the Oracle ADF run-time libraries:

  • In Oracle Fusion Middleware 11g, an Oracle WebLogic Server domain, by default, does not contain the Oracle ADF run-time libraries. However, you can optionally configure or extend your domain to include the Java Run-time Files (JRF). The Oracle ADF run-time libraries are included as part of the JRF component.

    The Oracle WebLogic Server domain can be extended with the Java Run-time Files (JRF) domain template, which includes the required Oracle ADF libraries, and other important Oracle-specific technologies.

  • In Oracle Application Server 10g, each instance of OC4J automatically provided the Oracle ADF run-time libraries required to support Oracle ADF applications.

For information about the types of Java EE environments available in 10g and instructions for upgrading those environments to Oracle Fusion Middleware 11g, refer to the Oracle Fusion Middleware Upgrade Guide for Java EE.

A.2 Integrating Access Manager With Web Applications Using Oracle ADF Security and the OPSS SSO Framework

This section describes how to integrate a Web application that uses Oracle ADF security and the OPSS SSO Framework with an Access Manager SSO security provider for user authentication.

Before the Web application can be run, you must configure the domain-level jps-config.xml file on the application's target Oracle WebLogic Server for the Access Manager security provider.

The domain-level jps-config.xml file is in the following path and should not be confused with the deployed application's jps-config.xml file:

domain_home/config/fmwconfig/jps-config.xml 

Note:

Do not confuse the domain-level jps-config.xml file with the deployed application's jps-config.xml file.

You can use an Oracle JRF WLST script to configure the domain-level jps-config.xml file, either before or after the Web application is deployed. This Oracle JRF WLST script is named as follows:

Linux: wlst.sh

Windows: wlst.cmd

The Oracle JRF WLST script is available in the following path if you are running through JDev:

     $JDEV_HOME/oracle_common/common/bin/

In a standalone JRF WebLogic installation, the path is:

     $Middleware_home/oracle_common/wlst

Note:

The Oracle JRF WLST script is required. When running WLST for Oracle Java Required Files (JRF), do not use the WLST script under $JDEV_HOME/wlserver_10.3/common/bin.

Command Syntax

addOAMSSOProvider(loginuri, logouturi, autologinuri)

Table A-1 defines the expected value for each argument in the addOAMSSOProvider command line addOAMSSOProvider

Table A-1 addOAMSSOProvider Command-line Arguments

Argument Definition

loginuri

Specifies the URI of the login page

Note: For ADF security enabled applications, "/<context-root>/adfAuthentication" should be provided for the 'loginuri' parameter. Here is the flow:

  1. User accesses a resource that has been protected by authorization policies in OPSS, fox example.

  2. If the user is not yet authenticated, ADF redirects the user to the URI configured in 'loginuri'.

  3. Access Manager, should have a policy to protect the value in 'loginuri': for example, "/<context-root>/adfAuthentication.

  4. When ADF redirects to this URI, Access Manager displays a Login Page (depending on the authentication scheme configured in Access Manager for this URI).

logouturi

Specifies the URI of the logout page

Note: For ADF security enabled applications, logouturi should be configured based on logout guidelines in Chapter 19. For the:

  • 11g Webgate the value of the logouturi should be sought from the 11g Webgate Administrator.

  • 10g Webgate requires a logouturi value of "/oamsso/logout.html

autologinuri

Specifies the URI of the autologin page.


The procedure to configure domain-level jps-config.xml for a Fusion Web application with Oracle ADF Security enabled is part of a larger task. With the exception of the command syntax, all tasks are the same for Access Manager 10g and 11g.

For more information, see:

A.2.1 Sample SSO Configuration for Access Manager

The SSO service configuration entered with the procedure described in Oracle Fusion Middleware Application Security Guide for all tasks involving Access Manager SSO providers and an OAM Configuration Example is written to the file jps-config.xml. The data specified includes:

  • A particular SSO service

  • The auto-login and auto-logout URIs

  • The authentication level

  • The query parameters contained in the URLs returned by the selected SSO service

  • The appropriate settings for token generation

The following fragment of a jps-config.xml file illustrates the configuration of an Access Manager SSO provider. Some values are merely placeholders for actual content. Your configuration should contain values for your implementation.

Example A-1 Sample SSO Configuration for Access Manager

<propertySets>
  <propertySet name = "props.auth.url">
    <property name = "login.url.BASIC" value = "http://host:port/oam_login.cgi?level=BASIC"/>
    <property name = "login.url.FORM" value = "http://host:port/oam_login.cgi?level=FORM"/>
    <property name = "login.url.DIGEST" value = "http://host:port/oam_login.cgi?level= DIGEST"/>
    <property name = "autologin.url" value = " http://host:port/obrar.cgi"/>
    <property name = "logout.url" value = "http://host:port/logout.cgi"/>
    <property name = "param.login.successurl"  value = "successurl"/>
    <property name = "param.login.cancelurl"   value = "cancelurl"/>
    <property name = "param.autologin.targeturl" value = "redirectto"/>
    <property name = "param.autologin.token"   value = "cookie"/>
    <property name = "param.logout.targeturl"   value = "targeturl"/>
  </propertySet>

  <propertySet name="props.auth.uri">
    <property name="login.url.BASIC" value="/${app.context}/adfauthentication?level=BASIC" /> 
    <property name="login.url.FORM" value="/${app.context}/adfauthentication?level=FORM" /> 
    <property name="login.url.DIGEST" value="/${app.context}/adfauthentication?level=DIGEST" /> 
    <property name="autologin.url" value="/obrar.cgi" /> 
    <property name="logout.url" value="/${oamsso/logout.html" /> 
  </propertySet>

  <propertySet name = "props.auth.level">
    <property name = "level.anonymous" value = "0"/>
    <property name = "level.BASIC"    value = "1"/>
    <property name = "level.FORM"    value = "2"/>
    <property name = "level.DIGEST"   value = "3"/>
  </propertySet>
<propertySets>

<serviceProviders>
  <serviceProvider name = "sso.provider"
    class = "oracle.security.jps.internal.sso.SsoServiceProvider" 
    type = "SSO">
    <description>SSO service provider</description>
  </serviceProvider>
</serviceProviders>

<serviceInstances>
  <serviceInstance name = "sso" provider = "sso.provider">
    <propertySetRef ref = "props.auth.url"/>
    <propertySetRef ref = "props.auth.level"/>
    <property name = "default.auth.level" value = "2"/>
    <property name = "token.type" value = "OAMSSOToken"/>
    <property name = "token.provider.class" value = "oracle.security.wls.oam.providers.sso.OAMSSOServiceProviderImpl"/>
  </serviceInstance>
</serviceInstances>

<jpsContexts default = "default">
  <jpsContext name = "default">
    <serviceInstanceRef ref = "sso"/>
  </jpsContext>
</jpsContexts>

A.2.2 SSO Provider Configuration Details

Note the following important points:

  • Any SSO provider must define the URI for at least the FORM login with the property login.url.FORM. The value need not be a URL.

  • If the application supports a self-registration page URI or URL, it must be specified with the property autologin.url.

  • If the SSO solution supports a global logout URI or URL, it must be specified with the property logout.url. The OAM solution supports global logout.

  • The following properties, illustrated in Example A-1, are optional:

    • param.login.successurl

    • param.login.cancelurl

    • param.autologin.targeturl

    • param.login.token

    • param.logout.targeturl

  • The use of the variable app.context in URI specifications, in values within the property set props.auth.uri for instance, is allowed for only ADF applications when integrating with the Access Manager solution.

  • The property set props.auth.level is required.

  • The reference to props.auth.url is required.

  • The property sso.provider.class within a service instance of the SSO provider is the fully qualified name of the class implementing a specific SSO solution.

    In the case of the OAM solution, the provided class name is oracle.security.wls.oam.providers.sso.OAMSSOServiceProviderImpl.

  • The property name default.auth.level within a service instance of the SSO provider must be set to "2", as illustrated in Example A-1.

  • The property token.type within a service instance of the SSO provider is required.

    This token type identifies the token set on the HTTP request by the SSO provider upon a successful authentication; the SSO provider uses this token, after the first time, to ensure that the user does not need to be reauthenticated and that his sign-on is still valid. In the case of the OAM solution, the token type must be OAMSSOToken, as illustrated in Example A-1.

  • The property token.provider.class within a service instance of the SSO provider is the fully qualified name of the token class, and it is provider-specific.

  • An application that implements a self-registration logic and wants to auto login a user after successful self-registration, it must call the OPSS autoLogin API; in turn, to allow this call, it must grant that application a code source permission named CredentialMapping with class JpsPermission.

    The following fragment of the file system-jazn-data.xml illustrates the specification of this permission to the application MyApp:

    <grant>
      <grantee>
        <codesource>
          <url>file:${domain.home}/servers/MyApp/-</url>
        </codesource>
      </grantee>
      <permissions>
        <permission>
          <class>oracle.security.jps.JpsPermission</class>
          <name>CredentialMapping</name>
        </permission>
      </permissions>
    </grant>
    

A.3 Configuring Centralized Logout for Oracle ADF-Coded Applications

The Access Manager SSO solution is available for applications that are coded to Oracle ADF standards and the OPSS SSO Framework. ADF-coded applications that are configured to perform logout with Access Manager, redirect to the /oamsso/logout.html resource.

IAMSuiteAgent intercepts and processes the request, cleans up the session, redirects to the central logout page (done by the OAM Server) and redirects back to the end_url.

See Also:

Oracle Fusion Middleware Application Security Guide

Note:

For ADF applications, only one extra configuration step is needed (to configure the OAMSSOProvider for OPSS).

Task overview: Protecting ADF-coded applications with Access Manager

  1. Review "About Centralized Logout Processing for Applications Coded to Oracle ADF Standards".

  2. Protect the ADF-coded application using either an:

    • 11g Webgate

    • 10g Webgate

  3. Perform the single extra configuration step for ADF-coded applications: configure the OAMSSOProvider as described in "Configuring Centralized Logout for ADF-Coded Applications with Access Manager".

  4. Perform logout configuration steps for your chosen Webgate version.

A.3.1 About Centralized Logout Processing for Applications Coded to Oracle ADF Standards

ADF-coded applications refer to either applications that have been fully integrated with ADF or those that simply use ADF Authentication Servlet to integrate with OPSS.

In this case, logout is initiated when an ADF application causes the invocation of the logout URI. The following process overview outlines the Access Manager centralized logout process for applications coded to Oracle ADF standards.

Process overview: Centralized logout for ADF applications with 10g Webgate

  1. An ADF application causes the invocation of the following URI.

    /<application context root>/adfAuthentication?logout=true&end_url=<any uri>
    

    The end_url parameter specifies the URI to which the application returns control following logout.

  2. ADF invokes the configured OPSS SSO provider (OAM in this case) and delegates the logout functionality to the configured logout URI by redirecting the request to the logout URI. The end_url value is passed as a query string to the logout URI. For example: /oamsso/logout.html?end_url=<end_uri>.

  3. The logout URI is invoked on the Webgate front-ending the application.

  4. 10g Webgate clears the ObSSOCookie for its domain and loads the logout.html script.

  5. If the end_url parameter does not include host:port, the logout.html script gets the host:port of the local server and constructs the end_url parameter as a URL. For example:

    http://serverhost:port/oam/server/logout?end_url=http://my.site.com/ 
    welcome.html
    
  6. Logic in logout.html redirect to the OAM Server. For example:

    http://myoamserverhost:port/oam/server/logout?end_url=http://my.site.com/
    welcome.html
    
  7. The OAM Server executes logout as follows:

    1. Cleans up the session information associated with the user at the server side.

    2. Validates the end_url and sends a page with callback URLs to the user's browser.

      Note:

      The Logout Callback URL is specified in the expanded (not short) OAM Agent registration, as described in Table 13-3.

    3. From the callback page, a new request is initiated to a specific URI on each Webgate. When this request reaches the specific Webgate in the specific domain, the ObSSOCookie for that domain is cleared.

    4. The user is redirected to the end_url in the logout script. However, if the end_url parameter is not present, an appropriate message is sent by the OAM Server.

A.3.2 Configuring Centralized Logout for ADF-Coded Applications with Access Manager

The following procedure is similar to configuring logout for 10g Webgates, with specific step for ADF-coded applications. The ADF-coded application must send the end_url value to identify where to redirect the user after logout processing. However, with ADF-coded applications, logout occurs when the application causes the following URI to be invoked:

 /<app context root>/adfAuthentication?logout=true&end_url=<any uri>

Note:

The Applcore f/w could facilitate triggering of the above URL and the ADF application could leverage that.

Some steps in this procedure require the WebLogic Scripting Tool (WLST): wlst.sh (Linux) or wlst.cmd (Windows), which you must invoke from the WLST_install_dir.

To configure centralized logout for ADF-coded applications

  1. Check with the Administrator to confirm the location of the logout.html script configured with the agent, which you need in following steps.

  2. Configure OPSS for OAM as the SSO provider to update jps-config.xml for the WebLogic administration domain, as follows:

    1. On the computer hosting the Oracle WebLogic Server and the Web application using Oracle ADF security, locate the Oracle JRF WLST script. For example:

      cd $ORACLE_HOME/oracle_common/common/bin
      
    2. Connect to the computer hosting the Oracle WebLogic Server, enter the Administrator ID and password, and the host and port of the WebLogic AdminServer:

      wls:/> /connect('admin_ID', 'admin_pw', 'hostname:port' 
      

      For example, the Oracle WebLogic Administration Server host could be localhost using port 7001. However, your environment might be different.

    3. Check with the Administrator to confirm the location of the logout.html script configured with the agent.

      In Step d, you must use the value provided by the Administrator. Here, logouturi value is the URI of the logout script /logout.html. The value could either begin with "logout." (exceptions are logout.gif and logout.jpg) or it could be any other value configured by the Administrator.

    4. Enter the loginuri for ADF authentication and the logouturi (location of the logout.html script configured with the agent); the host and port are not needed.

      wls:/>addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication",
      logouturi="/oamsso/logout.html", autologinuri="/obrar.cgi")
      

      Here, loginuri=/${app.context}/adfAuthentication; logouturival is the URI of the logout script /logout.html. The logouturl could either begin with "logout" (exceptions are logout.gif and logout.jpg) or it could be any other value configured by the Administrator.

  3. Required: The ADF application must pass the end_url parameter indicating where to redirect the user after logout, as follows:

    If the end_url parameter does not include host:port, the logout.html script gets the host:port of the local server and constructs the end_url parameter as a URL. For example:

    http://serverhost:port/oam/server/logout?end_url=http://serverhost:port/ 
    welcome.html
    
  4. 11g Webgate: Perform steps in "Configuring Centralized Logout for 11g Webgates".

  5. 10g Webgate: Perform steps in "Configuring Centralized Logout for 10g Webgate with 11g OAM Servers".

See Also:

"Scenario: Identity Propagation with the Access Manager Token" for details about setting up providers for Access Manager Identity Assertion.

A.4 Confirming Application-Driven Authentication During Runtime

As mentioned earlier in this chapter, it is the application that triggers authentication and redirects the user to be authenticated by the appropriate solution. For instance, when the application determines that a user is accessing a part of a secured artifact that requires authentication application-driven authentication is triggered, in this case using Access Manager SSO.

To confirm application-driven authentication during run time

  1. Create the application based on the Oracle ADF framework.

  2. Configure the Access Manager SSO Security provider, as described in "Integrating Access Manager With Web Applications Using Oracle ADF Security and the OPSS SSO Framework".

  3. Access the protected field and confirm that the application triggers authentication.