Single Sign-On (SSO) Connector for Oracle E-Business Suite (EBS)
The EBS Connector simplifies SSO in cloud, on-premise, or hybrid.
XtremeCloud SSO is a separate highly-available (HA) service that you manage in a Kubernetes cluster. Applications are configured to point to and be secured by this service. XtremeCloud SSO uses open protocol standards like OpenID Connect (OIDC) or SAML 2.0 to secure your applications. Browser applications redirect a user’s browser from the application to the XtremeCloud SSO authentication service where they enter their credentials. This is important because users are completely isolated from applications and applications never see a user’s credentials. Applications instead are given an identity token or assertion that is cryptographically signed. These tokens can have identity information like username, address, email, and other profile data. They can also hold permission data so that applications can make authorization decisions. These tokens can also be used to make secure invocations on REST-based services.
EBS Connector for Simplified SSO
The EBS Connector application (available with XtremeCloud SSO since the February 2021 Release 1.1), providing a full review of its features, configuration and deployment options ranging from single server to high available configuration based on a cloud-native Kubernetes cluster deployment.
###Integration with Oracle E-Business Suite
Traditionally Oracle Access Manager (OAM) has been the product of choice for customers looking for an SSO solution with EBS and although OAM is extremely flexible and powerful in features quite often requires additional resources in terms of servers and skilled professionals for its implementation, some times this only requirement can be a challenge for customers looking for a simple solution to their basic SSO needs.
The EBS Connector in the other hand is a lightweight Java application that acts as an extension to XtremeCloud SSO, requires minimal configuration and can be easily deployed to a Kubernetes cluster either on-premise or in the cloud providing SSO capabilities to EBS. Figure 1 depicts a typical deployment in which the EBS Connector provides SSO capabilities to EBS. Although two main flows are highlighted (orange and light-blue), later we will learn that other flows can be configured to allow things like redirection of the EBS login page or deep linking, a term referred to the use of URL links that take users to access specific pages or functions within the EBS application.
Figure 1. SSO with Oracle E-Business Suite using EBS Connector
Some examples of deep linking can be seen in EBS notifications containing links for accessing report pages or when working with Oracle Web Applications Desktop Integrator (Web ADI) documents to perform data entry operations with EBS.
Figure 2 depicts an extended deployment in which third-party SAML 2.0 identity providers like Okta, OneLogin, Microsoft Azure or Microsoft ADFS can be used to implement SSO with EBS by relying on XtremeCloud SSO and the EBS Connector application. Being XtremeCloud SSO SAML 2.0 compliant, it can be configured as service provider (SP) to allow an external identity provider authenticate users and access EBS without being prompted for another set of credentials.
Figure 2. SSO with EBS using EBS Connector and Third-Party IDPs
## EBS Connector
The EBS Connector is a cloud-native Java servlet application that provides Single Sign-On to EBS applications using XtremeCloud SSO as the primary identity provider for authentication while handling EBS user sessions. Internally, the EBS Connector communicates with XtremeCloud SSO and EBS using REST APIs, Java libraries and JDBC. Figure 3 depicts the EBS Connector architecture and communication interfaces.
Figure 3. EBS Connector Architecture
The EBS Connector offers the following features when implementing SSO with EBS applications:
- Non-intrusive solution, requiring minimum configuration changes in the EBS application. After SSO is enabled, administrators can continue accessing EBS directly if needed for recovery purposes or fail over.
- Support EBS mobile applications build on Oracle Mobile Application Framework like Approvals and Expenses.
- Support Single Logout (SLO) with XtremeCloud SSO and EBS application.
- Support multiple access modes for SSO with EBS application:
- Access using EBS Connector’s URL
- Access using the EBS Connector home page
- Access via redirect using EBS default login page
- Access via EBS deep links (e.g., links on email notifications)
- Support integration of EBS with Oracle Web ADI documents.
- Enhanced security on EBS applications by leveraging XtremeCloud SSO strong authentication and adaptive security capabilities, including multi-factor authentication, risk based adaptive authentication and access policies.
- In terms of deployment topologies, the EBS Connector application can be installed in a single server or in a high available configuration, supporting multiple EBS application instances, e.g. Development, UAT, etc.
Installing and Configuring EBS Connector
The following requirements must be considered when deploying the EBS Connector for SSO with EBS applications: The EBS Connector is deployed to a Kubernetes cluster with Java Development kit (JDK) version 11-based pod. The EBS Connector supports EBS Release 11i and Release 12 applications. The Fully Qualified Domain Name (FQDN) of the EBS Connector and EBS application must belong to the same domain name in order for the SSO to work.
For production deployments all communication must be secure using SSL and clock synchronization must be enable in both the EBS Connector and EBS application. Deployment of the EBS Connector application can be group in three configuration tasks: EBS application, XtremeCloud SSO and EBS Connector. Notes: please be aware the instructions and screenshots associated with the EBS application in this document are based in Release 12.2.10, if you have a previous release, some configuration options or screens maybe be missing or different, please consult My Oracle Support (MOS) for further details.
The following instructions assume the FQDN for the EBS Connector and EBS application are ebsConnector.example.com and ebs.example.com respectively.
EBS Configuration Tasks
Create an EBS application user that will be used for communication with the EBS database. To do so, login to the EBS application with a user with administrator privileges. Open the EBS Navigator and select User Management -> Users. In the User Management page, click on Users tab and select User Account from the Register drop-down menu, then click the Go button. Enter the details to define a new user, e.g.:
For User Name, enter
For Active From, leave the default current date For Password and Confirm Password, enter a password For Password Expiration, leave the default None Click the Submit button to create the new user
Figure 4. Creating EBS application user
Step 2: After the user is created a confirmation message is displayed, click in the Assign Roles button to display the Update User page, click in the Assign Roles button again. In the Search and Select window, search by Code and enter UMX|APPS_SCHEMA_CONNECT and click Go. In the Results section, select Apps Schema Connect Role and click on Select button. Back in the Update User page, enter a reason in the Justification text box and click the Save button. Notes: a) ignore the warning message regarding the Workflow Background Engine, b) login to EBS with the new user in order to reset the password as first time login.
Figure 5. Assigning Apps Schema Connect Role
Step 3: Proceed to configure the EBS application for SSO. To do so, login to the EBS application with a user with administrator privileges. Open the EBS Navigator and select Functional Administrator, in the Applications Administration page, click in Core Services tab and then click in the Profiles link. Search the following profiles by Code and update their values as follow, e.g.:
- For profile APPS_AUTH_AGENT update its value with the EBS Connector application URL, e.g.: https://ebsConnector.example.com:7002/ebs
- For profile APPS_SSO update its value to SSWA w/SSO
- For profile ICX_SESSION_COOKIE_DOMAIN update its value to DOMAIN
- For profile FND_SEC_ALLOW_UNRESTRICTED_REDIRECT update its value to Yes
Notes: setting profile FND_SEC_ALLOW_UNRESTRICTED_REDIRECT to Yes allows unrestricted redirects, however for a more secure approach you can set this profile to No and update the allowed redirects whitelist (at the host, domain or profile level) on $FND_TOP/secure/allowed_redirects.conf.
Figure 6. Updating EBS Profiles
In all cases, do the updates at the Site level, assuming your EBS application has one Web Entry Point, the default for most deployments. If your EBS application has multiple Web Entry Point consult with your EBS administrator to set the Hirarchy Type accordingly. Re-start your EBS application to make the changes effective.
Step 4: Register the EBS Connector FQDN with the EBS application. To do so, login to the EBS application server with a user that owns the EBS installation. Proceed to create a working folder, e.g. /opt/ebssdk and run the following commands to source the EBS environment and register the EBS Connector, e.g.:
The previous commands will generate a DBC file with its name set to the standard DBC file name plus the EBS Connector FQDN in the current path, e.g. EBSDB_EBSConnector.EXAMPLE.COM.dbc. Edit this file with a text editor and write down the value of parameter APPL_SERVER_ID, this value will be later use to populate the app.serverid property in the EBS Connector configuration file. Notes: in a production environment is recommendable to invoke the utiliy oracle.apps.fnd.security.AdminDesktop along with the IP_ADDRESS argument and set profiles FND_SERVER_SEC and FND_SERVER_IP_SEC to Desktop Only. Also set profile FND_SERVER_DESKTOP_USE at the user level for the user with the Apps Schema Connect Role, this will restrict the use of the DBC file to a machine with that IP address and user.
Step 5: If using EBS mobile applications based on Oracle Mobile Application Framework like EBS Approvals you must perform some additional configuration in EBS, otherwise skip this step. Notes: a) this document assumes you have already installed the required EBS patches and registered mobile applications in your EBS environment. Please consult the EBS documentation for further details, b) if using mobile application Oracle Fusion Expenses you can skip this configuration. Login to the EBS application with a user with administrator privileges. Open the EBS Navigator and select Mobile Applications Manager -> Applications. In the Search Mobile Applications page, search by Application Name, e.g. EBS Approvals. From the results list, click in the Configure icon for the mobile application. In the configuration page under Mobile Application section, update the status property, e.g. :
- For Status, make sure Enabled is selected
- Under Configuration Categories section, select Sub Category App SSO Login and expand Connection Settings. Update the configuration parameters accordingly, e.g.:
- For SSO Login URL enter %APPS_AUTH_AGENT%/login/sso in the Override Value colum
- For SSO Logout URL enter %APPS_AUTH_AGENT%/ssologout in the Override Value colum
- For SSO Login Success URL enter %APPS_AUTH_AGENT%/login/sso in the Override Value colum
- For EBS Session Service enter %APPS_AUTH_AGENT%/login/apps in the Override Value column Click Apply to save the changes
Re-start your EBS application to make the changes effective. Notes: a) connection settings are synced with mobile applications and you may need to re-open the mobile application a couple of times before the new changes become effective. b) a message “New updates were downloaded from the server. You must restart the app.” is displayed when opening a mobile application with pending updates.
Figure 7. Connection Settings for EBS Approvals
XtremeCloud SSO Configuration Tasks
Step 1: Create an XtremeCloud SSO application so the EBS Connector can communicate with XtremeCloud SSO. To do so, login to XtremeCloud SSO with a user with administrator privileges. From the XtremeCloud SSO Admin Console, click in the drawer icon to open the side bar menu and select Applications, click the Add button and select Confidential Application, enter the details for the new application, e.g.:
Under Details page:
- For Name enter EBS Connector
- In Application URL enter the URL for the EBS Connector application, e.g. https://ebsConnector.example.com:7002/ebs
- Check Display in My Apps
- Under Client page: -Select Configure this application as client now
- In Allowed Grant Types check Client Credentials and Authorization Code
- If deploying in a test or development environment, you can allow non-secure connection by checking Allow non-HTTPS URLs
- For Redirect URL enter https://ebsConnector.example.com:7002/ebs/response
- For Logout URL enter https://ebsConnector.example.com:7002/ebs/logout
- For Post Logout Redirect URL enter https://ebsConnector.example.com:7002/ebs
- In Grant the client access to Identity Cloud Service Admin APIs, click the Add button and add the following roles: Me and Authenticator Client
- Left the remaining pages Resources and Web Tier Policy with their default values, in the Authorization page click the Finish button to save the changes. Write down the Client ID and Client Secret values from the Application Added window, then click on the Close button. Proceed to enable the application by clicking in the Activate button, confirm by clicking on Activate Application.
Figure 8. XtremeCloud SSO application for EBS Connector
Step 2: For the SSO to work, users must exist in XtremeCloud SSO and the EBS application. Also, these users must share a common identifier like user name or email address that is specified during the EBS Connector configuration. For example the following user was created with the same user name in both applications: XtremeCloud SSO
User Name EBS User Name DBAKER DBAKER
Step 3: If you would like to access the EBS Connector application via XtremeCloud SSO’s My Apps portal page, make sure to add the XtremeCloud SSO users to the applications’s Users list. To do so, while in the XtremeCloud SSO Admin Console, edit the EBS Connector application, click in the Users tab and add the desired users. A similar step can be follow to add group of users in which case the group names will be added to the application’s Groups tab.
EBS Connector Configuration Tasks
Step 1: The EBS Connector application is deployed in a Kubernetes cluster and scales on demand.
Notes: XtremeCloud SSO SSL certificates are signed by DigiCert and since recent versions of Oracle JDK 8 certificate store includes the root certificate for DigiCert, you don’t need to import the XtremeCloud SSO certificates.
Step 2: Download the EBS Connector application. To do so, login to XtremeCloud SSO with a user with administrator privileges. From the XtremeCloud SSO Admin Console, click in the drawer icon to open the side bar menu and select Settings -> Downloads, in the Downloads page, select Identity Cloud Service E-Business Suite Connector and click the Download icon.
Once the download is complete, proceed to create a working folder in the WebLogic Server, e.g. /oracle/ebssdk, extract the files located in /build/libs inside zip file ebsassert-
Figure 9. Downloading EBS Connector
Step 3: Create an Oracle wallet to store the XtremeCloud SSO application credentials. To do so, login as the user who owns the WebLogic Server installation and run the following commands inside the working folder providing the required input, e.g.: The previous commands will create a wallet file named cwallet.sso in the specified wallet path.
Step 4: Add fndext-
Step 5: Optionally if you are deploying in a development environment or using wildcard SSL certificates, you may want to disable hostname verification, to do so login to the WebLogic Admin Console with a user with administrator privileges. From the left panel click the Lock & Edit button, then select Environment -> Servers, from the list click in the server name where the EBS Connector application is being deployed to open the Settings page, then select the SSL tab, scroll down and expand the Advanced section and proceed to update the Hostname Verification property to None. Click Save to apply the changes, then click on Activate Changes button in the left panel to confirm the changes. Proceed to re-start the WebLogic Server.
Step 6: Define a data source, to do so login to the WebLogic Console with a user with administrator privileges. From the left panel click the Lock & Edit button, then select Services -> Data Sources, under the Configuration tab click in the New button and select Generic Data Source, proceed to the enter the values to define a new data source, e.g.:
Under JDBC Data Source Properties:
- For Name and JNDI Name enter visionDS
- For Database Type select Oracle, click Next
- For Database Driver select *Oracle’s Driver (Thin) for Instance connections; Versions:Any, click Next
Notes: the value of Name and JNDI Name properties must match the value of the ebs.ds.name property in the EBS Connector configuration file to be created in the next steps.
Under Transaction Options:
- Uncheck Supports Global Transactions, click Next
Under Connection Properties:
- For Database Name enter the EBS database name, e.g. EBSDB
- For Host Name enter the EBS database hostname, e.g. ebs.example.com
- For Port enter the EBS database port number, e.g. 1521
- For Database User Name enter the EBS application user name, e.g.
- For Password and Confirm Password enter a password, click Next
Under Test Database Connection:
- For Database Class Name enter oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource
- For Properties add the following value in a new line: dbcFile=/oracle/ebssdk/EBSDB_EBSConnector.EXAMPLE.COM.dbc
Notes: Do not override the existing content in Properties and make sure the above value is added in a new line.
Leave the other properties with their default values and click the Test Configuration button to test the connection. If sucessful click Next
Under Select Targets, select the target server name, then click Finish and Activate Changes button to save the changes.
Figure 10. Testing Data Source Connection
Step 7: Create the EBS Connector configuration file. To do so, use a text editor to create a configuration file named bridge.properties in the working folder. The following content is a sample configuration: An explanation about the parameters follows: app.url is the URL for the EBS Connector application deployed in WebLogic. Its value must match XtremeCloud SSO’s application Application URL value. app.serverid is the APPL_SERVER_ID value found in the DBC file generated during registration of the EBS Connector FQDN with the EBS application. ebs.url.homepage is the URL address for the EBS application home page. ebs.ds.name is the name of the WebLogic data source created for communication between EBS Connector and the EBS database. ebs.user.identifier specifies how XtremeCloud SSO and EBS application users will match up, this is mandatory in order for the SSO to work. Allowed values are username which indicates the XtremeCloud SSO user name match the EBS application user name or email when the XtremeCloud SSO user email address match the EBS application user email address. Notes: if you specify email as the identifier then make sure there is only one email address set for the EBS user in the FND_USER table. XtremeCloud SSO.iss.url is the XtremeCloud SSO’s token issuer URL. XtremeCloud SSO.aud.url is the XtremeCloud SSO’ audience URL. wallet.path is the Oracle wallet full path, including file name. whitelist.urls is a multi-value parameter separated by commas allowing to specify a white list of EBS URLs commonly used to support Oracle Web ADI and deep links used in Workflows, Reports and Email notifications. The sample value includes commonly used URLs in EBS. In addition, the following optional parameters can be specified: post.logout.url used to specify a custom logout URL. If set its value must match XtremeCloud SSO’s application Post Logout Redirect URL. ebs.renew.session controls how the EBS Connector manages the EBS Forms time out. Setting this parameter to true results in refreshing the EBS Forms session after having reach the configured limit (ICX:Session Timeout). If the parameter is set to false, after reaching the configured limit, the EBS Forms session is invalidated closing all active Forms, however the EBS session in the browser will still active, allowing the user to reopen a new Forms session. Copy the configuration file bridge.properties into folder WEB-INF located inside war file ebs.war overriding the existing file.
Step 8: Deploy the EBS Connector application, to do so login to the WebLogic Console with a user with administrator privileges. From the left panel click the Lock & Edit button, then select Deployments, in the Deployments page click on Install button and proceed to enter the required input to deploy the application, e.g.:
Under Locate deployment
For Path, enter /oracle/ebssdk/ebs.war, click Next
Under Installation type
Select Install this deployment as an application, click Next
Under General section
For Name enter ebs and leave other parameters with their default values, click Next
Notes: a) the value of the Name parameter represents the context root for the application in WebLogic, therefore if you use a different name or are deploying two or more EBS Connector applications in the same WebLogic Server you must specify different names, e.g. ebsdev and ebsuat, b) you must also update the
Figure 11. Deployed EBS Connector Application
Testing SSO with EBS Application
As indicated previously, users with the same identifier (user name or email address) must exist in XtremeCloud SSO and the EBS application for the SSO to work. For the purpose of this demonstration we have created a couple of sample users with the same user name in both applications, e.g.: XtremeCloud SSO
User Name EBS User Name DBAKER DBAKER LJONES LJONES
Test 01: SSO using EBS Connector URL Open a browser and enter the URL for the EBS Connector application, e.g.: https://ebsConnector.example.com:7002/ebs. You are redirected to the XtremeCloud SSO Sign In page, proceed to enter a valid XtremeCloud SSO user name and password. Upon successful authentication you are redirected to the EBS application’s home page. Logout from the EBS application. Both user sessions for EBS and XtremeCloud SSO are terminated and you are redirected to the XtremeCloud SSO Sign In page.
Figures 12 and 13. SSO to EBS Application using EBS Connector URL
Test 02: SSO using EBS Connector Application in XtremeCloud SSO
Open a browser and enter the URL for the XtremeCloud SSO application, e.g.: https://
Figures 14 and 15. SSO to EBS Application using My Apps Portal Page
Test 03: SSO using Deep Links in EBS
Open a browser and enter the URL for the EBS application, e.g.: http://apps.example.com:8000/OA_HTML/AppsLogin. You are redirected to the XtremeCloud SSO Sign In page, proceed to enter a valid XtremeCloud SSO user name and password. Make sure the corresponding user in EBS has the Employee Self-Service responsibility assigned. From the EBS Navigator expand the Employee Self-Service menu option, right-click in Employee W-2 and make sure to copy the link address to a notepad or clipboard in your desktop. Proceed to logout from EBS (this will also terminate the XtremeCloud SSO session). Open a new tab in your browser and paste or copy the link address (deep link) from the previous step. You are redirected to the XtremeCloud SSO Sign In page, proceed to enter a valid XtremeCloud SSO user name and password. Make sure the corresponding user in EBS has the Employee Self-Service responsibility assigned. Upon sucessful authentication you are redirected to the EBS application’s Employee W-2 page.
Figures 16 and 17. SSO Using Deep Links in EBS
Test 04: SSO using Web ADI Documents with EBS
Open a Web ADI document, e.g. a Microsoft Excel spreadsheet for filling in Journals in General Ledger. Proceed to do data entry, e.g. double-click in one of the cells under the Category column. At this point a pop-up window displays the XtremeCloud SSO Sign In page, proceed to enter a valid XtremeCloud SSO user name and password. In the same pop-up window and upon sucessful authentication, a list of valid categories are listed, choose one and click the Select button. Web ADI auto-populates the spreadsheet cell with the selected category. Proceed with other data entry as needed. Save your changes and close the spreadsheet. The EBS and XtremeCloud SSO user sessions are terminated.
Figures 18 and 19. SSO Using Web ADI Documents with EBS
Test 05: SSO using EBS Application URL Open a browser and enter the URL for the EBS application, e.g.: http://apps.example.com:8000/OA_HTML/AppsLogin. You are redirected to the XtremeCloud SSO Sign In page, proceed to enter a valid XtremeCloud SSO user name and password. Upon sucessful authentication you are redirected to the EBS application’s home page.
Test 06: SSO using Mobile Applications Assuming you have configured your mobile application for SSO, e.g. Fusion Expenses, proceed to open the mobile application in you mobile device. You are redirected to the XtremeCloud SSO Sign In page, proceed to enter a valid XtremeCloud SSO user name and password. Upon successful authentication you are redirected to the mobile application’s home page.
Figures 20, 21 and 22. SSO with Mobile Fusion Expenses
###Deploying EBS Connector in High Availability Mode
This section outlines some considerations in the overall configuration when deploying the EBS Connector in high availability (HA) mode. The assumption is that a load balancer (LB) is fronting the WebLogic cluster in which the EBS Connector application has been deployed.
When updating profile APPS_AUTH_AGENT, use the LB URL fronting the EBS Connector cluster instead of the EBS Connector application server URL. When registering the EBS Connector with the EBS application, use the LB FQDN instead of the EBS Connector FQDN.
XtremeCloud SSO Considerations
When defining the XtremeCloud SSO application for the EBS Connector in XtremeCloud SSO, use the LB URL fronting the EBS Connector cluster instead of the EBS Connector application server URL.
EBS Connector Considerations
When defining the app.url paraneter in the bridge.properties file use the LB URL fronting the EBS Connector cluster. When defining the WebLogic data source, target all member servers of the EBS Connector cluster. Additionally, if supported by the LB configure session persistance using cookies with JSESSIONID as the session identifier (Session ID).
Integrating EBS Connector with Third-Party IdPs
This section outlines some aspects in the overall configuration to be considered when deploying the EBS Connector with third-party identity providers and XtremeCloud SSO in a SAML 2.0 federation.
No changes are require or different from the standard configuration with XtremeCloud SSO. In this case the EBS application is unaware of the integration with a third-party identity provider.
XtremeCloud SSO Considerations
XtremeCloud SSO participates in an Open Identity Connect (OIDC) federation playing the role of service provider. The standard XtremeCloud SSO documentation applies for configuring a federation with external identity providers.
Third-Party Identity Provider Considerations The standard third-party documentation for configuring a SAML 2.0 federation applies with the addition of specifying the RelayState parameter pointing to the EBS Connector application URL to redirect users after they have been authenticated. Deploying EBS Connector behind a Reverse Proxy This section outlines some aspects in the overall configuration to be considered when deploying the EBS Connector behind a reverse proxy. This deployment approach is common when exposing the EBS application to the public internet. Reverse Proxy Considerations The EBS Connector and Reverse Proxy should reside in the DMZ. The Reverse Proxy, EBS Connector and EBS application should belong to the same domain. Consider first deploying the Reverse Proxy with EBS and after thoroughly testing proceed with the integration of the EBS Connector and XtremeCloud SSO. XtremeCloud SSO Considerations When defining the XtremeCloud SSO application for the EBS Connector in XtremeCloud SSO, use the Reverse Proxy URL fronting the EBS Connector instead of the EBS Connector application server URL. EBS Connector Considerations When defining the app.url parameter in the bridge.properties file use the Reverse Proxy URL fronting the EBS Connector application.
Eupraxia Labs is constantly looking for better ways to improve customer experience while offering new tools and solutions to optimize the customer journey to the cloud. The EBS Connector represents a step further in that direction.