This chapter provides the following sections:
Security Token Service services must be running, as described in "Enabling and Disabling 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 37-1.
Table 37-1 Security Token Service Public Keys Used at Run Time
| When Security Token Service ... | Description |
|---|---|
|
Issues SAML Assertions |
|
|
Issues tokens |
|
|
Validates SAML Assertions |
|
|
Uses Web Services Security (WSS) protocol communication |
Between Requesters and Security Token Service (with OWSM Agent) |
Following is a brief summary of the keystore files distributed across all OAM Servers in the domain by the JMX framework and used for Security Token Service:
.oamkeystore: For keys and certificates associated with OAM Server instances
.oamkeystore: Partner Keystore for keys and certificates used to establish trust with partners, clients, and agents.
amtruststore: Trust Keystore for keys and certificates that are used to establish trust in entities that are interacting with the OAM Server instances
amcrl.jar: Certificate Revocation Lists (CRL) are used by the OAM Server instances when performing CRL-based certificate revocation checking
The files in Table 37-2, 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.
| Keystore | Mbean and Description |
|---|---|
|
System/Partner 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".
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
For the special cases where clients use referencing schemes such as SKI (as opposed to a 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".
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
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
Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password
Adding a New Key Entry to the System Keystore (.oamkeystore)
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
Enter the WSLT scripting environment, as usual.
Connect to the WebLogic Server AdminServer, using the connect() command.
Navigate to the domain runtime tree: domainRuntime().
Execute the following: resetKeystorePassword()
Enter and confirm 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 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:
Resetting System Keystore (.oamkeystore) and Trust Keystore (amtruststore) Password
Locate keytool.
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.
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:
"About Security Token Service Settings"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 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".
To use the Certificate Retrieval service
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).
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, Security Token Service might need to use a partner's certificate. The certificate needed depends on the situation, as described in Table 37-3.
Table 37-3 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:
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. |
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".
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 37-3, "Partner Keys for WS-Trust Communications"
To set the certificate of a partner
From the Oracle Access Management Console System Configuration, tab, Security Token Service section, and expand the Partners node.
Within the Partners node, expand Requester (or Relying Party or IssuingAuthority (see Table 37-3)).
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 37-4.
Table 37-4 Conditions for Security Token Service Certificate Validation
| STS Validates a Certificate When ... |
|---|
|
The security token to be validated is one of the following types:
|
|
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 37-5.
Table 37-5 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 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).Resetting System Keystore (.oamkeystore) and Trust Keystore (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".
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.
Have your Certificate Revocation List ready to import.
Task overview: Manage Certificate Validation and Revocation Lists
From the Oracle Access Management Console System Configuration tab, Common Configuration section, select Certificate Validation.
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
Create the JKS keystore in the $DOMAIN_HOME/config/fmwconfig directory.
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.
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.