The WSIT Tutorial

Configuring A Secure Token Service (STS)

A Secure Token Service (STS) is a Web service that issues security tokens. That is, it makes assertions based on evidence that it trusts, to whoever trusts it (or to specific recipients). To communicate trust, a service requires proof, such as a signature, to prove knowledge of a security token or set of security tokens. A service itself can generate tokens or it can rely on a separate STS to issue a security token with its own trust statement (note that for some security token formats this can just be a re-issuance or co-signature). This forms the basis of trust brokering.

The issued token security model includes a target server, a client, and a trusted third party called a Security Token Service (STS). Policy flows from server to client, and from STS to client. Policy may be embedded inside an issued token assertion, or acquired out-of-hand. There may be an explicit trust relationship between the server and the STS. There must be a trust relationship between the client and the STS.

When the web service being referenced by the client uses any of the STS security mechanisms (refer to table in Summary of Service-Side Configuration Requirements, an STS must be specified. You can specify the STS in one of these ways.

On the service side, specify the endpoint of the Issuer element and/or specify the Issuer Metadata Exchange (Mex) address of the STS.

If you need to create a third-party STS, follow the steps in To Create a Third-Party STS.

If you already have an STS that you want to use, follow the steps in To Specify an STS on the Service Side.

An example that creates and uses an STS can be found in Example: STS Issued Token (STS).
On the client side, specify the information for a preconfigured STS. This is mainly used for a local STS that is in the same domain as the client. Configuring the STS for the client is described in To Specify an STS on the Client Side.

This section covers the following topics:

To Create a Third-Party STS

Use the STS wizard to create an STS from a WSDL file. When using the STS wizard, provide the name of the STS implementation class. This class must extend com.sun.xml.ws.security.trust.sts.BaseSTSImpl. After completing the steps of the wizard, your application will contain a new service that is an STS and includes a provider implementation class, STS WSDL, and a WSIT configuration file with a predefined set of policies.

To use the STS wizard to create an STS, follow these steps.

Create a new project for the STS by selecting File->New Project.

Select Web, then Web Application, then Next.

Type a Project Name. Click Finish.

Right-click the STS Project node, select New, then click File/Folder at the top.

Select Web Service from the Categories list.

Select Secure Token Service (STS) from the File Type(s) list.

Click Next.

Type a name for the Web Service Class Name.

Type or select a name for the Package list.

Click Finish.

The IDE takes a while to create the STS. When created, it appears under the project’s Web Services node as your_STSService, and the Java file appears in the right pane.

The STS wizard creates an empty implementation of the provider class. Implement the provider implementation class.

An example of this can be found in To Create and Secure the STS (STS).

Back in the Projects window, right-click the STS project folder, and select Edit Web Service Attributes to configure the STS.

Select Secure Service.

Select a Security Mechanism (but not one of the STS mechanisms). The example application uses Username Authentication with Symmetric Keys.

Select the Configure button. For the Algorithm Suite option, specify a value that matches the value of the web service. Set the Key Size to 128 if you have not configured Unlimited Strength Encryption. Select OK to close the configuration dialog.

Note –
Some of the algorithm suite settings require that Unlimited Strength Encryption be configured in the Java Runtime Environment (JRE), particularly the algorithm suites that use 256 bit encryption. Instructions for downloading and configuring unlimited strength encryption can be found at the following URLS:

http://java.sun.com/products/jce/javase.html

http://java.sun.com/javase/downloads/index_jdk5.jsp#docs

Select Act as Secure Token Service (STS).

The default values will create a valid STS.

Optionally, you can change the following configuration options:
- Issuer: Specify an identifier for the issuer for the issued token. This value can be any string that uniquely identifies the STS, for example, MySTS.
- Contract Implementation Class: Specify the actual implementation class for the WSTrustContract interface that will handle token issuance, validation, and the like. Default value is com.sun.xml.ws.trust.impl.IssueSamlTokenContractImpl for issuing SAML assertions, or click Browse to browse to another contract implementation class.
- Life Time of Issued Tokens: The life span of the token issued by the STS. Default value is 300,000 ms.
- Encrypt Issued Key: Select this option if the issued key should be encrypted using the service certificate. Default is true.
- Encrypt Issued Token: Select this option if the issued token should be encrypted using the service certificate. Default is false.

Optionally, to add one or more Service Providers that have a trust relationship with the STS, click the Add button and specify the following configuration options:
- Provider Endpoint URI: The endpoint URI of the service provider.
- Certificate Alias: The alias of the certificate of the service provider in the keystore.
- Token Type: The type of token the service provider requires, for example, urn:oasis:names:tc:SAML1.0:assertion.
- Key Type: The type of key the service provider requires. The choices are public key or symmetric key. Symmetric key cryptography relies on a shared secret and is usually faster than public key cryptography. Public key cryptography relies on a key that is made public to all and is primarily used for encryption but can be used for verifying signatures.

Click OK to close the Select STS Service Provider dialog.

Click OK to close the STS Configuration dialog.

Click the Keystore button to configure the keystore.

If you are using the updated GlassFish stores, these are the settings:
- Location: Defaults to the location and name of the keystore,as-install/domains/domain1/config/keystore.jks.
- Store Password: Type or accept changeit.
- Load Aliases: Click the Load Aliases button.
- Alias: Select wssip.
Click OK to close the dialog.

Right-click the STS Project and select Properties. Select the Run category, and type the following in the Relative URL field: /your_STSService?wsdl.

Run the Project (right-click the Project and select Run Project).

To view the STS WSDL, append your_STSService to the URL of the deployed application in the browser.

For the example application (Example: STS Issued Token (STS)), you would view the STS WSDL by browsing to http://localhost:8080//MySTSProject/MySTSService?wsdl.

To Specify an STS on the Service Side

This section discusses how to specify a Security Token Service that can be referenced by the service. On the service side, you select a security mechanism that includes STS in its title.

The STS itself is secured using a separate (non-STS) security mechanism. The security configuration of the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application.

To specify an STS for the web service, follow these steps.

Right-click the node for the web service you want to secure.

Select Edit Web Service Attributes.

Select Secure Service.

Select a Security Mechanism that specifies STS from the list.

Click Configure to specify the STS information.

Type the Issuer Address and/or Issuer Metadata Address.

When the Issuer Address and the Metadata values are the same, you only need to type the Issuer Address. For the example application, the Issuer Address would be http://localhost:8080/MySTSProject/MySTSService.

Set the Algorithm Suite value so that the algorithm suite value of the service matches the algorithm suite value of the STS.

To Specify an STS on the Client Side

Once you’ve determined whether the an STS is required to be configured on the client side (see Summary of Client-Side Configuration Requirements), configure the client Secure Token Service options, as follows.

In the Projects window, expand the node for the web services client.

Expand the Web Service References node.

Right-click the node for the web service reference for which you want to configure security options.

Select Edit Web Service Attributes.

When the Web Service References Attributes Editor is opened, select the WSIT tab to display the WSIT options.

Expand the Secure Token Service section to specify the information required by the service.

The following options are available for configuration:
- Endpoint: The endpoint of the STS.
- WSDL Location: The location of the WSDL for the STS.
- Metadata: The metadata address for the STS.
- Service Name: The service name of the STS.
- Port Name: The port name of the STS.
- Namespace: The namespace for the service in the WSDL.
The Endpoint field is a mandatory field. Depending on how you plan to configure the STS, you can provide either Metadata information or information regarding the WSDL Location, Service Name, Port Name and Namespace. The following section contains a few example STS configurations. When the options are configured along the lines of STS Example 2: Endpoint with WSDL Location, Service Name, Port Name, and Namespace, the dialog appears as shown in Figure 7–9.

Figure 7–9 WSIT Configuration Page: Secure Token Service on Client

Specifying an STS on the Client Side: Examples

STS Example 1: Endpoint with Metadata

Endpoint:

http://131.107.72.15/Security_Federation_SecurityTokenService_Indigo/
Symmetric.svc/Scenario_5_IssuedTokenForCertificate_MutualCertificate11

Metadata:

http://131.107.72.15/Security_Federation_SecurityTokenService_Indigo/Symmetric.svc

STS Example 2: Endpoint with WSDL Location, Service Name, Port Name, and Namespace