SSO for Oracle HTTP Server and Apache: integration packages

An integration package installs the SSOGEN Web Agent on your web server and writes its configuration, so single sign-on for Oracle E-Business Suite, PeopleSoft, JD Edwards, Oracle HTTP Server (OHS) or plain Apache is one command instead of a manual edit. There is one package per product, and each carries the same version number as the Web Agent modules inside it (the 4.1 line). This guide covers what each package does, where to get it, the three ways it can connect, what you run, and how to undo it.

Good to know before you start

• The package is given to you by SSOGEN, as a single .zip file with a checksum file next to it (ssogen-<product>-<version>-<date>.zip and .zip.sha256). Ask your SSOGEN contact. It is not part of SSOGEN download.
• Nothing is enrolled. In SSOGEN mode the SSOGEN administrator gives you the application’s agent key (see Protect an on-premise app with the Web Agent). The package never asks for a token or a certificate authority file.
• Run it first on a non-production system. Every change is backed up first, and --check shows what would change without changing anything.
• The package runs on Linux, x86-64 only.

The packages

Package	For	Where it installs the module
ebs122	Oracle E-Business Suite 12.2	The EBS web tier (OHS), on both file systems of the EBS instance.
ebs121	Oracle E-Business Suite 12.1	The OHS of the external AccessGate server that EBS 12.1 signs in through.
ohs	Oracle HTTP Server 11g and 12c in front of any application	The OHS home.
apache	Apache 2.2 and 2.4 from your operating system	The Apache module directory.
peoplesoft	PeopleSoft web tier	The web server in front of PeopleSoft.
jde	JD Edwards EnterpriseOne web tier	The web server in front of JD Edwards.

Each package contains the module for Apache 2.2 and for Apache 2.4. It reads the Apache version from your web server (not from the operating system), picks the matching module, verifies its checksum, and copies it in by copy-then-rename so a running server never sees a half-written file. It does not restart the web server unless you ask (-restart, on the apache and ohs packages); the final messages tell you what to restart.

The Web Agent itself is described in Protect an on-premise app with the Web Agent.

Three ways to connect

Every package takes -mode=:

Mode	What it does	What you need
ssogen	The application signs in through your SSOGEN, and you manage the policy in the Admin Console.	The SSOGEN address (-platform_url), the application’s client ID (-client_id) and its agent key (-agent_key_file). No license key.
saml (the default)	The web server is a SAML service provider for another identity provider such as Microsoft Entra ID, Okta or Keycloak, without SSOGEN in between.	A license key from SSOGEN (-ssogen_license) and the identity provider’s metadata.
oidc	The web server is an OpenID Connect client of another identity provider.	A license key from SSOGEN, the identity provider’s discovery address, and the client ID and secret it gave you.

An existing configuration of another mode is never overwritten: give the new one its own name with -sso_config_name.

Before you run: register the application (ssogen mode)

1. In the Admin Console register the application as a Web Agent application, as in Part A of the Web Agent guide, and note its Client ID.
2. Open the application’s Integration tab, select Generate agent key, and copy the key once. Write it on the first line of a file on the web server that only the account running the package can read (chmod 600). SSOGEN keeps only a hash of the key and cannot show it again; Regenerate agent key replaces it.
3. For SAML or OpenID Connect mode, register the application in your identity provider instead. The package prints the values to enter there (the entity ID and the assertion consumer service address for SAML; the redirect address for OpenID Connect).

Run the package

Unpack the zip. It holds one file, ssogen. Check the package first:

sha256sum -c ssogen-ebs122-4.1.6-<date>.zip.sha256
unzip ssogen-ebs122-4.1.6-<date>.zip
./ssogen --selftest
./ssogen info > ssogen-info.txt

--selftest checks the tools it needs, free space and that the package is intact, and names what is wrong if not. info is read-only: it writes a summary of the web server it found, which you can send to SSOGEN support.

Then run the function for your product:

Product	Command (ssogen mode)
EBS 12.2, as the EBS application owner with the run environment loaded	./ssogen reg --check -mode=ssogen -platform_url=https://sso.acme.example -client_id=<client ID> -agent_key_file=<file> and then the same without --check
EBS 12.1	eagsetup, createeaguser and reg on the EBS server and deployag and ohsreg on the AccessGate server, in that order; run ./ssogen -h for the page of each
Apache, OHS, PeopleSoft, JD Edwards	./ssogen reg --check -mode=ssogen -app_url=https://app.acme.example -platform_url=https://sso.acme.example -client_id=<client ID> -agent_key_file=<file> and then the same without --check

For EBS the package asks for the APPS password (it does not echo it; -appspass= also works but is visible in the process list while the script runs). The package then:

1. checks the environment and prints a checklist;
2. installs the module and writes the configuration (mode 600);
3. for EBS, sets the E-Business Suite profile options for external single sign-on;
4. prints a summary, the backups it made, the log file, and numbered next steps.

If a required value is missing (for example the agent key), the package writes the configuration, says ACTION REQUIRED, and leaves your web server, the module and the EBS profile options alone until you give it and run it again.

When it finishes, restart the web server as the next steps say (for EBS: all EBS services), then test with a private browser window.

The agent key

The package accepts the key as -agent_key_file=FILE (preferred), -agent_key=KEY (it ends up in your shell history and in the process list, and a warning says so), or by asking you on a terminal without echoing it. It checks the key’s form before it changes anything, stores it in a file readable only by its owner next to the configuration, and refers to that file from the configuration. The key is never printed or logged. After Regenerate agent key in the console, run the package again with the new key; it replaces the stored one.

Application type

The packages for EBS, PeopleSoft, JD Edwards and OHS configure the Oracle application type, where the user name arrives in capitals. The apache package configures the generic type for a new configuration, where the user name arrives unchanged. On the apache package, -app_type=Oracle or -app_type=generic chooses the type. When you run apache again on a configuration that already exists, it keeps that configuration’s type (an older configuration without a type is kept as Oracle); only -app_type changes it.

SAML and OpenID Connect modes

Identity provider metadata (SAML). The package does not ask for it. Save your identity provider’s metadata file as <name>-idp.xml in the SSOGEN folder before you run the package, and it is used. Otherwise the configuration carries one comment telling you to save the file and add the line SSOGENSamlIdpMetadataFile, and the package ends with ACTION REQUIRED. Or use the metadata address instead of a file with SSOGENSamlIdpMetadataURL <address> (for Microsoft Entra ID, the application’s App Federation Metadata URL). The module does not start with a metadata file that is missing.

OpenID Connect. Add the identity provider’s discovery address (SSOGENOidcProviderMetadataURL, for Entra ID https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration) and the client ID. The client secret is given with -oidc_secret= or the SSOGEN_OIDC_SECRET variable, or asked on a terminal, and is written to the configuration file, which only its owner can read. EBS user names are usually network IDs, not email addresses: if the provider’s preferred_username is an email address, have it send the short name in another claim and name that claim with SSOGENOidcUserClaim.

Signing out

In SAML and OpenID Connect mode the package sends people to the Microsoft Entra ID sign-out page after sign-out by default, unless the identity provider metadata file it finds names a provider other than Entra ID (SSOGEN itself, for example). In that case the module shows its own signed-out page. -custom_logout_url=https://… sets another address in either case.

By default signing out of the application ends only the application’s own session (SSOGENLogoutScope local). On shared computers (a kiosk, a shift workstation) add SSOGENLogoutScope sso to the configuration, so that signing out also ends the SSOGEN or identity-provider session. Otherwise the next person at that browser who opens the application is signed in as the first person.

Back out

To	Run
See what would change	add --check (or -n) to any function
Remove the integration	./ssogen dereg (EBS also has dmzdereg; EBS 12.1 has ohsdereg). It removes the block the package wrote and restores the product’s settings; the module and the configuration file stay.
Restore a file	every file the package edits is first copied to <file>.preSSOGEN.<timestamp>. The newest ten backups are kept. Copy the one you want back.
Replace the configuration	run reg again with the new values; an unchanged run changes nothing

For EBS, cleanup clears the single-sign-on user links stored on the EBS users and first saves the user IDs it clears to a file.

If it does not work

Symptom	What to do
--selftest fails	It names the problem: a missing tool (the package needs openssl), a damaged download (compare the checksum and download again), no usable temporary folder, not enough free space (three times the size of the package), or a CPU other than x86-64.
“Apache line not found” (exit 8)	The package could not read your web server’s version. Give it with -apache=2.2 or -apache=2.4.
“ACTION REQUIRED” at the end	A value is missing. Give it as the message says and run the package again.
The web server will not start after a SAML or OpenID Connect install	The metadata file the configuration names is missing, or the provider lines were not added. Add them, or remove the line.
Signing in fails with a 403 and the log mentions the agent’s credential	The agent key is missing or old. Paste the current one from the Integration tab. See the Web Agent guide.

Related guides

• Protect an on-premise app with the Web Agent
• Protect a Java application with the Java agent
• Choose how to connect an application