Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Access Management
11g Release 2 (11.1.2)

Part Number E27239-03
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

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

33 Managing Security Token Service Certificates and Keys

This chapter provides the following sections:

33.1 Prerequisites

Security Token Service services must be running, as described in "Enabling and Disabling Security Token Service".

33.2 Introduction to Certificates and Keys for Security Token Service

This section describes certificates and keys used for 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 Security Token Service (with OWSM Agent). See also Table 33-1.

Table 33-1 Security Token Service Public Keys Used at Run Time

When Security Token Service ... Description

Issues SAML Assertions

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

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

  • 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

  • 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

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

Validates SAML Assertions

  • 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 Security Token Service (with OWSM Agent)


33.2.1 About Keystores and Security Token Service

Following is a brief summary of several types of keystores for Security Token Service:

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

Table 33-2 Keystores for Access Manager and Security Token Service

Keystore Description

System Keystore

.oamkeystore

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

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

$DOMAIN_HOME/config/fmwconfig/.oamkeystore

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

Trust Keystore

amtrustkeystore

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. 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 OAM 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 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 Management Console, as described in "Managing Certificate Revocation Lists (CLRs)".


The files in Table 33-3, are distributed across all OAM 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 33-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 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 "Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password".

33.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 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 Security Token Service keystore always be different. Otherwise, keys could be available to any modules authorized by OPSS to access the keystore and Access Manager keys might be accessed.

Note:

Oracle strongly recommends that the Oracle WSM Agent keystore and the Security Token Service 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

33.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 Security Token Service".

33.3 Managing Security Token Service Encryption/Signing Keys

Security Token Service uses keys to:

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

DOMAIN_HOME/config/fmwconfig/.oamkeystore

Task overview: Managing Security Token Service Keys

  1. Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password

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

  3. Extracting an Security Token Service Certificate

33.3.1 Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password

Use the following procedure to reset the password that protects keystores, and the key entries that are using the same password as the keystore.

These keystores were created and configured during installation, as described in the Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management. The password and key entries password were randomly generated.

The WLST resetKeystorePassword method allows the Administrator to set the .oamkeystore password and any key entries with a password identical to the .oamkeystore password to a new value:

  • Updates the .oamkeystore password

  • Updates the key entries in .oamkeystore that had the same password as the keystore

  • Updates Access Manager, Identity Federation, and Security Token Service configuration to reflect the changes

  • Updates the amtruststore password (if the keystore is protected by the same password as the default .oamkeystore)

To reset system and trust keystore passwords

  1. Enter the WSLT scripting environment, as usual.

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

  3. Navigate to the domain runtime tree: domainRuntime().

  4. Execute the following: resetKeystorePassword()

  5. Enter and confirm the password.

33.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 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:

33.3.2.1 Adding a New Entry

Prerequisites

Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password

To configure a new entry

  1. Locate keytool.

  2. Either generate a self signed certificate or generate a certificate request, export the request to a remote Certificate Authority, and import the certificate issued by the Certificate Authority.

  3. Observe messages on the screen.

  4. Proceed as needed:

33.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 Management 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.

33.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 Management 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".

33.3.3 Extracting an Security Token Service Certificate

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

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

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

To distribute the certificate of a key entry used by 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 Service, Security Token Service Settings and the preferred encoding (der vs pem). For more information, see "Using the Certificate Retrieval Service".

33.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 Management Console System Configuration tab, Security Token Service 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.

33.4 Managing Partner Keys for WS-Trust Communications

This topic provides the following information:

33.4.1 About Partner Certificates

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

Table 33-4 Partner Keys for WS-Trust Communications

If Security Token Service Must ... The OAM 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 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 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.


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

At runtime, Security Token Service is capable of downloading the Relying Party WSS Policy of the service listed in the AppliesTo field of the RST. If 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 Security Token Service can connect to the Relying Party.

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

  • If 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 Security Token Service issues a SAML Assertion with the Subject Confirmation of type Holder of Key / Symmetric, 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".

33.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 33-4, "Partner Keys for WS-Trust Communications"

To set the certificate of a partner

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

  2. Within the Partners node, expand Requester (or Relying Party or IssuingAuthority (see Table 33-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".

33.5 Managing Certificate Validation

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

Table 33-5 Conditions for Security Token Service Certificate Validation

STS 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

Security Token Service is configured to validate the signing certificate of a SAML Issuing Authority


Successful validation requirements are listed in Table 33-6.

Table 33-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:

33.5.1 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

Resetting System Keystore (.oamkeystore) and Trust Keystore (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".

33.5.2 Managing Certificate Revocation Lists

Security Token Service uses 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 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 Management Console System Configuration tab, Common Configuration section, select Certificate Validation.

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

  3. See "Enabling Certificate Validation":

  4. See "Configuring CRL Distribution Point Extensions (CDP)".

33.5.3 Using a Custom Trust Anchor Store for Security Token Service

Optionally, if a particular deployment requires a set of trust anchors separate from that of Access Manager, another keystore can be configured as the trusted certificate store for 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 Management 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 Security Token Service is deployed, the Custom Trust Anchor Keystore must be propagated manually by the Administrator across all the servers.