8 Configuring High Availability for Oracle Access Management Security Token Service

Security Token Service is a shared Web Service (JAX-WS) that provides a standards-based consolidated mechanism of trust brokerage between different identity domains and infrastructure tiers. Security Token Service brokers trust between a Web Service Consumer (WSC) and a Web Service Provider (WSP) and provides security token lifecycle management services to providers and consumers. Security Token Service can help simplify the effort needed to bridge access to various systems using a standardized set of interfaces.

A Security Token Service high availability deployment depends on Oracle Access Management Access Manager; the Access Manager application contains the Security Token Service server runtime. Access Manager and Security Token Service are bundled together in the OAM J2EE Application EAR file, installed together, and deployed on the same managed server in a WebLogic domain. Security Token Service is also integrated with the Oracle Access Management Console.

To administer and configure Security Token Service, see one of the following topics in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

For information on patching, see Migrating Oracle Access Manager to

This chapter includes the following topics:

8.1 Security Token Service High Availability Architecture

The following figure shows Security Token Service in a high availability architecture:

Figure 8-1 Security Token Service High Availability Architecture

Description of Figure 8-1 follows
Description of "Figure 8-1 Security Token Service High Availability Architecture"

This figure shows a two-node deployment of Access Manager/Security Token Service components.

The load balancer receives token requests and routes them to the Security Token Service (STS). Oracle recommends using external load balancers for inbound HTTP/SOAP connections. Outbound external connections to LDAP servers are load balanced with support for connection failover.

The Oracle Access Management Console provides services to manage the Security Token Service deployment. As part of the OAM deployment, the Administration Console must deploy to the Administration Server.

Each WebLogic Server domain supports one Security Token Service cluster. OAM/Security Token Service clusters cannot span domains.

The RAC Database is the same database that Access Manager uses as the Coherence backend store.

For details about the overall Access Manager high availability architecture, see Section 6.2.1, "Access Manager High Availability Architecture".

8.1.1 Clients and Client Connections

Web Service clients that implement the WS-Trust protocol interact with Security Token Service to issue or validate tokens. Clients designed to interact with an STS server, such as OWSM Client, as part of a Web Service call to a Relying Party can invoke Security Token Service.

The client connection process is as follows:

  1. The Web Service client sends a SOAP message over http or https.

    The WSS protocol protects the message. The payload contains a WS-Trust request (RST) indicating the operation to perform, which kind of token to issue or validate, and additional information about the token characteristics.

  2. The server processes the request and sends a response over the same channel the server received it on.

    The WSS protocol protects the message. The payload contains a WS-Trust response (RSTRC) if the processing was successful or a SOAP fault if an error occurs.

8.1.2 Cluster Wide Configuration Changes

Each Security Token Service Access Server instance is a peer of other instances with no inter-instance communication. Because all initialization happens before the Server is ready to receive requests combined with built in throttling capabilities, the WebLogic Server handles surge conditions gracefully without any significant effect on Security Token Service Access Server performance characteristics.

When the cluster stops, the Security Token Service denies new requests and permits existing requests to complete before the Access Server application shuts down. If a forced shutdown occurs, Security Token Service can recover for any corrupted/invalid data that the shutdown causes.

Propagation of configuration changes to all the cluster members is based on a distribution mechanism that leverages the Coherence distributed object cache. The coherence layer notifies all Security Token Service components of change events. The components then uptake these change events. Access Manager components reload their entire configuration every time a change happens.


The addition/removal of Access Server instance(s) is transparent to other Security Token Service instances in the cluster. Verify that removing a specific Security Token Service server does not affect the load.

8.2 Security Token Service Component Characteristics

This section includes the following topics:

8.2.1 Security Token Service Component Lifecycle

On startup, the Access Manager/Security Token Service Server starts connections to backend repositories. If the repository is not reachable, the Access Manager/Security Token Service server retries the connections using a timeout that grows exponentially with a configurable upper limit.

The Access Manager/Security Token Service Server provides continuity of service based on locally cached data if the backend connections go down. Service continues until the caches grow stale or the backend connections come up again.

8.2.2 Runtime Processes

The following graphic shows the Security Token Service runtime process.

Figure 8-2 Security Token Service Runtime Process

Description of Figure 8-2 follows
Description of "Figure 8-2 Security Token Service Runtime Process"

The Security Token Service runtime process works as described below:

  1. A Web Service Consumer (WSC) sends a Web Services-Trust Request Security Token (RST)) message for a security token type that the WSP requires. Client authentication occurs using transport layer authentication, or by binding the WSS Token to the RST message.

  2. The Security Token Service (STS) validates the RST message, authenticates the request, then authorizes the requested operation.

  3. The appropriate security token is generated in accordance with metadata that the RST message specifies. For a policy driven exchange use-case, STS looks up the appropriate token generation policy to generate the appropriate security token.

  4. STS generates an RST message that contains the generated security token; it sends the message to the WSC as a response.


WSP validation of the security token depends on the token type. When STS acts as a trust intermediary only, validation is performed against the underlying security infrastructure, such as Kerberos. Starting and Stopping Security Token Service

Because they are J2EE applications, you can start the Access Server (where Security Token Service is deployed) and the Administration Console from the user interface and Command Line tool that the Application Server provides. J2EE Components and Subcomponents

J2EE Components and sub-components include the following:

  • STS - An event-based design pattern that implements the core Security Token Service 11g-PS1. Packaged as a WAR application in the Access Manager EAR file, it comprises a WS Provider Servlet and Java classes. The STS Web Application is bound to the /sts root path

  • Admin Console - A stand-alone console based on ADF/IDM Shell. Packaged as an .EAR file.

  • JMX Mbeans - Packaged with the Access Server. Config Mbeans are packaged as standalone JAR files.

  • WSLT Command - Consists of Java classes that are in the Access Manager/Security Token Service package.

  • OWSM Agent - Web Service interceptor that supports WSS protocol, part of JRF.

  • ORAProvider - JRF Web Service Provider Session State Information

Security Token Service is a stateless J2EE application with the exception of the Nonce caching for Username Tokens, where Security Token Service keeps track of presented username tokens when the nonce is present, to prevent replay attacks.

8.2.3 Configuration Artifacts

Access Manager and Security Token Service are built together and use the same modules for configuration, logging, and other processes. The Security Token Service configuration artifacts include the following files.

  • DOMAIN_HOME/config/fmwconfig/oam-config.xml — Configuration file, which contains instance-specific information.

  • DOMAIN_HOME/config/fmwconfig/oam-policy.xml — Present only when OES Micro SM is not being used.

  • DOMAIN_HOME/config/fmwconfig/servers/instanceName/logging.xml — Logging config

  • DOMAIN_HOME/config/fmwconfig/cwallet.sso — stores passwords that are used to connect to identity stores, database, and other entities. This is not for end user passwords.

  • DOMAIN_HOME/config/fmwconfig/.oamkeystore — keystore containing keys and certificates Access Manager/Security Token Service owns

  • DOMAIN_HOME/config/fmwconfig/amtruststore — keystore containing the trust anchors used for X509 cert validation

  • DOMAIN_HOME/config/fmwconfig/amcrl.jar — zip file containing CRLs used for certificate revocation

  • DOMAIN_HOME/config/fmwconfig/default-keystore.jks — OWSM keystore used to store keys and certificates used by the OWSM Agent, as well as trusted anchors used to validate X.509 certificates for WSS operations

  • DOMAIN_HOME/config/fmwconfig/.cohstore.jks - trust store that Coherence SSL communication uses

8.2.4 External Dependencies

Security Token Service has external dependencies on the:

  • LDAP based Identity Store

    • User Identity Repository

    • LDAP access abstracted by User/Role API.


      Access Manager always connects to one Identity store, which can be a physical server or a load balancer IP. If the primary is down, Access Manager reconnects and expects the load balancer to connect it to the secondary.
  • OCSP Responder Service

    • Real-time X.509 Certification Validation

  • RDBMS Policy Store/Coherence Store

    • Policy (Authentication and Authorization) Repository

    • RDBMS access abstracted by the OAM policy engine

    • OPSS Security Store

8.3 Security Token Service High Availability Configuration Steps

Security Token Service High Availability is configured as part of Access Manager. All Security Token Service system configuration is done using the Oracle Access Management Console. See Section 6.4, "Access Manager High Availability Configuration Steps" for more information.

8.4 Validating Security Token Service High Availability

You can verify that Security Token Service endpoints are up and running on the different Security Token Service servers. To do so, access the WSDL document of an Security Token Service endpoint directly: http(s)://[hostname:port]/sts/[ENDPOINT]/WSDL

Replace [ENDPOINT] with the existing published endpoint.

8.5 Security Token Service Failover and Expected Behavior

Access Manager Access Servers support a heartbeat check--a ping request over HTTP. Also, Node Manager can monitor the application and restart it if necessary.

If a WebLogic Server node fails, external connection failover is based on the configuration, the retry timeout, and the number of retries. Access Manager Agent-Access Server failover is based on a timeout.

When the load balancing router or proxy server detects a WebLogic Server node failure, subsequent client connections go to the active instance, which picks up the session state from Coherence Distributed Object Cache and continues processing.

Front Channel HTTP bindings use a load balancing router for failover.

When it receives an exception from another service, Access Manager retries external connection requests. You can configure the number of retries (includes a no retries option).

See the following topics for more information:

8.5.1 Death Detection and Restart

Access Manager/Security Token Service Access Servers support a heartbeat check in the form of a ping request sent over HTTP. Also, the WebLogic Node Manager on the managed server can monitor the application and restart if the event isn't running. Restarting an Access Manager Access Server does not affect any other cluster components or members.

8.5.2 Node Failure

External Connection failover is based on the configuration, retry timeout, and the number of retries. The load balancer or Proxy Server detects node failure and subsequent client connections are routed to the active instance, which picks up the session state from the Coherence DOC and continues with the processing.

8.6 Disabling and Enabling Security Token Service

Security Token Service is enabled by default. To disable Security Token Service, you use the Oracle Access Management Console. See Enabling or Disabling Available Services in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

8.7 Troubleshooting Security Token Service

Security Token Service logs are logged to Managed Servers log files. However, you can edit logging.xml so that it logs Security Token Service logs to the file diagnostic.log in <DomainHome>/config/fmwconfig/servers/<servername>/sts/log/.

To create an Security Token Service log file to troubleshoot Security Token Service:

  1. Open the file DomainHome/config/fmwconfig/servers/servername/logging.xml

  2. Add the following in the appropriate sections:

    <log_handler name='sts-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
          <property name='path' value='sts/log'/>
          <property name='maxFileSize' value='10485760'/>
          <property name='maxLogSize' value='104857600'/>
    <logger name='oracle.security.fed' level='TRACE:32'>
          <handler name='sts-handler'/>

8.8 Log File Location

All log messages go to the server log file of the WebLogic Server that you deploy the application on. The default server log file location is:


8.9 Additional Considerations

The Security Token Service server can detect fake requests, such as replay attacks, that can occur if a user tries to steal token data from a request and send another request with the same token. In this case, the server detects the second fake request. The second issuance request with the same token in <Env: Body> goes to the Security Token Service server. It denies the request after checking its UNT token cache, which indicates a replay attack.