This chapter provides the following sections:
Introduction to Certificates and Keys for Oracle Security Token Service
Managing Oracle Security Token Service Encryption/Signing Keys
Both the Oracle Access Manager and Oracle Security Token Service services must be running, as described in "Enabling and Disabling 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 |
|
|
Issues tokens |
|
|
Validates SAML Assertions |
|
|
Uses Web Services Security (WSS) protocol communication |
Between Requesters and Oracle Security Token Service (with OWSM Agent) |
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. $ 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. $ 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.
| 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".
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
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".
Oracle Security Token Service uses keys to:
Sign outgoing Assertions
Decrypt any incoming XML encrypted data contained inside the RST message (tokens, entropies...), which is not handled by the WSS Protocol
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
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
Enter the WSLT scripting environment.
Connect to the WebLogic Server AdminServer, using the connect() command.
Execute the following command by providing the connection information to the AdminServer: listCred(map="OAM_STORE", key="jks").
Note the password.
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:
Retrieving the System Keystore (.oamkeystore) Password
Locate keytool.
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
Observe messages on the screen.
Proceed as needed:
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
Display the list of existing Token Issuance Templates.
Find and open the SAML issuance template that will use the new key. For example: saml11-issuance-template.
On the SAML Issuance Template page, click the Security tab.
On the Security tab, Signing And Encryption section, click Sign Assertion.
From the Signing Keystore Access Template Id list, choose the KeyID as the Signing Keystore Entry.
Click Apply at the top of the page to save this information.
Proceed to "Setting the Default Encryption Key", if needed.
Users with valid Administrator credentials can use this procedure as a guide when editing an existing template to use a signing key.
See Also:
To set the default encryption key
Go to the Security Token Service Settings page.
From the Default Encryption Template list, select the new key entry.
Click Apply at the top of the page to save this information.
Proceed to "Setting the Default Encryption Key".
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".
To use the Certificate Retrieval service
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).
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)
Review the certificate returned in the browser.
This topic provides the following information:
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:
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. |
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".
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.
Review Table 19-4, "Partner Keys for WS-Trust Communications"
To set the certificate of a partner
From the Oracle Access Manager Console System Configuration, tab, Security Token Services section, and expand the Partners node.
Within the Partners node, expand Requester (or Relying Party or IssuingAuthority (see Table 19-4)).
Search for and open (or Create) the Partner for which the certificate must be set.
Edit Partner settings as needed (see "Managing Token Service Partners") and click Save.
Encryption Certificate: Click the Browse button to locate and choose the Encryption certificate.
Signing Certificate: Click the Browse button to locate and choose the Signing certificate.
Save the information and close the page.
Proceed with "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:
|
|
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: |
|
|
Not be revoked:
|
The revocation status of a certificate can be decided by checking:
|
Certificate validation requires the Trust Anchors Store (.amtruststore). Procedures for managing this store and validation are described in following topics:
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
Enter the WSLT scripting environment.
Connect to the WebLogic Server AdminServer, using the connect() command.
Execute the following command by providing the connection information to the AdminServer: listCred(map="OAM_STORE", key="jks").
Observe messages on the screen and note the password.
Proceed to "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).
Retrieving the Trust Anchors Store (amtruststore) Password
To manage the Trust Anchors store (amtruststore)
Locate keytool.
Execute the following command.
keytool -keystore $DOMAIN_HOME/config/fmwconfig/amtruststore -storetype JKS -alias orakey -file $CERT_FILE
Observe messages on the screen and enter a password if requested.
Proceed to "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.
Have your Certificate Revocation List ready to import.
Task overview: Manage Certificate Validation and Revocation Lists
From the Oracle Access Manager Console System Configuration tab, Common Configuration section, select Certificate Validation.
See "Configuring CDP".
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
Create the JKS keystore in the $DOMAIN_HOME/config/fmwconfig directory.
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.
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.