33 Managing Security Token Service Settings and Set Up

This chapter introduces how to manage components involved in the protection of Security Token Service endpoints. This chapter provides the following topics:

33.1 Prerequisites

This section identifies requirements for tasks in this chapter.

Before you begin tasks in this chapter, be sure to review the following topics:

33.2 Introduction to Security Token Service Configuration

Security Token Service a Web Service co-existing with Access Manager. Security Token Service invokes some Access Manager components to validate and issue security tokens. Typically, the Web client can use the Security Token Service to request an outbound token, such as SAML, by providing a security token, like a Username Token or an X.509 Token.

Security Token Service is integrated with the Oracle Access Management Console to provide a unified and consistent administration experience. All Security Token Service system configuration is done using the Oracle Access Management Console.

Security Token Service provides:

  • Tokens:

    • Validation Tokens: Standard (Username, X.509, Kerberos, SAML 1.1/2.0) and custom tokens. OnBehalfOf use cases (OAM Session ID Propagation Token and custom tokens through the integration engine) also supports the following standard tokens along with OAM sessionID propagation token and custom token (Username, X.509, SAML 1.1/2.0).

    • Issuance Tokens: Standard (Username, SAML 1.1/2.0) and custom tokens through the integration engine

  • Configuration-driven token issuance and validation

  • Enhanced auditing through identity propagation across multiple tiers and domains

  • Consolidated shared-platform service interacts with internal (Access Manager SSO, Federation, Oracle Web Services Manager) and external services

This section provides the following topics:

See Also:

Oracle Fusion Middleware Security and Administrator's Guide for Web Services

33.2.1 Post-Installation Configuration

After installation and server startup, you can access the Oracle Access Management Console on the OAM Server. For example, if the URL to the OAM Server is http://machine:14100/oam, you might access:

  • Oracle Access Management Console at http://machine:7001/oamconsole

  • Security Token Service: http://machine:14100/sts/wss11user?wsdl to view the WSDL of the /sts/wss11user endpoint that is available by default, to ensure that Security Token Service is available.

    By default, Security Token Service is disabled and as such all runtime functionality as well as Web Service endpoints are disabled. To access those endpoints, Security Token Service must first be enabled using the Oracle Access Management Console. Afterwards, the endpoints might be accessed

Post-installation configuration includes the tasks in the following outline, which point to other areas in this book for details.

Task overview: Security Token Service configuration requires

  1. Server Side Configuration: Use the Oracle Access Management Console for the following tasks.

    1. Service enablement "Enabling and Disabling Services for Security Token Service"

    2. Settings configuration "Managing Security Token Service Settings"

    3. Endpoint registration "Managing EndPoints"

    4. Token Issuance Template configuration "Managing Token Issuance Templates"

    5. Token Validation Template configuration "Managing Token Validation Templates"

    6. Partner Profile creation "Managing Token Service Partner Profiles"

    7. Partner configuration "Managing Token Service Partners"

    8. Token Issuance Policies to define an authorization rule for issuing tokens with Security Token Service, for a specific Relying Party "Managing Token Issuance Policies, Conditions, and Rules"

  2. Set up interactions with the Oracle WSM Agent as described in following topics:

    1. Using and Managing WSS Policies for Oracle WSM Agents

    2. Configuring OWSM for WSS Protocol Communication

  3. Set up message logging, as described in "Introduction to Logging Security Token Service Messages".

  4. Configure event auditing, as described in "Setting Up Auditing for Oracle Access Management".

  5. Configure lifecycle management

    1. Register the Security Token Service trust endpoint, as described in item 1c.

    2. Register the Requester or Relying Party Partner with Security Token Service, as described in "Managing Token Service Partners".

    3. Monitor performance, as described in Chapter 11, "Monitoring Performance and Logs with Fusion Middleware Control".

33.2.2 About OAM Servers and Security Token Service

With Oracle Access Management, all Security Token Service instances are installed on OAM Servers (also known as Managed Servers). Each server must be registered with Access Manager.

Security Token Service leverages the common infrastructure for shared services and the Oracle Access Management administration model.

Security Token Service support Web Services Security protocol 1.0 and 1.1 and process the following tokens, if present in the Security SOAP headers:

  • Username token (UNT)

  • SAML 1.1 or SAML 2.0 Assertion

  • Kerberos

  • X.509

Note:

Managed servers hosting Security Token Service must be registered with Access Manager as described in Chapter 5, "Managing Server Registration".

Third-Party Servers: Security Token Service interoperates with third party security token servers. For instance, a third party Security Token Service can create a valid Security Assertion Markup Language (SAML) Assertion that can be consumed by Security Token Service.

33.2.3 About Security Token Service Clients

Security Token Service provides services to various Oracle clients (Oracle Web Services Manager client) or third party clients (Microsoft and IBM are two).

Oracle WSM Client: Oracle Web Services Manager client bindings are the responsibility of Oracle Web Services Manager (and out of scope for this book). For more information, see "Configuring Oracle WSM Agent for WSS Kerberos Policies".

See Also:

"WS-Trust Policies and Configuration Steps" in Oracle Fusion Middleware Security and Administrator's Guide for Web Services

Third Party Clients: Require a secure key exchange between the Oracle WSM client and server. You simply import the Security Token Service certificate to the client.

During SOAP interactions, the WS-Security protocol might require the client to trust the signing/encryption certificate used for WSS operations by the OWSM Agent protecting the Security Token Service endpoint. In those cases, the Oracle Access Management Administrator should extract the Security Token Service OWSM signing/encryption certificate used for WSS operations and provide it to the WS Client. For more information, see "Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate".

33.2.4 About Agents and Security Token Service

Oracle Web Services Manager communicates through agents. This topic introduces the agents that operate with Security Token Service.

Oracle WSM Agent: The Oracle Web Services Manager (Oracle WSM) Agent is integrated with Security Token Service. This agent provides the Web Services Security support for Security Token Service Web Services endpoints.

  • Protects Web Services endpoints of Security Token Service

  • Provides WS-Security support for sending SOAP messages to Relying Parties. As part of that process, the OWSM Client might interact with Security Token Service to get a security token that will be presented to the Relying Party

  • Interacts with Security Token Service for token acquisition and token validation

Security Token Service supports token acquisition and token validation by Oracle Web Services Manager (Oracle WSM) agents. Oracle Web Services Manager Agents are not required to use Security Token Service as part of their inbound or outbound security policy enforcement. Oracle Web Services Manager client bindings are the responsibility of Oracle Web Services Manager Administrators.

The Oracle WSM Agent is used by Security Token Service to enforce message protection of the SOAP communication channel between Security Token Service and the client. The Oracle WSM Agent caches the OPSS Keystore (by default the default-keystore.jks keystore located in $DOMAIN_HOME/config/fmwconfig directory) which contains the trusted certificates involved when validating the WSS clients' certificates. Subsequent changes to the contents of the keystore or to its name, require a restart of the Managed Server using Oracle Enterprise Manager Fusion Middleware Control or WebLogic Server console, or NodeManager.

The Oracle WSM Agent available to Security Token Service must be configured to protect the Security Token Service endpoints, to perform the following tasks:

  • Decrypt the request, if necessary

  • Verify any digital signatures present in the request

  • Validate any certificate used to create the request's digital signatures, if the signatures were created with a private key

  • Validate any X.509 token, if present, in the SOAP headers

  • Validate the Kerberos token, if present, in the SOAP headers

  • Sign the outgoing response, if needed

  • Encrypt the outgoing response, if required

Oracle WSM Agent Keystore: The Oracle WSM Agent uses a keystore for various cryptographic operations. For these operations, the Oracle WSM Agent uses the keystore configured for Oracle WSM tasks.

Webgate: Security Token Service uses Webgate for the Access Manager session propagation token. This, identity propagation, use case is more advanced. It requires the Identity Assertion Provider in WebLogic Server and some custom integration.

33.2.5 About Security Token Service End Points and Policies

When you add an endpoint, you can choose from a list of Policy URI's and validation templates with which to associate the Security Token Service endpoint. By default, Security Token Service is configured with the endpoints shown in Figure 33-1.

Figure 33-1 Default Endpoints, Policies, and Validation Templates

Description of Figure 33-1 follows
Description of "Figure 33-1 Default Endpoints, Policies, and Validation Templates"

The ORAPROVIDER is integrated with the Oracle WSM Agent, which provides Web Services Security support on the SOAP messages being exchanged between the client and Security Token Service. Security Token Service leverages ORAPROVIDER for Web Services to:

  • publish Web Services endpoints dynamically

  • invoke Security Token Service to process SOAP messages

  • publish a WSDL file for each WS endpoint

Oracle WSM Agent WSS Policy Stores: The Oracle WSM Agent requires a repository to retrieve the Web Services Security (WSS) policies it needs. Security Token Service supports two types of repositories:

  • JAR file with WSS Policies: Used when the WLS Domain is configured for classpath.

  • Oracle WSM Policy Manager available from the SOA deployment

See Also:

  • "Configuring OWSM for WSS Protocol Communication"

  • Managing Oracle Workspace Studio policies for Security Token Service

  • Oracle Fusion Middleware Security and Administrator's Guide for Web Services for details about the policies for Security Token Service

Policy Assertions: Out of the box, Security Token Service provides a set of security policy assertions for use with the WS-Policy framework to describe how messages are to be secured in the context of Oracle Workspace Studio: SOAP Message Security and WS-Trust.

  • Security Token Service makes its associated security policy files publicly available by attaching them to its deployed WSDL.

  • Security Token Service runtime uses the private key and X.509 certificate pairs, stored in the keystores defined by the jps-config.xml file, for its WS-Security encryption and digital signature operations.

The following paragraphs and tables identify the policies that are available out of the box for Security Token Service and the Oracle WSM Agent.

Message-level Security Not Required: When message level-security is not required, use an Security Token Service policy that does not specify message_protection in its name. This authenticates users using credentials provided in tokens in the WS-Security SOAP header. The credentials in the Fusion Applications token are mapped based on the rules specified in the validation template. Both plain text and digest mechanisms are supported.

Transport Security when Message-level Security Not Required: You can configure two-way SSL where both the client applications and WebLogic server present certificates to each other. To configure two-way or one-way SSL for the core WebLogic Server security see "Configuring SSL" in Oracle Fusion Middleware Securing Oracle WebLogic Server guide. Use the policies described in Table 33-1.

Interoperability WS-Security 1.0 and 1.1 Policies: Use policies in Figure 33-2 if you require interoperability with WS-Security 1.0 or 1.1 (depending on your authentication requirements and credential availability). Use WS-Security 1.1 policies if you have strong security requirements.

Figure 33-2 WS-Security 1.0 and 1.1 Policies

Description of Figure 33-2 follows
Description of "Figure 33-2 WS-Security 1.0 and 1.1 Policies"

Task overview: Using and modifying WS-S policies

  1. From the Oracle Access Management Console, System Configuration tab, open the Security Token Service section.

  2. From the Endpoints node, proceed as described in "Managing Security Token Service Endpoints" to locate or create the endpoint to be protected.

  3. From the Policy URI list, choose a specific WS Security policy to protect the endpoint, as described in:

33.3 Enabling and Disabling Security Token Service

This topic includes the following topics:

33.3.1 About Security Token Service and the Oracle Access Management Console

Elements in the Oracle Access Management Console enable Administrators to easily configure the Token Service to exchange WS Trust tokens with partners. Token Service elements provide for creation, viewing, modification, and removal of partners, endpoints, validation templates, issuance templates, and data store connections.

All Security Token Service system configuration is done using the Oracle Access Management Console. This includes the following common tasks covered in Part II of this book:

  • Registering and managing common OAM Servers and proxy information

  • Registering and managing the common Default User Identity Store

  • Configuring the OAM Keystore, which differs from the OWSM Keystore used for WSS processing

  • Certificate Validation and Revocation

The Oracle Access Management Console enables Administrators to perform the following Security Token Service-specific tasks:

  • Manage validation token templates: The validation templates include configuration properties to validate a Web Services Security/WSTrust token, and map it to a Requester Partner or a User record in the Default User Identity Store.

  • Manage issuance templates: The issuance templates contain rules on how a token will be created

  • Manage Partner Data: A partner represents a partner trusted by Security Token Service. Security Token Service defines three types of partners: Requester, Relying Party and Issuing Authority. Each partner entry is associated to a partner profile. The partner entry contains signing and encryption certificates and identifiers used to uniquely identify a partner

  • Manage Partner Profile: A partner profile contains configuration properties that are common to a set of partners:

    • Claim Mapping

    • Token Types definition

    • Issuance and Validation templates defined for the token Types

    • Override Validation Template rules for Issuing Authorities(Other STS)

  • Manage Security Token Service Endpoints

  • Manage Token Issuance Policies (authorization policies that will be evaluated to determine if a Requester Partner can request a token based on the Relying Party referenced in the request)

  • Security Token Service Global Settings

  • Custom tokens

33.3.1.1 About Security Token Service Administrators

Users with administrative access to the Oracle Access Management Console, have access to Security Token Services.

Initially, administrative users must log in to the Oracle Access Management Console using the WebLogic Administrator credentials set during initial configuration. However, your enterprise might require independent sets of Administrators: one set of users responsible for Access Manager and another for Security Token Service.

33.3.1.2 About Logging In To, and Signing Out Of, Security Token Service

When using Security Token Service with Access Manager, logging in to, and signing out of the Oracle Access Management Console is the same.

33.3.2 About Enabling Services for Security Token Service

To use Security Token Service, both it and Access Manager must be enabled, as shown in Figure 33-3. By default Security Token Service is disabled and needs to be enabled.

Figure 33-3 Available Services Panel

Description of Figure 33-3 follows
Description of "Figure 33-3 Available Services Panel"

A green check mark in the Status field beside the service name indicates the service is enabled. A red circle with a line through it indicates that the corresponding service is disabled.

33.3.3 Enabling and Disabling Services for Security Token Service

Prerequisites

Oracle Access Manager service must be enabled.

To enable or disable Security Token Service

  1. Log in to the Oracle Access Management Console, as usual

         https://hostname:port/oamconsole/
    
  2. From the System Configuration tab, Common Configuration section, click Available Services.

  3. Enable Security Token Service: Beside Security Token Service, click Enable (or confirm that the Status check mark is green) and confirm that the Access Manager Service is also enabled.

  4. Disable Security Token Service: Beside Security Token Service, click Disable (or confirm that the Status check mark is red).

33.4 Defining Security Token Service Settings Using Oracle Access Management Console

This section provides the following information:

33.4.1 About Security Token Service Settings

Security Token Service can be viewed or altered from the Security Token Service section of the System Configuration tab. These settings are show in Figure 33-4.

Figure 33-4 Security Token Service Page

Description of Figure 33-4 follows
Description of "Figure 33-4 Security Token Service Page"

Table 33-1 describes the elements on the Security Token Service Settings page.

Table 33-1 Security Token Service Settings

Element Description

Partner Identification Attributes

A field where you list attributes, other than the standard ones available by default, that should be available in "Identity Attributes" Table in the Partner page. These attributes can be used to identify a partner by matching their values against those in the incoming request.

When a Requester sends a WS-Trust request to Security Token Service, the server might map the incoming token containing the requester's identity to a partner entry in the Security Token Service partner store.

To do so, Security Token Service will use the mapping settings configured in a validation template and will attempt to map the token data to a partner entry by performing a lookup by matching the token data to a Partner Identification Attribute.

By default, each requester partner contains three identification attributes that can be set: username, HTTP Basic Username, SSL Client Certificate DN.

It is possible to define additional Identification Attributes that could be set for each requester partner entry.

This section allows new attributes to be set. After defining a new attribute, it becomes available in the Requester Partner entry section, and it can be used in mapping rules in the WSS Validation Templates.

Custom Trust Anchor File

By default, Access Manager and Security Token Service use the default $DOMAIN_HOME/config/fmwconfig/amtruststore keystore containing the trust anchors used for certificate validation by Security Token Service, when verifying X.509 Tokens, or when verifying certificates used in SAML Assertion signatures.

It is possible to configure Security Token Service to use a specific trust anchor file if necessary, that will contain trust anchors only used for Security Token Service operations and validations. In this case, this field should contain the location of the JKS keystore to use.

Note the following:

  • When using a custom trust anchor keystore, it will not be replicated automatically across the cluster. You must manage replication.

  • In most cases, the default Access Manager and Security Token Service trust anchor should be enough.

See Also: Chapter 34, "Managing Security Token Service Certificates and Keys"

Default Encryption Template

A list from which you choose the default template for Security Token Service encryption:

  • osts_encryption

  • osts_signing

See Also: Setting the Default Encryption Key.

Proxy

Outbound Connection Properties, HTTP Proxy Settings Use this section to configure Security Token Service to use a proxy for outgoing HTTP connections when optionally retrieving the WS-Sec Policy of Relying Parties at runtime:

  • Enabled: When this box is checked the Proxy function is enabled and will be used when retrieving the WS-Security Policy of Relying Parties. When the box is not checked, the Proxy function is disabled and related fields are inaccessible for editing.

  • Host: The proxy hostname

  • Port: The proxy port number. Default is 8080

  • Non Proxy Hosts: A list of hosts for which the proxy should not be used. Use ';' to separate multiple hosts.

  • Username: The username to use when connecting to the proxy.

  • Password: The password to use when connecting to the proxy.

Keystore

Location: Path of the active keystore that was set up during Security Token Service installation.

The Keystore table includes the following information for each of the templates in the table, which are available for use as the Default Encryption Template:

  • Template ID: The name of the template that can access the keystore.

  • Alias: Identifies the alias for the template. When adding a template, you can choose from the Aliases listed. For example:

    Aliases for use with OSTS Encryption Templates
  • Password: The password for the selected Alias.

  • Description: Optional.

The keystore section defines key entries that exist in the Security Token Service keystore: $DOMAIN_HOME/config/fmwconfig/.oamkeystore

After an entry is defined an entry, it can be used in other Security Token Service templates (like SAML Issuance Templates).


33.4.2 Managing Security Token Service Settings

Users with valid Administrator credentials can use this procedure to confirm or alter Security Token Service Settings.

Prerequisites

Both the Access Manager Service and the Security Token Service must be enabled.

To view or edit Security Token Service Settings

  1. Log in to the Oracle Access Management Console, as usual.

         https://hostname:port/oamconsole/
    
  2. From the System Configuration tab, open the Security Token Service Settings section.

  3. Double-click the Security Token Service Settings

  4. On the Security Token Service Settings page view (or modify) the following information (see Table 33-1):

    • Partner Identification Attributes

    • Custom Trust Anchor File

    • Proxy details

  5. Keystore Table: View, add, or remove new encryption templates

  6. Click Apply to submit changes (or Revert to cancel changes).

  7. Close the page when finished.

33.5 Using and Managing WSS Policies for Oracle WSM Agents

You can use existing Oracle Workspace Studio policies to protect Security Token Service Web Service endpoints. For instance:

  • classpath mode: Existing Oracle Workspace Studio policies defined in $ORACLE_IDM_HOME/oam/server/policy/sts-policies.jar are used in this mode

  • SOA deployment: Policies defined in the Oracle WSM Policy Manager available from a SOA deployment are used

This section describes how to manage Web Service Security Policies for Security Token Service in the following topics:

33.5.1 Using and Modifying Oracle Workspace Studio Policies

This section introduces WS-Security Policies used to protect Security Token Service WS Endpoint and how to modify these policies. TheWS-Security Policies that are provided by Oracle should cover most use cases.

See Also:

33.5.2 Managing WSS Policies for Security Token Service: Classpath

Predefined Oracle Web Services Manager policies are constructed using assertions based on predefined assertion templates. For WSS Policy classpath mode, the OWSM Agent retrieves policies from sts-policies.jar located on the classpath.

If SOA is not deployed in the WebLogic Server domain, the Security Token Service installer configures the WebLogic Server domain for WSS Policy classpath mode. The JAR file containing the WSS Policies used when the WLS Domain is configured for classpath is located at:

$ORACLE_IDM_HOME/oam/server/policy/sts-policies.jar

When your environment is in classpath mode, perform the following tasks to Administrators confirm sts-policies.jar is located on the classpath.

See Also:

Task overview: Managing WSS Policies for Security Token Service: Classpath

  1. Define an OWSM Assertion Template.

  2. Proceed as follows, depending on your need:

    • Modify an OWSM Policy

    • Define a Policy using the OWSM Assertion Template

  3. Bundle the Assertion Template and policy in the sts-policies.jar file:

    META-INF/assertiontemplates/oracle of the $ORACLE_IDM_HOME/oam/server/policy/
    sts-policies.jar
    
  4. Confirm that sts-policies.jar is located in the following path to enable the policy URI to be available the Policy URI drop down list.

    $ORACLE_IDM_HOME/oam/server/policy/sts-policies.jar
    
  5. Restart the Managed Servers running Security Token Service.

  6. Proceed to the Oracle Access Management Console to configure the Security Token Service Endpoints.

33.5.3 Managing WSS Policies for Security Token Service: Oracle WSM Policy Manager

The Oracle WSM Policy Manager is the security linchpin for Oracle Fusion Middleware Web services and SOA applications. For more information about how the Oracle WSM Policy Manager manages the policy framework, see "Understanding Oracle WSM Policy Framework" in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

At design time, you attach Oracle WSM and WebLogic Web service policies to applications programmatically using your favorite IDE, such as Oracle JDeveloper. Alternatively, at deployment time you attach policies to SOA composites, ADF, and WebCenter applications using the Oracle Enterprise Manager Fusion Middleware Control, and to WebLogic Web services (Java EE) using the WebLogic Server Administration Console.

System Administrators can leverage the Oracle WSM through the Oracle Enterprise Manager Fusion Middleware Control to:

  • Centrally define policies using the Oracle WSM Policy Manager.

  • Enforce Oracle WSM security and management polices locally at run time.

When your environment is integrated with the OWSM Policy Manager, perform the following tasks to add or modify WSS policies for Security Token Service using Oracle Web Services Manager.

Note:

All of Oracle WSM's functionality is accessible to Administrators from Oracle Enterprise Manager Fusion Middleware Control.

See Also:

Oracle Fusion Middleware Security and Administrator's Guide for Web Services
  • Part II, "Basic Administration"

  • Part III, "Advanced Administration"

Task overview: Managing WSS Policies for Security Token Service: OWSM Policy Manager

  1. From the OWSM Policy Manager, locate and open the desired policy.

  2. Refer to the Oracle Fusion Middleware Security and Administrator's Guide for Web Services and make any required changes to the policy.

  3. Restart all Managed Servers running Security Token Service.

  4. Proceed to "Configuring OWSM for WSS Protocol Communication".

33.6 Configuring OWSM for WSS Protocol Communication

This section describes how to configure communication between WS-Sec Clients and the Oracle WSM Agent embedded with Security Token Service.

The Oracle WSM Agent protects the Web Service endpoints of Security Token Service, and provides support for WSS protocol exchanges. To ensure a client is communicating successfully with the Oracle WSM Agent:

  • The client might need to be aware of the signing and encryption certificates used by the Oracle WSM Agent (this will require extracting and distributing the signing and encryption certificates used by the OWSM Agent embedded with Security Token Service).

  • The Oracle WSM Agent might need to be aware, depending on the policies, of the signing certificate used by the client (this will require adding the client's certificate as a trusted certificate for the Oracle WSM Agent)

Task overview: Configuring communication with Oracle WSM agents

  1. See "About Oracle WSM Agent WS-Security Policies for Security Token Service"

  2. Retrieving the Oracle WSM Keystore Password

  3. Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate

  4. Adding Trusted Certificates to the Oracle WSM Keystore

  5. Validating Trusted Certificates in the Oracle WSM Keystore

  6. Configuring Oracle WSM Agent for WSS Kerberos Policies

33.6.1 About Oracle WSM Agent WS-Security Policies for Security Token Service

The Oracle WSM Agent requires a repository to retrieve the Web Services Security (WSS) policies it needs. Access Manager supports two types of repositories for Security Token Service:

  • JAR file with WSS Policies: Used when the WLS Domain is configured for classpath. The required JAR file is located in $ORACLE_IDM_HOME/oam/server/policy/ sts-policies.jar.

  • Oracle WSM Policy Manager available from the SOA deployment

During Security Token Service installation, the installer detects if the Oracle Web Services Manager Policy Manager is present and deployed in the WebLogic Security domain.

  • If not deployed in the WebLogic Security domain, the installer configures the WebLogic Security domain for the Web Services Security Policy classpath mode, where the WSM Agent will retrieve the policies from a JAR file.

  • If present, the installer connects to the Oracle Web Services Manager Policy Manager and uploads the policies that are used to protect Security Token Service endpoints.

See Also:

"About the Database Store for Policy, Password Management, and Sessions" for details about the required database for Access Manager policy data and (optionally) Access Manager session data.

33.6.2 Retrieving the Oracle WSM Keystore Password

Administrators need to retrieve the keystore password and key entry password from CSF for certain activities. Otherwise, keystore or key entry cannot be changed. Having access to the keystore is sometimes required to:

  • Extract the signing/encryption certificate to distribute to clients if necessary

  • Update or replace the signing/encryption key entry

  • Add trusted certificates

The following procedure displays the password used to protect the Oracle WSM keystore as well as the key entry.

To retrieve the Oracle WSM keystore password

  1. Enter the WSLT scripting environment.

  2. Connect to the WebLogic Server AdminServer, using the connect() command.

  3. Execute the following command by providing the connection information to the AdminServer: listCred(map="OAM_STORE", key="jks").

  4. Note the password.

  5. Proceed to "Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate".

33.6.3 Extracting the Oracle STS/Oracle WSM Signing and Encryption Certificate

During SOAP interactions, the WS-Security protocol might require the client to trust the signing/encryption certificate used for WSS operations by the OWSM Agent protecting the Security Token Service endpoint. In those cases, the Oracle Access Management Administrator should extract the Security Token Service OWSM signing/encryption certificate used for WSS operations and provide it to the WS Client.

The Administrator must export the signing and encryption certificate used by Security Token Service for WSS cryptographic operations. The following procedure guides as you do this by:

  • Replacing $DOMAIN_HOME with the path to the Domain directory

  • CERT_FILE with the location of the file where the certificate will be saved

If you are prompted to enter a password, simply press the Enter key.

Prerequisites

Retrieving the Oracle WSM Keystore Password

To export the signing and encryption certificate

  1. Locate keytool.

  2. Execute the following command.

    keytool -exportcert -keystore $DOMAIN_HOME/config/fmwconfig/default-keystore.j 
    ks -storetype JKS -alias orakey -file $CERT_FILE
    
  3. Enter the keystore password retrieved in the previous section if prompted.

  4. Proceed to "Adding Trusted Certificates to the Oracle WSM Keystore".

33.6.4 Adding Trusted Certificates to the Oracle WSM Keystore

To add a trusted certificate to the OWSM keystore for WSS cryptographic operations:

  • perform the command in the following procedure

  • replace the $DOMAIN_HOME with the path to the Domain directory

  • replace the TRUSTED_CERT_FILE with the location of the file containing the trusted certificate

  • replace the TRUSTED_CERT_ALIAS with the alias under which the trusted certificate will be stored

When prompted to enter a password, enter the password of the OWSM keystore that you retrieved earlier.

Prerequisites

Retrieving the Oracle WSM Keystore Password

The Administrator must have the certificate to import.

To add trusted certificates to the Oracle WSM keystore

  1. Locate keytool.

  2. Execute the following command.

    keytool -importcert -trustcacerts -keystore $DOMAIN_HOME/config/fmwconfig/de 
    fault-keystore.jks -storetype JKS -alias $TRUSTED_CERT_ALIAS -file $TRUSTED_ 
    CERT_ALIAS
    
  3. Observe messages on the screen, enter a password if requested.

  4. Proceed to "Validating Trusted Certificates in the Oracle WSM Keystore".

33.6.5 Validating Trusted Certificates in the Oracle WSM Keystore

When the Oracle WSM Agent performs a certificate validation, it uses the keystore configured for Oracle WSM tasks, and will validate the certificate against the trusted certificate entries contained in the keystore. For those operations, it might be required to add trusted certificate entries (the certificate itself or the issuer's certificate) in the OWSM keystore.

When receiving a SOAP requester, the Oracle WSM Agent processes the request for message protection. Part of the steps might include a certificate validation operation if the incoming message:

  • is of type WSS 1.0, and includes a digital signature created with a private key, without the certificate being present. In this case:

    Remedy: The Oracle WSM keystore must contain the signing certificate.

  • is of type WSS 1.0, and includes a digital signature created with a private key, with the certificate being present.

    Remedy: The Oracle WSM keystore must contain either the signing certificate or the issuer's certificate of the signing certificate.

  • is of type WSS 1.1, and includes a digital signature created with a private key, without the certificate being present.

    Remedy: The Oracle WSM keystore must contain the signing certificate.

  • is of type WSS 1.1, and includes a digital signature created with a private key, with the certificate being present. In this case, the OWSM keystore will need to contain either the signing certificate or the issuer's certificate of the signing certificate

    Remedy: The Oracle WSM keystore must contain either the signing certificate or the issuer's certificate of the signing certificate

33.6.6 Configuring Oracle WSM Agent for WSS Kerberos Policies

Security Token Service provides services to various Oracle clients (Oracle Web Services Manager client) or third party clients (Microsoft and IBM are two). the Oracle WSM Agent performs only message protection (not authentication) on the incoming request. The Oracle WSM agent does not attempt to map the incoming Kerberos ticket to a user record in the OPSS Identity Store.

If Oracle WSM is the client that will interact with Security Token Service using WSS Kerberos policies, then the entire Oracle WSM Kerberos setup section in Oracle Fusion Middleware Security and Administrator's Guide for Web Services applies.

However, if the client is not Oracle WSM, see Table 33-2 and disregard sections on how to configure the client, sections related to authenticating the user referenced in the Kerberos ticket.

Table 33-2 Configuring a Non-Oracle WSM Client for WSS Kerberos Policies

Perform Tasks for Non-Oracle Client Skip These Tasks for Non-Oracle Client

Configure the KDC

 

Initialize and Start the MIT Kerberos KDC

 

Create Principals

 

Configure the Web Service Client to Use the Correct KDC

 
 

Set the Service Principal Name In the Web Service Client

 

Set the Service Principal Name In the Web Service Client at Design Time

Configure the Web Service to Use the Right KDC

 

Use the Correct Keytab File in Enterprise Manager

 

Extract and Export the Keytab File

 

Modify the krb5 Login Module to use the Keytab File

 

Authenticate the User Corresponding to the Service Principal

 

Create a Ticket Cache for the Web Service Client

 

Use Active Directory with Kerberos and Message Protection

 
 

Set Up the Web Service Client

Create a User Account

 

Create a Keytab File

 
 

Set the Service Principal Name

Set Up the Web Service

 

33.7 Managing and Migrating Security Token Service Policies

This section provides the following topics:

33.7.1 About Managing and Migrating Security Token Service Policies

Security Token Service policies for endpoints reside in sts-policies.jar. This jar is copied to following location under $WLS_HOME ($Oracle_IDM1, for example):

$WLS_HOME/oam/server/policy

The sts-policies.jar contains the stspolicies.prop file at the following location in the JAR:

META-INF/policies/sts/

This file lists all the policies packaged in the directory as file names to allow the server to read the JAR entries programmatically when migrating policies to destination repository.

Note:

Be sure to update policies and stspolicies.prop as needed before migration.

33.7.2 Managing Security Token Service Policies

The following procedure outlines the various scenarios for policy updates.

Task overview: Updating policies and stspolicies.prop

  1. Add a Policy to sts-policies jar: Before creating the new jar, you must also update the stspolicies.prop file at META-INF/policies/sts/ to include this new policy file name.

  2. Delete a Policy from sts-policies jar: You must also delete the entry from file META-INF/policies/sts/stspolicies.prop.

  3. Update Existing Policy File Name: When re-naming a policy file at META-INF/policies/sts/, you must also update the corresponding entry in the file META-INF/policies/sts/stspolicies.prop file.

  4. Update Existing Policy Content: When updating the content of a policy file, without touching the file name, there is no need to do anything else.

33.7.3 Migrating Security Token Service Policies

During installation a check is performed to establish whether SOA is deployed within the domain where Security Token Service is being installed:

  • If SOA is not installed, the Oracle WSM protocol is set to classpath and policies are read from the JAR on the class path.

  • If SOA is present within the domain, Security Token Service reads the policies from sts-policies.jar and migrates them to the Oracle WSM PM repository by calling Oracle WSM Mbeans.

  • If SOA is installed after Security Token Service within the same domain, ensure smooth operations between SOA and Security Token Service as follows:

    • The Oracle WSM protocol must be set to 'remote'.

    • Security Token Service policies from sts-policies jar must be migrated to Oracle WSM PM repository using Oracle WSM provided tools.

33.8 Introduction to Logging Security Token Service Messages

Logging is the mechanism by which components write messages to a file. Administrators can use the logging mechanism to capture critical component events. Access Manager uses the same logging infrastructure and guidelines as any other component in Oracle Fusion Middleware 11g. This is accomplished by using the package java.util.logging, which is standard and available in all Java environments. The logging system writes output to flat files only. Logging to an Oracle Database instance is not supported.

Configuring logging and locating log files are the focus of this section. Diagnosing problems using the information in log files is outside the scope of this manual.

Log messages are used for problem diagnosis. The logging infrastructure records messages from Access Manager. The Administrator controls the amount of information that is logged in a message by specifying log levels for each component or service for which a logger is defined.

Note:

Generally, you enable logging to produce files that you send to Oracle Technical Support for problem diagnosis. Documentation for log messages is not available. In some cases, you might be able to diagnose problems on your own by reading log files.

By default, the log level for Access Manager is the Notification level. Logging at the Error level produces a small amount of output while other log levels can result in voluminous logging output, which can impact OAM performance. In production environments, logging is usually either disabled or the log level is set to a level that results in a small volume of logging output (the error level, for example).

Access Manager and Security Token Service uses the WebLogic container's logging defaults:

  • Logging File: $DOMAIN_HOME/servers/SERVER-NAME/logs/SERVER-NAME-diagnostics.log

  • Logging Configuration File: Provides logging level and other configuration information for logging. This file is stored in the following path: $DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml

33.9 Introduction to Auditing for Security Token Service

Oracle Fusion Middleware auditing provides a measure of accountability and answers to the "who has done what and when" types of questions. Audit data can be used to create dashboards, compile historical data, and assess risks. Analyzing recorded audit data allows compliance officers to perform periodic reviews of compliance policies.

This section introduces the Security Token Service administrative and run-time events that can be audited. Configuring common auditing settings for Security Token Service and validating your auditing configuration is a subject of this chapter. However, analyzing and using audit data is outside the scope of this book.

The Oracle Fusion Middleware Common Audit Framework supports auditing for a number of run-time events, and administrative events (changes to the system). The Oracle Fusion Middleware Common Audit Framework provides uniform logging and exception handling and diagnostics for all audit events.

While auditing can be enabled or disabled, it is normally enabled in production environments. Auditing has minimal performance impact, and the information captured by auditing can be useful (even mission-critical).

Auditing is based on configuration parameters set in the Oracle Access Management Console that enable data capture for a user or set of users.

Audit data can be written to either a single, centralized Oracle Database instance or to flat files. Regardless of where the audit record is stored, it contains a sequence of items that can be configured to meet particular requirements. The audit log file helps the audit Administrator track errors and diagnose problems if the audit framework is not working properly.

Security Token Service integrates with Oracle Business Intelligence Publisher, which provides a pre-defined set of compliance reports.

33.9.1 About Security Token Service Audit Record Storage

Security Token Service can be configured to write audit records to a variety of targets supported by the Common Audit Framework:

  • Local flat files: By default, Security Token Service records audit data to a file.

  • Central database: In production environments, Oracle recommends using a database audit store to provide scalability and high-availability for the Common Audit Framework. Audit data is cumulative and grows over time. Ideally this is a database for only audit data; not used by other applications.

  • Platform-specific log (Linux Syslog and Windows Event Log)

  • Audit Vault

To switch to a database as the permanent store for your audit records, you must first use the Repository Creation Utility (RCU) to create a database schema for audit data. The RCU seeds that database store with the schema required to store audit records in a database. After the schema is created, configuring a database audit store involves:

  • Creating a data source that points to the audit schema you created

  • Configuring the audit store to point to the data source

33.9.2 About Audit Reports and Oracle Business Intelligence Publisher

The data in the database audit store is exposed through pre-defined reports in Oracle Business Intelligence Publisher. These reports allow you to drill down the audit data based on various criteria, such as user name, time range, application type, and execution context identifier (ECID).

Out-of-the-box, there are several sample audit reports available with Security Token Service and accessible with Oracle Business Intelligence Publisher. You can also use Oracle Business Intelligence Publisher to create your own custom audit reports.

33.9.3 About the Audit Log

An audit log file helps the audit Administrator track errors and diagnose problems when the audit framework is not working properly. An audit log file records several fields including: Date, Time, Initiator, EventType, EventStatus, MessageText, ECID, RID ContextFields, SessionId, TargetComponentType, ApplicationName, and EventCategory to name a few.

See Also:

The topic on audit logs in the chapter on configuring and managing auditing in the Oracle Fusion Middleware Security Guide

33.9.4 About Auditing Security Token Service Events

Specific administrative and run-time events that you can audit for Security Token Service are grouped together in Chapter 8, "Auditing Administrative and Run-time Events". Included with the events are the common instructions for setting up and validating auditing. For details, see: