Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service
11g Release 1 (11.1.1)

Part Number E15478-07
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

19 Managing Oracle Security Token Service Certificates and Keys

This chapter provides the following sections:

19.1 Prerequisites

Both the Oracle Access Manager and Oracle Security Token Service services must be running, as described in "Enabling and Disabling Oracle Security Token Service".

19.2 Introduction to Certificates and Keys for Oracle Security Token Service

This section describes certificates and keys used for Oracle Security Token Service.

Depending on the public key infrastructure, the digital certificate establishes credentials for Web-based transactions, as described in "About Certificates, Authorities, and Encryption Keys".

Public Keys at Run Time: There are distinct cases where public key infrastructure materials are used at run time. For instance, during Web Services Security (WSS) protocol communication between Requesters and Oracle Security Token Service (with OWSM Agent). See also Table 19-1.

Table 19-1 OSTS Public Keys Used at Run Time

When Oracle Security Token Service ... Description

Issues SAML Assertions

  • Oracle Security Token Service Signing Assertions using a key defined in the STS Global settings

  • Oracle Security Token Service using the Requester's signing certificate as a proof key for Holder-of-Key of type Public Key confirmation method

  • Oracle Security Token Service using the Relying Party's encryption certificate to encrypt the secret proof key for Holder-of-Key of type Secret Key confirmation method

  • Oracle Security Token Service using the Requester's encryption certificate to encrypt a secret proof/entry in the RSTR for Holder-of-Key of type Secret Key confirmation method

Issues tokens

  • Oracle Security Token Service uses the Relying Party's encryption certificate to encrypt the outgoing token

Validates SAML Assertions

  • Oracle Security Token Service uses the Issuing Authority's signing certificate to verify the signature of the incoming SAML Assertion

Uses Web Services Security (WSS) protocol communication

Between Requesters and Oracle Security Token Service (with OWSM Agent)


19.2.1 About Keystores and Oracle Security Token Service

Following is a brief summary of several types of keystores for Oracle Access Manager with Oracle Security Token Service:

Table 19-2 describes these in greater detail. Additional details follow the table.

Table 19-2 Keystores for Oracle Access Manager with Oracle Security Token Service

Keystore Description

System Keystore

The container for keys and certificates associated with OAM Server instances (OAM secret keys and Oracle Security Token Service private keys for signing and encryption).

Only one System Keystore of type JCEKS may be present: .oamkeystore.

$DOMAIN_HOME/config/fmwconfig/.oamkeystore

The certificate alias and password can be configured using the Oracle Access Manager Console, as described in Table 18-2, "Security Token Service Settings".

Trust Keystore

The Trust Keystore is used to validate certificates presented by clients.

$DOMAIN_HOME/config/fmwconfig/amtruststore

amtruststore is created during installation, and must include at least one trusted anchor.

The Trust Keystore is managed by using the JRE's keytool application. Oracle Security Token Service can use a custom trust keystore.

Certificate Revocation Lists (CRL)

Certificate revocation information lists are stored in a ZIP archive on the filesystem. These are used by the Oracle Access Manager/Oracle Security Token Service server instances when performing CRL-based certificate revocation checking. amcrl.jar contains CRL files in the DER format:

$DOMAIN_HOME/config/fmwconfig/amcrl.jar

The OAM Server defines a notification listener for the Keystores and the CRL Zip file. Any changes to these files causes Oracle Access Manager with Oracle Security Token Service to reload the keystore/crl-zip at runtime, without requiring any restarts.

amcrl.jar is created by installation and can be modified using the Oracle Access Manager Console, as described in "Managing Certificate Revocation Lists (CLRs)".


The files in Table 19-3, are distributed across all Managed Servers in the domain by the JMX framework. The $DOMAIN_HOME/config/fmwconfig /mbeans directory defines a registration mbeans.xml for each file that indicates the MBean to manage the file and also identify that the file should be propagated across the domain.

Table 19-3 Keystore Mbeans

Keystore Mbean and Description

System Keystore: .oamkeystore

Configuration of the .oamkeystore is done using the JRE's keytool application.

Trust Keystore: .amtruststore

Configuration of the amtruststore is done using the JRE's keytool application.

CRL: amcrl.jar

CRL MBean: Can be used to manage CRLs.


The token security key pair is populated to the common keystore shared by Oracle Access Manager and Oracle Security Token Service. This eliminates the need for Oracle Web Services Manager agents to interact with the common keystore.

You can use a WLST command to retrieve the password for keystores and for the amtruststore, as described in "Retrieving the System Keystore (.oamkeystore) Password".

19.2.2 About the Oracle Web Services Manager Keystore (default-keystore.jks)

This topic describes the keystore of type JKS required by the Oracle WSM Agent to contain System and Partner keys and certificates.

Oracle WSM Agent functionality is available to Oracle Security Token Service to publish WS Policies and enforce message protection on inbound and outbound WS messages. Oracle WSM requires a separate keystore to contain System and Partner keys and certificates.

The Oracle WSM Agent uses a keystore for various cryptographic operations. For these tasks, the Oracle Web Services Manager Agent uses the keystore configured for Oracle Web Services Manager tasks (containing OWSM private keys and OWSM trusted certificates). The OPSS modules publish a keystore service used by Oracle Web Services Manager for certificate validation operations, and the $DOMAIN_HOME/config/fmwconfig/jps-config.xml will contain the settings for the keystore service. The default name is default-keystore.jks, which is specified in jps-config.xml.

Oracle strongly recommends that the Oracle WSM Agent keystore and the Oracle Access Manager and the Oracle Security Token Service keystore always be different. Otherwise, keys could be available to any modules authorized by OPSS to access the keystore and Oracle Access Manager keys might be accessed.

Note:

Oracle strongly recommends that the Oracle WSM Agent keystore and the OAM/OSTS keystore always be different.

During installation, if the Oracle WSM keystore service has not been configured, the installer:

  • creates a new keystore in the $DOMAIN_HOME/config/fmwconfig folder (default name is default-keystore.jks)

  • creates a key entry with the corresponding certificate that will be used by OWSM for signature and encryption operations. This key entry will be stored in the OWSM Keystore under the orakey alias

  • stores the passwords of the key entry and of the keystore in CSF

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

19.2.3 About Using the OPSS Keystore for Requester Certificates

For the special cases where clients use referencing schemes such as SKI etc (as opposed to certificate token being received as part of the web service request), the requester's certificates need to be populated in the OPSS Keystore. This is an uncommon scenario that requires manually provisioning keys to the OPSS keystore

For more information on this, see "About Agents and Oracle Security Token Service".

19.3 Managing Oracle Security Token Service Encryption/Signing Keys

Oracle Security Token Service uses keys to:

Oracle Security Token Service uses the following keystore for storing Encryption and Signing Certificates.

DOMAIN_HOME/config/fmwconfig/.oamkeystore

Task overview: Managing Oracle Security Token Service Keys

  1. Retrieving the System Keystore (.oamkeystore) Password

  2. Adding a New Key Entry to the System Keystore (.oamkeystore)

  3. Extracting an Oracle Security Token Service Certificate

19.3.1 Retrieving the System Keystore (.oamkeystore) Password

The following procedure can be used to display the password that protects the keystore as well as the key entry.

If the keystore was created and configured by the IM/OAM/OSTS installer, then the keystore password and the key entry password will need to be retrieved from CSF. Otherwise, the administrator cannot change the keystore or key entry.

To retrieve the system keystore (.oamkeystore) 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.

19.3.2 Adding a New Key Entry to the System Keystore (.oamkeystore)

An administrator can use the following procedure to add a new key entry into the System keystore(.oamkeystore) using the keytool command to create and add the new key entry. Once the entry has been added, it must be defined in the Oracle Security Token Service configuration screen so that it can be used to sign assertions and decrypt incoming messages.

This topic provides the following procedures to add a new entry to sign SAML Assertions or decrypt XML-Encrypted data not covered by WSS:

19.3.2.1 Adding a New Entry

Prerequisites

Retrieving the System Keystore (.oamkeystore) Password

To configure a new entry

  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.

  4. Proceed as needed:

19.3.2.2 Configuring a SAML Issuance Template to use a Signing Key

Users with valid Administrator credentials can use this procedure as a guide when editing an existing template to use a signing key.

To configure a SAML Issuance Template to use a signing key

  1. Display the list of existing Token Issuance Templates.


    Oracle Access Manager Console
    System Configuration
    Security Token Services
    Token Issuance Templates
  2. Find and open the SAML issuance template that will use the new key. For example: saml11-issuance-template.

  3. On the SAML Issuance Template page, click the Security tab.

  4. On the Security tab, Signing And Encryption section, click Sign Assertion.

  5. From the Signing Keystore Access Template Id list, choose the KeyID as the Signing Keystore Entry.

  6. Click Apply at the top of the page to save this information.

  7. Proceed to "Setting the Default Encryption Key", if needed.

19.3.2.3 Setting the Default Encryption Key

Users with valid Administrator credentials can use this procedure as a guide when editing an existing template to use a signing key.

To set the default encryption key

  1. Go to the Security Token Service Settings page.


    Oracle Access Manager Console
    System Configuration
    Security Token Service
    Security Token Service Settings
  2. From the Default Encryption Template list, select the new key entry.

  3. Click Apply at the top of the page to save this information.

  4. Proceed to "Setting the Default Encryption Key".

19.3.3 Extracting an Oracle Security Token Service Certificate

In some cases, it is required to distribute the Oracle Security Token Service keys used for SAML Signature operations or XML encryption operations:

  • When a Relying Party needs to have access to the Oracle Security Token Service signing key, in order to validate the SAML Assertion issued by Oracle Security Token Service

  • When a token needs to be encrypted for Oracle Security Token Service Server

To distribute the certificate of a key entry used by Oracle Security Token Service for SAML Signature operations or XML encryption operations, use the Certificate Retrieval Service by specifying the KeyID (listed in System Configuration > Security Token Services > Security Token Service Settings section) and the preferred encoding (der vs pem). For more information, see "Using the Certificate Retrieval Service".

19.3.3.1 Using the Certificate Retrieval Service

To use the Certificate Retrieval service

  1. Retrieve the KeyID of the entry for which the certificate should be retrieved (listed in Oracle Access Manager Console System Configuration tab, Security Token Services section, Security Token Service Settings).

  2. Create a URL. For example: http(s)://osts-hostname:osts-port/sts/servlet/samlcert?id=<KEYID>&encoding=<ENCODING>, with:

    • id holding the KeyID of the entry

    • encoding representing the format with which the certificate will be returned. Possible values are pem (PEM format) or der (DER format). (optional, default value is pem)

  3. Review the certificate returned in the browser.

19.4 Managing Partner Keys for WS-Trust Communications

This topic provides the following information:

19.4.1 About Partner Certificates

During the processing of the WS-Trust messages, Oracle Security Token Service might need to use a partner's certificate. The certificate needed depends on the situation, as described in Table 19-4.

Table 19-4 Partner Keys for WS-Trust Communications

If the OSTS Server Must Issue a ... The Server ...

Issue a SAML Assertion encrypted for the Relying Party

Uses the Relying Party's encryption certificate to encrypt the outgoing token

Issue a SAML Assertion with the Subject Confirmation being of type Holder of Key / Asymmetric

Uses the Requester Partner's signing certificate as the proof key to be included in the Assertion

Note: if the WS-Trust RST contains a UseKey element referencing an X.509 Binary Security Token in the SOAP header that was used in a signature, then Oracle Security Token Service will be able to use this certificate as the proof key.

Issue a SAML Assertion with the Subject Confirmation being of type Holder of Key / Symmetric

Uses the Relying Party's encryption certificate to encrypt the secret proof key to be included in the Assertion.

Issue a SAML Assertion with the Subject Confirmation being of type Holder of Key / Symmetric

Can encrypt in the RSTR for the Requester, the secret or the server entropy.

In this case, the server:

  • uses the Requester's encryption certificate to encrypt the secret (if the secret was generated using only server entropy)

  • or uses the server entropy to encrypt the secret in the RSTR (if the secret was derived from client and server entropy).

Note: if the WS-Trust RST contains a ProofEncryption element referencing an X.509 Binary Security Token in the SOAP header that was used in a signature, then Oracle Security Token Service will be able to use this certificate to encrypt the secret or entropy returned to the client.

Validate an incoming SAML Assertion

Uses the Issuing Authority's signing certificate to verify the XML digital signature present on the Assertion.


19.4.2 About Downloading the Relying Party's Certificate at Run Time

At runtime, Oracle Security Token Service is capable of downloading the Relying Party WSS Policy of the service listed in the AppliesTo field of the RST. If Oracle Security Token Service is configured to download the Relying Party's WS-Sec policy, then ensure that the Proxy settings are correctly entered, if needed, so that Oracle Security Token Service can connect to the Relying Party.

If the Relying Party Partner Profile is configured to do so, it instructs Oracle Security Token Service to download the WS-Sec Policy from the service. Oracle Security Token Service then extracts the certificate located in the policy and uses it for cryptographic operations, if necessary. Also:

  • If Oracle Security Token Service issues a SAML Assertion encrypted for the Relying Party, the server uses the certificate downloaded from the Relying Party's WS-Sec Policy to encrypt the outgoing token.

  • If Oracle Security Token Service issues a SAML Assertion with the Subject Confirmation of type Holder of Key / Symmetric, Oracle Security Token Service uses the certificate downloaded from the Relying Party's WS-Sec Policy to encrypt the secret proof key to be included in the Assertion.

To configure the Relying Party Partner Profile to download the certificate at run time, see "Setting the Partner's Signing or Encryption Certificate".

19.4.3 Setting the Partner's Signing or Encryption Certificate

To set the signing or encryption certificate of a partner, perform the following operations.

Alternatively: Use the WLST Partner commands to set the signing or encryption certificate of a specific partner.

Prerequisites

Review Table 19-4, "Partner Keys for WS-Trust Communications"

To set the certificate of a partner

  1. From the Oracle Access Manager Console System Configuration, tab, Security Token Services section, and expand the Partners node.

  2. Within the Partners node, expand Requester (or Relying Party or IssuingAuthority (see Table 19-4)).

  3. Search for and open (or Create) the Partner for which the certificate must be set.

  4. Edit Partner settings as needed (see "Managing Token Service Partners") and click Save.

  5. Encryption Certificate: Click the Browse button to locate and choose the Encryption certificate.

  6. Signing Certificate: Click the Browse button to locate and choose the Signing certificate.

  7. Save the information and close the page.

  8. Proceed with "Managing Certificate Validation".

19.5 Managing Certificate Validation

This section describes managing certificate validation. Conditions for certificate validation are described in Table 19-5.

Table 19-5 Conditions for Oracle Security Token Service Certificate Validation

OSTS Validates a Certificate When ...

The security token to be validated is one of the following types:

  • X.509

  • X.509v3

  • PKCS#7

A SAML Assertion must be validated

OSTS is configured to validate the signing certificate of a SAML Issuing Authority


Successful validation requirements are listed in Table 19-6.

Table 19-6 Successful Certificate Validation Requirements

Certificates Must ... How ...

Be linked to a trusted anchor:

  • by being a trusted anchor

  • or by having its issuer being a trusted anchor

Not be revoked:

  • by being a trusted anchor

  • or by having its issuer being a trusted anchor

The revocation status of a certificate can be decided by checking:

  • Against a list of CRLs that were uploaded by the administrator

  • Against an OCSP server

  • CRL Distribution Points


Certificate validation requires the Trust Anchors Store (.amtruststore). Procedures for managing this store and validation are described in following topics:

19.5.1 Retrieving the Trust Anchors Store (amtruststore) Password

The Trust Anchors keystore password must be retrieved from CSF. Otherwise administrators cannot change the keystore. The store is located in:

$DOMAIN_HOME/config/fmwconfig/amtruststore

To retrieve the password of the, perform the following operations, which will display the password used to protect the Trust Anchors Keystore.

  • Enter the WSLT scripting environment

  • Execute the following command, by providing the connection information to the WLS Admin Server: listCred(map="OAM_STORE", key="jks")

To retrieve the Trust Anchors store 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. Observe messages on the screen and note the password.

  5. Proceed to "Managing the Trust Anchors Store (amtruststore)".

19.5.2 Managing the Trust Anchors Store (amtruststore)

The Trust Anchors keystore is managed using the keytool command. Certificates added to the keystore are detected by the Certificate Validation module.

Note:

Notification is performed using the JMX Notification Framework and might take some time, depending on the notification refreshing time (60 seconds by default).

Prerequisites

Retrieving the Trust Anchors Store (amtruststore) Password

To manage the Trust Anchors store (amtruststore)

  1. Locate keytool.

  2. Execute the following command.

    keytool -keystore $DOMAIN_HOME/config/fmwconfig/amtruststore 
    -storetype JKS -alias orakey -file $CERT_FILE 
    
  3. Observe messages on the screen and enter a password if requested.

  4. Proceed to "Managing Certificate Revocation Lists".

19.5.3 Managing Certificate Revocation Lists

Oracle Security Token Service and Oracle Access Manager use the common infrastructure certification validation module. Trusted Certificates and Certificate Revocation Lists (CRLs) used during certificate validation are stored in Trust Keystore and CRL ZIP file. The Oracle Security Token Service configuration stores the OCSP/CDP settings.

This section outlines how to add or remove certificate revocation lists (CLRs) to check the revocation status of a certificate, perform the following operations.

Prerequisites

Have your Certificate Revocation List ready to import.

Task overview: Manage Certificate Validation and Revocation Lists

  1. From the Oracle Access Manager Console System Configuration tab, Common Configuration section, select Certificate Validation.

  2. See "Managing Certificate Revocation Lists (CLRs)".

  3. See "Managing Certificate Validation":

  4. See "Configuring CDP".

19.5.4 Using a Custom Trust Anchor Store for Oracle Security Token Service

Optionally, if a particular deployment requires a set of trust anchors separate from that of Oracle Access Manager, another keystore can be configured as the trusted certificate store for Oracle Security Token Service. This can be done by having the administrator perform the following tasks.

Note:

Using a Custom Trust Anchor Store is an optional feature that most customers will not need.

Task overview: Deploying a custom keystore for trusted certificates

  1. Create the JKS keystore in the $DOMAIN_HOME/config/fmwconfig directory.

  2. In the Oracle Access Manager Console, Security Token Service Settings page, enter the full path name of the new trust store and Apply your changes.

  3. In the domain where Oracle Access Manager with Oracle Security Token Service is deployed, the Custom Trust Anchor Keystore must be propagated manually by the administrator across all the servers.