Advanced Configurations for Single Sign-On

Overview

Single sign-on (SSO) is available in some of the 10.x apps when authenticating a user from a mobile device. However, some apps do not currently support this feature even if you have integrated Oracle E-Business Suite with Oracle Access Manager for single sign-on. In this situation if the mobile device has multiple Oracle E-Business Suite mobile apps, then it is required to re-authenticate the user by providing user login credentials when the user navigates from one Oracle E-Business Suite mobile app to another on the same mobile device.

Note: Oracle Maintenance for EBS is not configured for SSO by default. However, you can configure SSO for this app using the setup tasks described in this chapter. SSO is available for the Oracle Approvals for EBS, Oracle Self-Service HR for EBS, and Oracle Timecards for EBS apps through the SSO configuration of your Oracle E-Business Suite instance.

When configuring Oracle E-Business Suite mobile apps with the "Apps SSO Login" authentication type, ensure that you complete the required tasks for your app:

• Setup Tasks for Oracle Approvals for EBS, Oracle Timecards for EBS, and Oracle Self-Service HR for EBS

• Setup Tasks for Oracle Maintenance for EBS

Note: Oracle Field Service for EBS and Oracle Mobile SCM for EBS (MSCA) support single sign-on with their own app-specific configuration processes. Therefore, the setup tasks described in this chapter do not apply to these two apps.

Setup Tasks for Oracle Approvals for EBS, Oracle Timecards for EBS, and Oracle Self-Service HR for EBS

Single sign-on is available for the Oracle Approvals for EBS, Oracle Self-Service HR for EBS, and Oracle Timecards for EBS apps through the SSO configuration of your Oracle E-Business Suite instance. Therefore, you need to ensure that your Oracle E-Business Suite environment is configured for SSO first. You may need to perform additional configuration if Oracle E-Business Suite is configured with Oracle Access Manager 12c.

1. Configuring Oracle E-Business Suite with Single Sign-On

2. Performing Additional Configurations in Oracle Access Manager

3. Accessing the Apps for Oracle E-Business Suite Configured with Oracle Access Manager

Step 1: Configuring Oracle E-Business Suite with Single Sign-On

If your Oracle E-Business Suite is integrated with Oracle Access Manager (OAM), to authenticate users remotely with single sign-on, ensure that you complete the following prerequisites:

• Oracle E-Business Suite mobile apps delegate user authentication to Oracle Access Manager in the same way as supported for Oracle E-Business Suite browser-based applications. In this situation, mobile users are authenticated remotely against an external OAM server. Refer to My Oracle Support Knowledge Document 1388152.1, Overview of Single Sign-On Integration Options for Oracle E-Business Suite.

• For both browser-based applications and mobile apps, Oracle E-Business Suite certifies the form-based challenge method only.

Step 2: Performing Additional Configurations in Oracle Access Manager

If Oracle E-Business Suite is configured with Oracle Access Manager 12c, then perform the following steps on the OAM 12c instance:

1. Use the following commands to create a new 'esapi' directory in $DOMAIN_HOME/config/fmwconfig:

   cd $DOMAIN_HOME/config/fmwconfig
   mkdir esapi
   cd esapi

2. Obtain the ESAPI.properties and validation.properties files from the release notes for your app:

   • Oracle Approvals for EBS: Section 5.1 in My Oracle Knowledge Document 1642423.1, Oracle Mobile Approvals for Oracle E-Business Suite Release Notes

   • Oracle Self-Service HR for EBS: Section 5.1 in My Oracle Knowledge Document 2105189.1, Oracle Mobile Self-Service Human Resources for Oracle E-Business Suite Release Notes

   • Oracle Timecards for EBS: Section 5.1 in My Oracle Knowledge Document 1669224.1, Oracle Mobile Timecards for Oracle E-Business Suite Release Notes

3. Copy the ESAPI.properties and validation.properties files to $DOMAIN_HOME/config/fmwconfig/esapi.

4. Edit the $DOMAIN_HOME/bin/setDomainEnv.sh file, to add a new property (this is a reference to the directory where your new esapi files are located):

   EXTRA_JAVA_PROPERTIES="-Doracle.oam.esapi.resources=<Enter the full file path here to the esapi directory> ${EXTRA_JAVA_PROPERTIES}"
   export EXTRA_JAVA_PROPERTIES
   

5. Restart OAM using the following commands:

   Shutdown oam_policy_mgr1 then oam_server1
   Startup oam_policy_mgr1 then oam_server1

Step 3: Accessing the Apps for Oracle E-Business Suite Configured with Oracle Access Manager

When your Oracle E-Business Suite instance is configured for SSO, SSO is available for the Oracle Approvals for EBS, Oracle Self-Service HR for EBS, and Oracle Timecards for EBS apps through the SSO configuration of your Oracle E-Business Suite instance.

Accessing the App from the Oracle E-Business Suite Home Page

For example, in Oracle Approvals for EBS if Oracle E-Business Suite is configured for SSO, a user of the Approvals app with the SSO authentication type can directly access the app through a web page URL. If the Oracle E-Business Suite user is configured with the local authentication type, the user can access the app by clicking the Mobile icon above the Worklist table in the Oracle E-Business Suite Home page.

Oracle E-Business Suite Home Page with the Mobile Icon Highlighted

Setup Tasks for Oracle Maintenance for EBS

This section describes the following setup tasks for Oracle Maintenance for EBS:

Important: Before setting up your mobile app with any of the advanced configurations, ensure basic mobile app configuration is performed and validated. See: Validating the Configuration.

1. Configuring Oracle E-Business Suite with Single Sign-On

2. Setup Tasks to Enable the Apps SSO Login Authentication Security

3. Testing the Setup for the Apps SSO Login Authentication Security

4. Setting the Mobile App Connection to Use Apps SSO Login

Additionally, see Troubleshooting Tips on Configuring Apps With the Apps SSO Login Authentication Type.

Step 1: Configuring Oracle E-Business Suite with Single Sign-On

Before setting up app-specific tasks, you must ensure that your Oracle E-Business Suite is configured with SSO.

• Oracle E-Business Suite mobile apps delegate user authentication to Oracle Access Manager in the same way as supported for Oracle E-Business Suite browser-based applications. In this situation, mobile users are authenticated remotely against an external Oracle Access Manager (OAM) server. Refer to My Oracle Support Knowledge Document 1388152.1, Overview of Single Sign-On Integration Options for Oracle E-Business Suite.

• For both browser-based applications and mobile apps, Oracle E-Business Suite certifies the form-based challenge method only.

• In addition to the form-based challenge method, Oracle Access Manager supports several alternative authentication methods, including Oracle Identity Federation, integration with multi-factor authentication, or integration with other third-party access management systems. You may leverage Oracle Access Manager to further integrate with any of the alternative authentication mechanisms supported by Oracle Access Manager. Integration with Oracle E-Business Suite is expected to work, regardless of how Oracle Access Manager authenticates the user, provided that Oracle Access Manager protects the resources, enforces authentication, and returns the configured response headers.

  Note that Oracle E-Business Suite does not certify these alternative authentication methods. You may be asked to revert Oracle Access Manager to the certified form-based authentication before further investigation on any issues in Oracle E-Business Suite can take place.

• If you encounter issues during the configuration of Oracle Access Manager with alternative authentication mechanisms, you may contact Oracle Support for diagnosing issues related to Oracle Access Manager.

Step 2: Setup Tasks to Enable the Apps SSO Login Authentication Security

To better understand the setup tasks specifically for mobile apps with Apps SSO Login, the following diagram illustrates the high level process flow when authenticating Oracle E-Business Suite mobile users using single sign-on in the case of TLS configuration:

Note: Oracle E-Business Suite mobile apps work with any single sign-on configurations for Oracle E-Business Suite.

High Level Process Flow for Apps SSO Login Authentication with TLS Configuration

In this diagram, there are two different REST invocation points (client vs server) which require you to import certificates into appropriate truststores:

• Scenario 1: TLS client invocation from a mobile app

  This scenario invokes the following two endpoints:

  • Oracle E-Business Suite AccessGate

    A mobile user attempts to log in to an app through the value configured in the "SSO Login URL" (login/sso) parameter. The user is directed to Oracle E-Business Suite AccessGate (EAG) which is protected by the Oracle Access Manager (OAM) server for user authentication. When the user enters the login credentials in the Sign In screen, OAM verifies the credentials against user directory. If the user is successfully authenticated, OAM returns a unique OAM access token to Oracle E-Business Suite AccessGate for further identification verification, as described in Scenario 2.

  • Oracle E-Business Suite REST endpoint on the server

    Once the user is successfully authenticated to access Oracle E-Business Suite from the mobile app, the mobile app uses "EBS Session Service" (login/apps) to create a valid Oracle E-Business Suite session. The user then performs desired actions through Oracle E-Business Suite REST APIs to fetch Oracle E-Business Suite data for the app.

• Scenario 2: TLS client invocation from Oracle E-Business Suite AccessGate to invoke Oracle E-Business Suite application tier

  Oracle E-Business Suite AccessGate is a Java Enterprise Edition application that maps a single sign-on user to an Oracle E-Business Suite user. Once picking up the access token from OAM, Oracle E-Business Suite AccessGate verifies the user identification against the Oracle E-Business Suite database. If the verification is successful meaning that this is a valid Oracle E-Business Suite user, an Oracle E-Business Suite session token is returned. The session token that points to the user session will be passed to HTTP headers of all subsequent service calls for the user authentication.

  To successfully invoke the Oracle E-Business Suite application tier from Oracle E-Business Suite AccessGate as described in this scenario, custom CA or self-signed certificates used in Oracle E-Business Suite application tier should be imported to the Oracle E-Business Suite AccessGate truststore.

Based on the above high level invocation diagram, to enable the Apps SSO Login authentication for Oracle E-Business Suite mobile apps, you need to perform the following setup tasks to ensure Oracle E-Business Suite AccessGate is deployed properly and its required certificates are imported for a TLS-based environment.

For Oracle E-Business Suite Release 12.2

1. Download Oracle E-Business Suite AccessGate for your Oracle E-Business Suite release. For download and patch information, refer to My Oracle Support Knowledge Document 2202932.1, Using the Latest Oracle E-Business Suite AccessGate for Single Sign-On Integration with Oracle Access Manager.

2. Deploy Oracle E-Business Suite AccessGate by following the setup and configuration instructions described in one of the following My Oracle Support Knowledge Documents based on your Oracle Access Manager release:

   • For Oracle Access Manager 12c, see Document 2339348.1, Integrating Oracle E-Business Suite Release 12.2 with Oracle Access Manager 12c using Oracle E-Business Suite AccessGate.

     If you have already deployed an earlier version of Oracle E-Business Suite AccessGate, refer to Section 8.2 Oracle E-Business Suite AccessGate Upgrade, My Oracle Support Knowledge Document 2339348.1.

   • For Oracle Access Manager 11g, see Document 1576425.1, Integrating Oracle E-Business Suite Release 12.2 with Oracle Access Manager 11gR2 (11.1.2) using Oracle E-Business Suite AccessGate.

     If you have already deployed an earlier version of Oracle E-Business Suite AccessGate, refer to Section 8.2 Oracle E-Business Suite AccessGate Upgrade, My Oracle Support Knowledge Document 1576425.1.

3. After Oracle E-Business Suite AccessGate is successfully deployed, define a public policy to make the /accessgate/logout/sso service to be publicly invokable.

   Please note that the new resource /accessgate/logout/sso has been added to the public resources defined in the AutoConfig template ebs_oam_uri_conf.tmp, and will be automatically configured when you register Oracle E-Business Suite with Oracle Access Manager.

   If you have already registered Oracle E-Business Suite with Oracle Access Manager for single sign-on prior to setting up Oracle E-Business Suite Mobile Foundation Release 4.0 or later, then you need to re-register Oracle E-Business Suite and include an additional parameter -policyUpdate=yes. These actions add the newly-defined public resource /accessgate/logout/sso to your configuration.

   Follow the registration instructions as documented in Section 4.2 Register Oracle E-Business Suite with Oracle Access Manager, My Oracle Support Knowledge Document 1576425.1. Additionally, add a command line parameter -policyUpdate=yes as shown in the following example:

   txkrun.pl -script=SetOAMReg -registeroam=yes -policyUpdate=yes \  
   -oamHost=http://myoam.example.com:7001 \  
   -oamUserName=weblogic \  
   -ldapUrl=ldap://myoid.example.com:3060 \ 
   -oidUserName=cn=orcladmin \  
   -skipConfirm=yes \  
   -ldapSearchBase=cn=Users,dc=example,dc=com \  
   -ldapGroupSearchBase=cn=Groups,dc=example,dc=com 

4. Tasks for Enabling the feature on a TLS-based Oracle E-Business Suite environment

   Note: Oracle E-Business Suite mobile 10.x apps support TLS 1.2 only and TLS 1.2 with backward compatibility (recommended). For information on enabling TLS 1.2 only and TLS 1.2 with backward compatibility, see My Oracle Support Knowledge Document 1367293.1, Enabling TLS in Oracle E-Business Suite Release 12.2.

   If your Oracle E-Business Suite instance is TLS enabled and Oracle Access Manager (OAM) configured, perform the following tasks:

   1. Import the root-CA certificates from the OHS wallet into the truststore of the OAEA managed server where Oracle E-Business Suite AccessGate is deployed, if the root-CA certificates have not already been imported.

      Note: When the OAEA managed server is isolated from the oacore server, it is required to import the certificates into the truststore of the OAEA server.

      The default truststore or keystore for the managed server is at: <s_fmw_jdkto>/jre/lib/security/cacerts

      For information on importing the certificates into the truststore, see Section 3.9 Update the JDK Cacerts File in My Oracle Support Knowledge Document 2143101.1, Enabling SSL or TLS in Oracle E-Business Suite Release 12.2.

   2. If your Oracle Fusion Middleware version is earlier than 11.1.1.9, then you must enable JSSE TLS in the Oracle E-Business Suite context file. Use Oracle Applications Manager to update the Oracle E-Business Suite context file.

      Prerequisites: Review My Oracle Support Knowledge Document 1617461.1, Applying the Latest AD and TXK Release Update Packs to Oracle E-Business Suite Release 12.2, and follow the instructions to apply the required codelevel of AD and TXK for your system.

      1. Log in to Oracle E-Business Suite as a system administrator.

      2. Navigate to System Administration. Select Oracle Applications Manager, and then AutoConfig.

      3. Select the application tier context file, and choose Edit Parameters.

      4. Search for the s_enable_jsse variable by selecting OA_VAR in the search list of values and entering s_enable_jsse in the search text box. Choose the Go button.

      5. By default, the s_enable_jsse variable is set to false. Change this value to true to enable JSSE TLS. Refer to the description of the context variable for more information.

      6. Choose the Save button.

      7. Enter a reason for the update, such as "Enabling JSSE TLS". Then choose the OK button.

      8. Run AutoConfig and restart all the application tier services. For more information about AutoConfig, see: Technical Configuration, Oracle E-Business Suite Setup Guide.

Step 3: Testing the Setup for the Apps SSO Login Authentication Security

To successfully log in to an Oracle E-Business Suite mobile app configured with the Apps SSO Login security, you need to ensure successful HTTP(s) communication from the Oracle E-Business Suite AccessGate managed server to the Oracle E-Business Suite server.

1. Validate the communication by running the following WGET command from the managed server where Oracle E-Business Suite AccessGate is deployed:

   wget -d http(s)://<ebs_host>:<ebs_port>/OA_HTML/RF.jsp?function_id=mLogin

2. If this fails, verify the following tasks and ensure they are in place:

   1. The root-CA, intermediate, and server certificates from the Oracle HTTP Server (OHS) wallet and Oracle TLS CA certificates are imported into the truststore of the managed server where Oracle E-Business Suite AccessGate is deployed.

   2. Network port from the current managed server to the Oracle E-Business Suite web entry is NOT restricted.

   3. For an Oracle E-Business Suite environment configured in a DMZ configuration, if Oracle E-Business Suite AccessGate is deployed on your intranet server with firewalls and the Oracle E-Business Suite web entry point is a URL over the Internet, then make sure this Oracle E-Business Suite URL is NOT DIS_ALLOWED from the intranet server.

      Although this Oracle E-Business Suite web entry point URL can be your enterprise's own URL, this could still restrict access from your intranet server. If this network restriction policy cannot be exempted to ALLOW access from the intranet managed server where Oracle E-Business Suite AccessGate is deployed to the Oracle E-Business Suite web entry point over the Internet, then you can try the following option of configuring proxy host and port for the HTTP communication as a workaround.

      1. Restart with the following -D System settings on the managed server where Oracle E-Business Suite AccessGate is deployed.

      2. Use the -D settings for setting up proxy host and port through the System properties in JAVA_OPTIONS:

         • For the HTTP protocol communication:

           -Dhttp.proxyHost 
           -Dhttp.proxyPort 
           

         • For the HTTPS protocol communication:

           -Dhttps.protocols (TLSv1.1/SSL version) 
           -Dhttps.proxyHost 
           -Dhttps.proxyPort 

      For more information, refer to Oracle Networking Properties (https://docs.oracle.com/javase/7/docs/api/java/net/doc-files/net-properties.html), Oracle Java Documentation.

Step 4: Setting the Mobile App Connection to Use Apps SSO Login

After completing all the setup tasks on the server, you now need to configure the mobile client and set the mobile app connection to use Apps SSO Login authentication type.

See: Configuring Parameters for the Apps SSO Login Authentication Type.