Configure Oracle SSM and Kerberos settings

Configure Oracle SSM and Kerberos settings.

8 minute read

Configure Oracle Security Service Module settings (10g)

An Oracle Security Service Module (SSM) integrates a secured application (in this case, the API Gateway) with an Oracle Entitlements Server (OES) 10g so that security administration (for example, roles, resources, and policies) is delegated to the Oracle Entitlements Server 10g. An SSM must be installed on the machine hosting the application to be secured by the Oracle Entitlements Server 10g. The SSM runs in-process with the secured application, which improves performance and on-the-wire security.

In Policy Studio, select the Environment Configuration > Server Settings node in the tree, and select Security> Security Service Module in the right pane. The Security Service Module settings enable you to configure the API Gateway to act as a Java SSM. For more details on Oracle Entitlements Server 10g and SSMs, see the Oracle Entitlements Server website.


Before configuring the settings on the Security Service Module tab, you must perform the following prerequisite tasks.

Test the SSM installation

Because the API Gateway is running a Java SSM internally, it is recommended that the example Java SSM client that ships with the OES installation is set up and configured. This example can be found in the following directory:


Follow the instructions in the README file in this directory to test the installation. When the testing of the JavaAPIExample is complete, all the configuration files for an SSM instance are located in the /ales32-ssm/java-ssm/SSM-Name directory, where SSM-Name is the name of the SSM setup when testing the example.

Configure the API Gateway classpath

The API Gateway classpath must be updated to include the JARs and configuration files for the SSM instance. The jvm.xml file must be updated so that various environment variables and the SSM-Name are updated to reflect the installation of the Java SSM. At minimum, the following must be updated in jvm.xml:

<Environment name="BEA_HOME" value="/opt/apps/bea" >
<Environment name="INSTANCE_NAME" value="SSM-Name" >

For example, to modify the classpath, place the following jvm.xml in the conf directory of the API Gateway installation:

<!--Additional JVM settings to run with Oracle Entitlements Server BEA_HOME must be set to the location 
    where the SSM is installed -->
    <!-- Environment variables -->
    <!-- change these to match location where SSM has been installed and configured -->
    <Environment name="BEA_HOME" value="/opt/apps/bea" />
    <Environment name="ALES_SHARED_HOME" value="$BEA_HOME/ales32-shared" />
    <!-- Name of the SSM running in the API Gateway, replace the "SSM-Name" with the name of the SSM for 
    the API Gateway -->
    <Environment name="INSTANCE_NAME" value="SSM-Name" />
    <Environment name="INSTANCE_HOME" value="$BEA_HOME/ales32-ssm/java-ssm/instance/
    <Environment name="PDP_PROXY" value="$INSTANCE_HOME/pdpproxy" />
    <!-- Location of the Java SSM libraries -->
    <!-- <ClassDir name="$BEA_HOME" /> -->
    <ClassDir name="$BEA_HOME/ales32-ssm/java-ssm/lib" />
    <ClassDir name="$BEA_HOME/ales32-ssm/java-ssm/lib/providers/ales" />
    <!-- Add location of the SSM configuration to classpath -->
    <ClassPath name="$INSTANCE_HOME/config/" />
    <!-- Additional JVM parameters based on the %JAVA-OPTIONS% of set-env script in SSM instance running 
    in API Gateway $BEA_HOME/ales32-ssm/java-ssm/instance/ssm-name/config -->
    <VMArg name="-Dwles.scm.port=7005" />
    <VMArg name="-Dwles.arme.port=8000" />
    <VMArg name="-Dwles.config.signer=Oracle Entitlements" />
    <VMArg name="-Dlog4j.configuration=file:$INSTANCE_HOME/config/" />
    <VMArg name="-Dlog4j.ignoreTCL=true" />
    <VMArg name="-Dwles.ssl.passwordFile=$ALES_SHARED_HOME/keys/password.xml" />
    <VMArg name="-Dwles.ssl.passwordKeyFile=$ALES_SHARED_HOME/keys/password.key" />
    <VMArg name="-Dwles.ssl.identityKeyStore=$ALES_SHARED_HOME/keys/identity.jceks" />
    <VMArg name="-Dwles.ssl.identityKeyAlias=wles-ssm" />
    <VMArg name="-Dwles.ssl.identityKeyPasswordAlias=wles-ssm" />
    <VMArg name="-Dwles.ssl.trustedCAKeyStore=$ALES_SHARED_HOME/keys/trust.jks" />
    <VMArg name="-Dwles.ssl.trustedPeerKeyStore=$ALES_SHARED_HOME/keys/peer.jks" />
    <VMArg name="$INSTANCE_HOME/work/jar_temp" />
    <VMArg name="-Darme.configuration=$INSTANCE_HOME/config/" />
    <VMArg name="-Dales.blm.home=$INSTANCE_HOME" />
    <VMArg name="-Dkodo.Log=log4j" />
    <VMArg name="-Dwles.scm.useSSL=true" />
    <VMArg name="-Dwles.providers.dir=$BEA_HOME/ales32-ssm/java-ssm/lib/providers" />
    <VMArg name="$PDP_PROXY/" />

Centralize all trace output

Oracle’s Java SSM uses log4j to output any diagnostics. You can also add these messages to the API Gateway trace output by adding the log4j that ships with the API Gateway to the following file:


Then the log4j.rootCategory=WARN, A1, ASIlogFile line includes a new appender called VordelTrace as follows:

log4j.rootCategory=WARN, A1, ASIlogFile, VordelTrace

Add the configuration for this new appender by adding the following line to the file:


You can now start the API Gateway so that it runs with the Java SSM classpath and the centralized trace output.

Further information

For more details on configuring and testing SSMs, see the Oracle SSM Installation and Configuration Guide.


On the Security Service Module settings window, configure the following fields on the Settings tab:

Enable Oracle Security Service Module: Select whether to enable the API Gateway instance to act as an SSM. This setting is disabled by default.

Application Configuration Name: Enter the Application Configuration name for the SSM instance. This is the name of your runtime application used by OES (for example, for monitoring purposes).

Configuration Name: Enter the OES Configuration name for the SSM instance to be stored in the OES Configuration Repository. Configuration names share the same name as their Policy Domain names.

Application Configuration Properties: Click Add to specify optional configuration properties as name-value pairs. Enter a Name and Value in the Properties dialog. Repeat to specify multiple properties.

Policy Domain Name: Enter the OES Policy Domain name for the SSM instance. Policy Domains contain policy definitions (target resource, permission set, and policy). Policy Domain names share the same name as their Configuration names.

Name authority definition settings

Configure the following field on the Name Authority Definition tab:

Name Authority Definition File: Click the Browse button at the bottom right to configure the Name Authority Definition file for the SSM. This is an XML file that specifies the naming authority definition required for the API Gateway. For example, a specified XML file named apigatewayNameAuthorityDefinition.xml file should contain the following settings:

    <AuthorityDefinition name="apigatewayResource" delimiters="/\">
    <Attribute name="protocol" type="MULTI_TOKEN" authority="URLBASE" />
    <AuthorityDefinition name="apigatewayAction" delimiters="/">
    <Attribute name="action" type="SINGLE_VALUE_TERMINAL" />

Configure Kerberos settings

The Kerberos Configuration under Server settings > Security > Kerberos in the node tree enables you to configure instance-wide Kerberos settings on API Gateway and to upload a Kerberos configuration file to API Gateway. This configuration file contains information on the location of the Kerberos Key Distribution Center (KDC), as well as which encryption algorithms, encryption keys, and domain realms to use.

You can also configure trace options for the various APIs used by the Kerberos system, such as the Generic Security Services (GSS) and Simple and Protected GSS-API Negotiation (SPNEGO) APIs.

Linux platforms ship with a native implementation of the GSS library, which API Gateway can leverage. You can specify the location of the GSS library in this configuration window.

For more details on different Kerberos setups with API Gateway, see the API Gateway Kerberos Integration Guide.

Kerberos configuration file krb5.conf

The Kerberos configuration file (krb5.conf) defines the location of the Kerberos KDC, supported encryption algorithms, and default realms in the Kerberos system. Both Kerberos clients and Kerberos services that are configured for API Gateway use this file.

Kerberos clients need to know the location of the KDC so that they can obtain a Ticket Granting Ticket (TGT). They also need to know what encryption algorithms to use and what realm they belong to. Kerberos services do not need to call the KDC to request a TGT, but they still require the information on supported encryption algorithms and default realms contained in the krb5.conf file.

A Kerberos client or service identifies the realm it belongs to because the realm is appended to its Kerberos principal name after the @ symbol. Alternatively, if the realm is not specified in the principal name, the Kerberos client or service assumes the realm to be the default_realm specified in the krb5.conf file. The file specifies only one default_realm, but you can specify a number of additional named realms. The default_realm setting is in the [libdefaults] section of the krb5.conf file. It points to a realm in the [realms] section. This setting is not required.

The text input field in the Kerberos configuration window displays a default configuration for krb5.conf. You can type and modify the configuration as needed, and then click OK to upload it to your API Gateway configuration. Alternatively, if you have an existing krb5.conf file that you want to use, select Load File and open to the configuration file. The contents of the file are displayed in the text area, and you can edit and upload it to API Gateway.

Refer to your Kerberos documentation for more information on the settings that can be configured in the krb5.conf file.

Advanced settings

You can configure various tracing options for the underlying Kerberos API using the check boxes on the Advanced settings tab. Trace output is always written to the /trace directory of your API Gateway installation.

  • Kerberos Debug Trace– Enables extra tracing from the Kerberos API layer.
  • SPNEGO Debug Trace – Switches on extra tracing from the SPNEGO API layer.
  • Extra Debug at Login– Provides extra tracing information during login to the Kerberos KDC.

Native GSS library

The Generic Security Services API (GSS-API) is an API for accessing security services, including Kerberos. Implementations of the GSS-API ship with the Linux platforms and can be leveraged by API Gateway when it is installed on these platforms. The fields on this tab allow you to configure various aspects of the GSS-API implementation for your target platform.

Use Native GSS Library: Select this to use the operating system’s native GSS implementation. This option only applies to API Gateway installations on the Linux platforms.

Native GSS Library Location: If you have opted to use the native GSS library, enter the location of the GSS library in the field provided, for example, /usr/lib/ On Linux, the library is called .

Native GSS Trace: Use this option to enable debug tracing for the native GSS library.