4 Managing the Security Token Service

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:

• About the OpenSSO Security Token Service

• To Configure the Security Token Service

• Generating Security Tokens

• To Register a Web Service Provider to OpenSSO STS

• To Configure a Web Service Provider

• To Register a WS-Trust Client

4.1 About the OpenSSO Security Token Service

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.

4.1.1 Security Token Generation Process Flow

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.

4.1.2 Supported Security Tokens and Security Mechanisms

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

4.1.3 Supported Standards

OpenSSO STS supports the following industry standards for web services security:

WS-Trust 1.3 and 1.0

Protocol for communicating requests and responses to the Security Token Service. See the following URLs for the comprehensive WS-Trust specification:

• http://docs.oasis-open.org/ws-sx/ws-trust/200512.

This specification describes the Web Services Trust Model and provides detailed information about security tokens and the Security Token Service Framework.

WS-Security 1.x

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

WS-Policy 1.5

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.

WS-SecurityPolicy 1.2

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.

4.1.4 Leveraging Dynamic Policy For OpenSSO STS WSDL

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

4.2 To Configure the Security Token Service

When you configure the Security Token Service, you specify how OpenSSO STS authenticates remote clients that request security tokens.

1. On the Configuration tab, click the Global subtab.

2. In the Global Properties list, click Security Token Service.

3. 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: HTTP://OpenSSOhost:OpenSSOport/URI/sts 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: HTTPS://host:port/URI/sts 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
   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: UserNameToken-Plain — Uses a user name token with a clear text password for securing Security Token service requests. X.509Token — Uses the X.509 certificate to secure the Security token. TLS-UserNameToken-Plain — KerberosToken — Uses Kerberos tokens.
   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. To add a credential user token to the list, Click Add. In the Add User Credential page, type a username and password, and then click Add. To remove an entry from the Credential for User Token list, click to mark the box corresponding to the entry, and then click Remove.
   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
   Signing and Encryption
   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. Direct Reference Key IdentifierRef X.509 Issuer Serial Reference For detailed information see http://www.oasis-open.org/committees/download.php/5943/oasis-200401-wss-x509-token-profile-1.0.pdf.
   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: AES 3DES 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. For AES, values of 28, 192, and 256 are supported. For 3DES, values of 0, 112, and 168 are supported. Depending upon the Encryption Strength, you may have to provision the appropriate encryption policies for the JDK.
   Key Store
   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. PublicKey SymmetricKey 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 Configuration
   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: HTTP/hostname.domainname@dc_domain_name 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.HTTP.keytab 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 Configuration
   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: To add a SAML attribute mapping to the list, in the New Value field type an attribute value-pair, and then click Add. Use the following format: SAML_attr_name=Real_attr_name where SAML_attr_name is the SAML attribute name from a SAML assertion contained in an incoming web service request, and Real_attr_name is the attribute name that is obtained from either the authenticated SSOToken or the identity repository. To remove an entry from the Current Values list, select the entry and them click Remove.
   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. To add a trusted issuer to the list, in the New Value field type the trusted issuer name, and then click Add. To remove an entry from the Current Values list, select the entry and them click Remove.
   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. To add an IP address to the list, in the New Value field type an IP address, and then click Add. To remove an entry from the Current Values list, select the entry and then click Remove.

   
   

4. Click Save.

4.3 Generating Security Tokens

The following summarizes the steps you take to use OpenSSO STS to generate security tokens:

1. Register a web service provider.

   See Section 4.4, "To Register a Web Service Provider to OpenSSO STS.".

2. Configure the web service provider. See the following sections:

   • Section 4.3.1, "Using the Security Token Generation Matrix."

   • Section 4.3.2, "To Read the Security Token Generation Matrix."

   • Section 4.5, "To Configure a Web Service Provider."

4.3.1 Using the Security Token Generation Matrix

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.

4.3.1.1 Token Generation Matrix Legend

Message-Level Security Binding

• 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.

Web Service Client Token

• 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

KeyType

• WS-Security SAML tokens: Bearer, Sender-Vouches, and Holder-of-Key

• WS-Trust RST keytype values: Symmetric, Public, and Bearer

OnBehalfOf Token

Used when the requestor is obtaining a token on behalf of another party.

UseKey

Used when the client supplies a public-key to be embedded in the issued token as the proof key.

OpenSSO STS Output Token

Attributes to be included in the SOAP message.

For general information about Web Service Security and related terminology, see the following URLs:

• http://www.oracle.com/technology/tech/standards/pdf/security.pdf

• http://download.oracle.com/docs/cd/E15523_01/web.1111/b32511/intro_security.htm#CDDHHGEE

4.3.2 To Read the Security Token Generation Matrix

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

4.3.2.1 Example: Using the Token Generation Matrix

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

4.4 To Register a Web Service Provider to OpenSSO STS

When you add a new web service provider security agent profile, the web service provider is automatically registered to OpenSSO STS.

1. On the Access Control tab, click the Agents subtab.

2. In the Agent section, click New.

3. 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.

   
   

4. 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."

4.5 To Configure a Web Service Provider

1. On the Access Control tab, click the Agents subtab.

2. In the Agent section, click name of the web service provider you want to configure.

3. 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 http://www.oasis-open.org/committees/download.php/16768/wss-v1.1-spec-os-SAMLTokenProfile.pdf for detailed information about SAML security tokens.
   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.

   
   

4. 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."

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.

1. Obtain a client X.509 certificate or public key in ASCII format from the web service client.

2. 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>
   

3. When prompted, enter the default keystore password.

   The default keystore password is changeit.

4. (Optional) Add the certificate into the Advanced Properties list.

   See Section 5.1.3.6, "To Configure OpenSSO STS Server Advanced Properties."

5. (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".