Oracle® OpenSSO STS Administrator's Guide Release 11gR1. Version 11.1.1.3.0 Part Number E17844-01 |
|
|
View PDF |
This chapter provides instructions for determining your security token needs, and for configuring the Security Token Service to generate and validate security tokens to meet those needs.
The following topics are contained in this chapter:
Oracle OpenSSO Security Token Service (OpenSSO STS) establishes a trust relationship between a web service client and a web service provider, and then brokers the trust between them. The web service can trust tokens issued by just one entity—OpenSSO STS— instead of having to communicate with several clients. In this way, OpenSSO STS significantly reduces trustpoint management overhead.
An HTTP client, or browser, sends an access request through the web service client to the web service provider. A web services security agent redirects the request to the OpenSSO STS authentication service. A SOAP security agent issues the redirect.
The OpenSSO STS authentication service determines the security mechanism registered by the web service provider, and retrieves the appropriate security tokens. After successful authentication, the web service client provides a SOAP message body while the SOAP security agent on the web service client side inserts the security header and a token. The message is then signed before the request is sent to the WSP.
The SOAP security agent on the web service provider side verifies the signature and security token in the SOAP request before forwarding the request on to the web service provider itself. The web service provider then processes it and returns a response, signed by the SOAP security agent, back to the web service client. The SOAP security agent on the web service client side then verifies the signature before forwarding the response on to the web service client.
The OpenSSO Security Token Service issues and authenticates the following security tokens:
Inbound Tokens
UserName
X.509
Kerberos
Outbound Tokens
UserName
SAML 1.1 and SAML2.0
Holder-of-Key, Bearer, and Sender Vouches
Token Translation
Converts UserName to SAML.
Converts OpenSSO STS SSOToken to SAML 1.1 or SAML 2.0 token.
Converts SAML 1.1 to SAML 2.0 token, and SAML 2.0 to SAML1.1 token.
Converts OpenSSOToken to SAML Assertion.
Converts Oracle Access Manager SSOToken to SAML Assertion.
Supports custom token plugability.
Additionally, end user tokens can be converted or validated after customization. In this case, the new token is an OnBehalfOftoken
(a WS-Trust protocol element) carried in the WS-Trust request as part of the SOAP body. The new token becomes an authentication token carried as part of the SOAP header. Custom tokens can also be created and sent on behalf of an end user token for conversion or validation by the Security Token Service.
For detailed descriptions of security tokens, see the links to comprehensive Web Service Security specifications in Section 4.1.3, "Supported Standards."
Message-Level Security Bindings
Asymmetric, Symmetric, and Transport-Layer security bindings
WS-Security 1.0 and WS-Security 1.1 (for Kerberos)
For detailed descriptions of supported security tokens and security mechanisms, see the links to comprehensive Web Service Security specifications in Section 4.1.3, "Supported Standards."
OpenSSO STS supports the following industry standards for web services security:
Protocol for communicating requests and responses to the Security Token Service. See the following URLs for the comprehensive WS-Trust specification:
This specification describes the Web Services Trust Model and provides detailed information about security tokens and the Security Token Service Framework.
Standards that define processing rules for security when SOAP is used as a communication protocol for web services. See the following URL for the WS-Security specification:
http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf
XML-based language for expressing web service policy metadata through WSDL. See the following URL for the WS-Policy specification:
http://www.w3.org/TR/ws-policy/
This specification provides detailed information about the Policy Model and Policy Expression.
Security policy metadata expressed in WSDL. See the following URL for the comprehensive WS-Security Policy specification:
http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ws-securitypolicy-1.2-spec-os.html
This specification defines a set of security policy assertions for use with the WS-Policy framework. The specification includes detailed information about security token properties and assertions, security bindings, and SOAP message security options.
Any changes you make to the Security Token Service configuration are automatically and dynamically reflected in the OpenSSO STS WSDL. For example, if you want to disable a security mechanism, you can use the OpenSSO STS console to make the change once, and that change is propagated throughout the Security Token Service. You do not have to make additional manual changes or redeploy OpenSSO STS. You can inspect the corresponding WSDL to be sure that the change has been made appropriately. Go to the WSDL URL. Example:
http://
OpenSSOhost:OpenSSOport/deployURI/sts?wsdl
When you configure the Security Token Service, you specify how OpenSSO STS authenticates remote clients that request security tokens.
On the Configuration tab, click the Global subtab.
In the Global Properties list, click Security Token Service.
On the Security Token Service page, provide values for the Token Issuance Attributes, Security, Signing and Encryption, Key Store, Kerberos Configuration, and SAML Configuration attributes.
The following table provides a listing and descriptions of the attributes you can configure.
Table 4-1 Security Token Service Attributes
Attribute | Description |
---|---|
Token Issuance Attributes |
|
Issuer |
Specify the name of the Security Token service that issues the security tokens. |
End Point |
The OpenSSO STS end point that a client communicates with. Use the form:
If the OpenSSO STS is fronted by a load-balancer, then use the load balancer host name and port number. This syntax allows for dynamic substitution of the Security Token Service Endpoint URL based on the specific session parameters. |
SSL End Point |
The SSL-enabled OpenSSO STS end point that a client communicates with. Use the form:
If the OpenSSO STS is fronted by a load-balancer, then use the load balancer host name and port number. This syntax allows for dynamic substitution of the Security Token Service Endpoint URL based on the specific session parameters. |
Lifetime for Security Token |
Specify the number of milliseconds the issued token is valid. |
Certificate Alias Name |
Specify the alias name for the certificate or key used to sign the security token issued by the Security Token service. |
STS End User Token Plugin class |
Specify the implementation class for the end user token conversion. |
Security Mechanism |
Specify the type of security credential that is used to secure either the security token itself, or the security credential accepted by the Security Token service from the incoming WS-Trust request sent the by the client. Choose from the following security types:
|
Authentication Chain |
Choose the authentication chain or service name to be used to authenticate to the OpenSSO STS authentication service. OpenSSO STS uses the credentials from an incoming issuer request's security token to generate an OpenSSO STS-authenticated security token. |
Credential for User Token |
This attribute is not used when an authentication chain is configured. The list displays the username and password shared secrets to be used by the Security Token service to validate a UserName token. The UserName token is sent by the client as part of the incoming WS-Trust request.
|
On Behalf Of Token |
This attribute represents the WS-Trust protocol OnBehalfOf element. These elements are used for token translations. Choose one or more of the following: OpenSSO UserName UserName with Password SAML 1 SAML 2 Custom |
Authentication Chain for On Behalf Of Token |
Choose the authentication chain or service to be used to authenticate to the OpenSSO STS Authentication service. |
Detect Message Replay |
This attribute is used to detect message replays from a client in a malicious attack. When enabled, Yes is checkmarked and replay are automatically detected. |
Detect User Token Replay |
This attribute is used to detect message replays from a client in a malicious attack when the security mechanism is the Username token. When enabled, Yes is checkmarked, and |
Is Request Signature Verified |
When enabled, Yes is checkmarked, and the Security Token service must verify the signature of the incoming WS-Trust request. |
Disable signature validation when transport is secured with SSL |
When enabled, Yes is checkmarked, and OpenSSO STS does not verify the signature if the Transport Layer security binding is used. |
Is Response Signed Enabled |
When enabled, Yes is checkmarked. Specify the responses received by the Security Token Service that must be signed. Choose from the following: Body SecurityToken Timestamp To From ReplyTo Action MessageID |
Signing Reference Type |
Specify how to detect the security token used to sign the SOAP response.
For detailed information see |
Is Request Decrypted |
When enabled, Yes is checkmarked, OpenSSO STS decrypts the incoming request message. Body: When checkmarked, the body is decrypted. Header: When checkmarked, the header is decrypted. |
Disable decryption when transport is secured with SSL |
When enabled, Yes is checkmarked, and OpenSSO STS does not decrypt the incoming request message when transport layer security binding is used. |
Is Response Encrypted |
When enabled, Yes is checkmarked, and all responses sent by the Security Token service must be encrypted. |
Encryption Algorithm |
Choose the encryption algorithm used by the Security Token service to encrypt the WS-Trust response. Choose from the following:
Depending upon the encryption algorithm you use, choose the corresponding Encryption Strength (below). |
Encryption Strength |
Choose the encryption strength to be used by the Security Token service to encrypt the WS-Trust response. A high value corresponds to a high encryption strength level. Choose a value based on the algorithm specified in the Encryption Algorithm field.
|
Private Key Alias |
Specify the private certificate key alias to be used to sign the WS-Trust response or to decrypt the incoming WS-Trust request. |
Private Key Type |
Specify the certificate private key type to be used for signing WS-Trust responses or decrypting WS-Trust requests. Choose from the following: PublicKey, SymmetricKey, or NoProofKey.
|
Public Key Alias of Web Service (WS-Trust) Client |
Specify the public certificate key alias to be used to verify the signature of the incoming WS-Trust request or to encrypt the WS-Trust response. |
Kerberos Domain Server |
Specify the Kerberos Distribution Center (the domain controller) hostname. Use the fully qualified domain name of the domain controller. |
Kerberos Domain |
Specify the Kerberos Distribution Center (domain controller) domain name. Depending up on your configuration, the domain name of the domain controller may be different than the OpenSSO STS domain name. |
Kerberos Service Principal |
Specify the Kerberos principal designated as the owner of the generated Security token. Use the following format:
where hostname and domainame represent the host name and domain name of the OpenSSO STS instance, and dc_domain_name is the Kerberos domain in which the Windows Kerberos server (domain controller) resides. The Kerberos server may be different from the domain name of the OpenSSO STS instance. |
Kerberos Key Tab File |
Specify the Kerberos keytab file to be used for issuing the token. Use the following format, although the format is not required: hostname where hostname is the host name of the OpenSSO STS instance. |
Is Verify Kerberos Signature |
When enabled, Yes is checkmarked, and OpenSSO STS verifies the incoming request signature using the Kerberos token. This is optional and must be enabled only when JDK6 is used. |
SAML Attribute Mapping |
The Current Values list displays the SAML attribute that must be generated as an Attribute Statement when the Security Token Service creates a SAML assertion for a web service provider. Use the following format:
|
NameID Mapper |
Specify the SAML NameID Mapper to be used in an assertion that is generated for the Security Token service. |
Should Include Memberships |
When enabled, Yes is checkmarked, and the generated assertion contains user memberships as SAML attributes. |
Attribute Namespace |
Specify the SAML Attribute Namespace for an assertion that is generated for the Security Token service. |
Trusted Issuers |
The Current Values list displays trusted issuers that can be trusted to send security tokens to OpenSSO STS. OpenSSO STS must verify that a security token was sent from one of these issuers.
|
Trusted IP Addresses |
The Current Values list displays IP addresses that can be trusted to send security tokens to OpenSSO STS. OpenSSO STS must verify whether a security token was sent from one of these hosts.
|
Click Save.
The following summarizes the steps you take to use OpenSSO STS to generate security tokens:
Register a web service provider.
See Section 4.4, "To Register a Web Service Provider to OpenSSO STS.".
Configure the web service provider. See the following sections:
Use the Security Token Generation Matrix to help you configure OpenSSO STS to generate a web service client security token required by the web service provider.
Transport binding provides message protection only at the transport layer level.
Asymmetric binding uses public key cryptography to provide message protection at the SOAP message encoding layer.
Symmetric binding uses Kerberos tokens to provide message protection at the SOAP message encoding layer.
Username
See http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf
X.509
See http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-errata-os-x509TokenProfile.pdf
Kerberos
See http://www.oasis-open.org/committees/download.php/16788/wss-v1.1-spec-os-KerberosTokenProfile.pdf
WS-Security SAML tokens: Bearer, Sender-Vouches, and Holder-of-Key
WS-Trust RST keytype values: Symmetric, Public, and Bearer
Used when the requestor is obtaining a token on behalf of another party.
Used when the client supplies a public-key to be embedded in the issued token as the proof key.
Attributes to be included in the SOAP message.
For general information about Web Service Security and related terminology, see the following URLs:
The Security Token Generation Matrix summarizes frequently-used Security Token Service parameter settings and the types of security tokens OpenSSO STS generates based on these settings. An example follows the table.
Table 4-2 Security Token Generation Matrix
Row | Message-Level Security Binding | Web Service Client Token | KeyType | OnBehalfOf Token | Use Key | OpenSSO STS Output Token |
---|---|---|---|---|---|---|
1 |
Asymmetric |
X.509 |
Bearer |
Yes |
No |
SAML Bearer, no proof key |
2 |
Asymmetric |
Username |
Bearer |
Yes |
No |
SAML Bearer, no proof key |
3 |
Asymmetric |
X.509 |
Bearer |
No |
No |
SAML Bearer, no proof key |
4 |
Asymmetric |
Username |
Bearer |
No |
No |
SAML Bearer, no proof key |
5 |
Asymmetric |
X.509 |
Symmetric |
Yes |
No |
SAML Holder-of-Key, Symmetric proof key |
6 |
Asymmetric |
Username |
Symmetric |
Yes |
No |
SAML Holder-of-Key, Symmetric proof key |
7 |
Asymmetric |
X.509 |
Symmetric |
No |
No |
SAML Holder-of-Key, Symmetric proof key |
8 |
Asymmetric |
Username |
Symmetric |
No |
No |
SAML Holder-of-Key, Symmetric proof key |
9 |
Asymmetric |
X.509 |
Asymmetric |
No |
Web Service Client public key |
SAML Holder-of-Key, Asymmetric proof key |
10 |
Asymmetric |
X.509 |
Oracle-proprietary for SAML sender-vouches |
Yes |
No |
SAML sender-vouches, no proof key |
11 |
Asymmetric |
Username |
Oracle-proprietary for SAML sender-vouches |
Yes |
No |
SAML sender-vouches, no proof key |
12 |
Transport |
Username |
Bearer |
Yes |
No |
SAML Bearer, no proof key |
13 |
Transport |
Username |
Bearer |
No |
No |
SAML Bearer, no proof key |
14 |
Transport |
Username |
Symmetric |
Yes |
No |
SAML Holder-of-Key, Symmetric proof key |
15 |
Transport |
Username |
Symmetric |
No |
No |
SAML Holder-of-Key, Symmetric proof key |
16 |
Transport |
Username |
Oracle-proprietary for SAML sender-vouches |
Yes |
No |
SAML sender-vouches, no proof key |
17 |
Asymmetric |
X.509 |
Asymmetric |
No |
No |
SAML Holder-of-Key, Asymmetric proof key |
18 |
Asymmetric |
X.509 |
No |
No |
No |
SAML Holder-of-Key, Asymmetric proof key |
19 |
Asymmetric |
Username |
No |
No |
No |
SAML Holder-of-Key, Symmetric proof key |
20 |
Transport |
Username |
No |
No |
No |
SAML Holder-of-Key, Symmetric proof key |
In the last column titled OpenSSO STS Output Token, find a description that meets the web service provider token requirements. Then make note of the parameter values in the same row, and use those values when you configure the Web Service Provider profile.
For example, after installing OpenSSO STS, you may want to add a web service provider. You must gather some information before you can configure the Security Token Service to generate the required tokens. First, determine how a client should authenticate to OpenSSO STS: using X.509, Kerberos, or Username tokens. See Web Service Client Token. For this example choose X.509.
Next determine what type of security token the web service requires. You can inspect the web service provider security policy which defines the web service provider requirements. For example, the security policy may indicate that the web service provider will accept a SAML bearer token using Asymmetric binding.
Now you can use the OpenSSO STS console to add and register a web service provider, and import the web service provider certificate alias. Make note of the certificate alias name. For this example, use CertAliasTest.
This is where you read the Security Token Generation Matrix. Based on the information you've gathered so far, look in the last column of the matrix for SAML bearer token. Now exclude any rows that use Web Service Client Tokens other than X.509. Row 1 meets your needs so far, and you can use the remaining values in Row 1 as guidelines for configuring the web service provider, making adjustments as necessary.
Now you are ready to configure the web service provider. Following the instructions in Section 4.5, "To Configure a Web Service Provider," you can provide the following values:
Parameter | Value |
---|---|
Security Binding | Asymmetric |
Web Service Client Token | X.509 |
KeyType | Bearer |
Certificate Alias Name | CertAliasTest |
When you add a new web service provider security agent profile, the web service provider is automatically registered to OpenSSO STS.
On the Access Control tab, click the Agents subtab.
In the Agent section, click New.
In the New Agent page, provide the following information:
Property | Description |
---|---|
Name | Specify a name for the new web service provider. |
Password | Specify an administrator password for accessing the new web service. |
Re-Enter Password | Re-enter the password to confirm it. |
Click Create.
Once you've registered a web service provider to OpenSSO STS, you can configure the web service provider. See Section 4.5, "To Configure a Web Service Provider."
On the Access Control tab, click the Agents subtab.
In the Agent section, click name of the web service provider you want to configure.
Provide the following General, End Points, Key Store,Security, and SAML Configuration information:
Property | Description |
---|---|
General | |
Group | Select a group to which this web service provider belongs. |
End Points | |
Web Service End Point | This is the end point that the web service is listening to. Specify a URL for the service end point. |
Key Store | |
Public Key Alias | Specify the public key alias used for encrypting shared secrets or any other SAML assertion intended for the web service provider. |
Security | |
Security Mechanism | Choose one of the following: SAML-Bearer SAML-Holder-of-Key SAML-SenderVouches SAML2-Bearer SAML2-Holder-of-Key SAML2-SenderVouches See |
SAML Configuration | |
SAML Attribute Mapping | This configuration represents a SAML attribute that needs to be generated as an Attribute Statement during SAML assertion creation by the Security Token Service for a web service provider. The format is SAML_attr_name=Real_attr_name.
SAML_attr_name is the SAML attribute name from a SAML assertion from an incoming web service request. Real_attr_name is the attribute name that is fetched from either the authenticated SSOToken or the identity repository. |
SAML NameID Mapper Plugin | Specify the NameID mapper plug-in class that is used for SAML account mapping. |
SAML Attributes Namespace | Specify the name space used for generating SAML attributes. |
Include Memberships | If enabled, this attribute specifies that the principal's membership must be included as a SAML attribute. |
Generate attribute assertion only: | If enabled, the generated SAML assertion for a web service provider will contain only SAML attribute statements, and no authentication statements. |
Click Save.
Once you've registered a web service provider to OpenSSO STS, you can configure a WS-Trust client. See Section 4.6, "To Register a WS-Trust Client."
When import a X.509 client certificate into the OpenSSO STS keystore, the WS-Trust client is automatically registered with OpenSSO STS.
Obtain a client X.509 certificate or public key in ASCII format from the web service client.
Use the keytool command to import the certificate or public key into the OpenSSO STS keystore.
cd $OPENSSO_CONFIG/openssosts/openssosts keytool -import -keystore keystore.jks -alias <pkaliasname> -file <pkfilename>
When prompted, enter the default keystore password.
The default keystore password is changeit.
(Optional) Add the certificate into the Advanced Properties list.
See Section 5.1.3.6, "To Configure OpenSSO STS Server Advanced Properties."
(Optional) You can use this certificate to configure a Certificate-based authentication module in the authentication chain.
See Section 6.3, "Managing Authentication Module Instances" and Section 6.4, "Managing Authentication Chains".