The WSIT Tutorial

Chapter 7 Using WSIT Security

This chapter describes how to use NetBeans Integrated Development Environment (“the IDE”) to configure security for web services and web service clients using WSIT.

This release of WSIT makes securing web services even easier by including a set of preconfigured security mechanisms that can be applied to a web service or a web service operation simply by selecting it from a list. You can use advanced configuration options to customize the security mechanism to the needs of your application.

This chapter covers the following topics:

Configuring Security Using NetBeans IDE

This section describes the following tasks:

To Secure the Service

To use the IDE to configure security for a web service and/or a web service operation, perform the following steps.

Create or open your web service.

If you need an example of how to create a web service, refer to Chapter 3, WSIT Example Using a Web Container and NetBeans IDE.

Note –
When creating an application using the wizards in NetBeans IDE and running on GlassFish, the Java EE Version defaults to Java EE 5. This results in an application compliant with JSR-109, Implementing Enterprise Web Services, which can be read at http://jcp.org/en/jsr/detail?id=109. If you select a value other than the default, for example, J2EE 1.4, the application that is created is not JSR-109 compliant, which means that the application is not JAX-WS, but is JAX-RPC.

In the Projects window, expand the Web Services node.

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

Select Edit Web Service Attributes.

When the Web Service Attributes Editor is opened, the WSIT Configuration options appear (see Figure 7–1).

Figure 7–1 Web Service Attributes Editor Page

Select Secure Service.

This option enables WSIT security for all of the operations of a web service.

For information on how to secure selected operations, refer to Securing Operations and Messages.

Select a Security Mechanism from the list.

Most of the mechanisms are fully functional without further configuration, however, if you’d like to customize the mechanism, click Configure to specify the configuration for that mechanism.

Options in the Configure dialog are discussed in Security Mechanism Configuration Options.

Specify Keystore, Truststore, STS, SSL, and/or user information as required for the selected security mechanism.

Refer to the entry for the selected security mechanism in Table 7–1. This table summarizes the information that needs to be set up for each of the security mechanisms.

Click OK to save your changes.

Run the web application by right-clicking the project node and selecting Run Project.

Verify the URL of the WSDL file before proceeding with the creation of the web service client.

The client will be created from this WSDL file, and will get the service’s security policies through the web service reference URL when the client is built or refreshed.

Next Steps

The WSIT Configuration file that is used when the web service is deployed can be viewed by expanding the Web Pages->WEB-INF elements of the application in the tree, and then double-clicking the wsit-package.service.xml file to open it in the editor. The full contents of an example service-side WSIT configuration file can be viewed at Service-Side WSIT Configuration Files.

Steps for configuring an example application are provided for several of the mechanisms. See the following sections for a complete example of how to configure a web service and a web service client to use these security mechanisms:

To Secure the Client

All of the steps in To Secure the Service need to be completed before you create your web service client. The service’s security policies are defined in its WSDL. You specify this WSDL file when you create the client application so that the client is configured to work with the service’s security mechanism through the web service reference URL when the client is built or refreshed.

To use the IDE to configure security for a web service client, perform the following steps.

Create a client for your web service.

If you need an example of how to do this, see Creating a Client to Consume a WSIT-Enabled Web Service.

If you are creating a client for a mechanism that will use SSL, specify the secure port for running the client when completing the New Web Service Client step. To do this, type https:// fully_qualified_hostname:8181/rest_of_url in the WSDL URL field of the New Web Service Client wizard. For the example, this is the way to specify the secure URL for CalculatorWS web service:
https://fully_qualified_hostname:8181/CalculatorApplication/CalculatorWSService?wsdl
Note –
If you prefer to use localhost in place of the fully-qualified hostname when specifying the URL for the service WSDL, you must follow the workaround described in Transport Security (SSL) Workaround.

In the Projects window, expand the client node.

Expand the Web Service References node.

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

Select Edit Web Service Attributes.

When the Web Service References Attributes Editor is opened, select the WSIT tab to display the WSIT options (see Figure 7–2).

Figure 7–2 Web Service References Attributes Editor Page for Web Service Clients

Refer to Table 7–2 for a summary of what options are required on the client side. The configuration requirements for the client are dependent upon which security mechanism is specified on the server side.

Click OK to save your changes.

The WSIT configuration information is saved in two files under Source Packages->META-INF.

Next Steps

To view the WSIT configuration files, in the tree, drill down from the project to Source Packages->META-INF. Double-click on serviceService.xml or wsit-client.xml to view the contents. The full contents of example client WSIT configuration files can be viewed at Client-Side WSIT Configuration Files.

Summary of Configuration Requirements

The following sections summarize the options that need to be configured for each of the security mechanisms on both the service and client side. The configuration requirements for the client are dependent upon which security mechanism is specified on the server side.

This section covers the following topics:

Summary of Service-Side Configuration Requirements

Table 7–1 summarizes the options that need to be configured for each of the security mechanisms. Each of the columns is briefly discussed after the table.

Table 7–1 Summary of Service-Side Configuration Requirements


Mechanism	Keystore	Truststore	STS	SSL	User in GlassFish
Username Authentication with Symmetric Keys	X				X
Mutual Certificates	X	X (no alias)
Transport Security				X	X
Message Authentication over SSL - Username Token				X	X
Message Authentication over SSL - X.509 Token		X (no alias)		X
SAML Authorization over SSL	X	X (no alias)		X
Endorsing Certificate	X	X
SAML Sender Vouches with Certificate	X	X (no alias)
SAML Holder of Key	X	X (no alias)
STS Issued Token	X	X	X
STS Issued Token with Service Cert.	X	X	X
STS Issued Endorsing Token	X	X	X

Keystore: If this column has an X, click the Keystore button and configure the keystore to specify the alias identifying the service certificate and private key. For the GlassFish keystores, the file is keystore.jks and the alias is xws-security-server, assuming that you’ve updated the GlassFish default certificate stores as described in To Update GlassFish Certificates.
Truststore: If this column has an X, click the Truststore button and configure the truststore to specify the alias that contains the certificate and trusted roots of the client. For the GlassFish keystores, the file is cacerts.jks and the alias is xws-security-client, assuming that you’ve updated the GlassFish default certificate stores as described in To Update GlassFish Certificates.
STS: If this column has an X, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS). The STS is secured using a separate (non-STS) security mechanism. The security configuration for 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.
SSL: To use a mechanism that uses secure transport (SSL), you must configure the system to point to the client and server keystore and truststore files. Steps for doing this are described in Configuring SSL For Your Applications.
User in Glassfish: To use a mechanism that requires a user database for authentication, you can add a user to the file realm of GlassFish. Instructions for doing this can be found at Adding Users to GlassFish.

Summary of Client-Side Configuration Requirements

Table 7–2 summarizes the options that need to be configured for each of the security mechanisms on the client-side. Each of the columns is briefly discussed after the table.

Table 7–2 Summary of Client-Side Configuration Requirements


Mechanism	Keystore	Truststore	Default User	SAML Callback Handler	STS	SSL	User in GlassFish
Username Authentication with Symmetric Keys		X	X				X
Mutual Certificates	X	X
Transport Security						X	X
Message Authentication over SSL - Username Token			X			X	X
Message Authentication over SSL - X.509 Token	X					X
SAML Authorization over SSL	X	X		X		X
Endorsing Certificate	X	X
SAML Sender Vouches with Certificate	X	X		X
SAML Holder of Key	X	X		X
STS Issued Token	X	X			X
STS Issued Token with Service Certificate	X	X			X
STS Issued Endorsing Token	X	X			X

Keystore: If this column has an X, configure the keystore to point to the alias for the client certificate. For the GlassFish keystores, the keystore file is keystore.jks and the alias is xws-security-client, assuming that you’ve updated the GlassFish default certificate stores as described in To Update GlassFish Certificates.
Truststore: If this column has an X, configure the truststore that contains the certificate and trusted roots of the server. For the GlassFish keystores, the file is cacerts.jks and the alias is xws-security-server, assuming that you’ve updated the GlassFish default certificate stores as described in To Update GlassFish Certificates.

When using an STS mechanism, the client specifies the truststore and certificate alias for the STS, not the service. For the GlassFish stores, the file is cacerts.jks and the alias is wssip.
Default User: When this column has an X, you must configure either a default username and password, a UsernameCallbackHandler, or leave these options blank and specify a user at runtime. More information on these options can be found at Configuring Username Authentication on the Client.
SAML Callback Handler: When this column has an X, you must specify a SAML Callback Handler. Examples of SAML Callback Handlers are described in Example SAML Callback Handlers.
STS: If this column has an X, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS). The STS is secured using a separate (non-STS) security mechanism. The security configuration for 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.
SSL: To use a mechanism that uses secure transport (SSL), you must configure the system to point to the client and server keystore and truststore files. Steps for doing this are described in Configuring SSL For Your Applications.
User in Glassfish: To use a mechanism that requires a user database for authentication, you can add a user to the file realm of GlassFish. Instructions for doing this can be found at Adding Users to GlassFish.

Configuring Username Authentication on the Client

On the client side, a user name and password must be configured for some of the security mechanisms. For this purpose, you can use the default Username and Password Callback Handlers (when deploying to GlassFish), specify a SAML Callback Handler, specify a default user name and password for development purposes, create and specify your own Callback Handlers if the container you are using does not provide defaults, or leave all of these options blank and specify the username and password dynamically at runtime. When using any of these options, you must create an authorized user on GlassFish using the Admin Console, as described in Adding Users to GlassFish.

To Configure Username Authentication on the Client

Once you’ve created an authorized user and determined how your application needs to specify the user, configure the Username Authentication options as follows.

In the Projects window, expand the node for the web service 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.

Select the WSIT tab to display the WSIT options.

Expand the Username Authentication section to specify the user name and password information as required by the service. The dialog appears as shown in Figure 7–3.

Figure 7–3 WSIT Configuration - Client - Username Authentication

The following options are available.

Note –
Currently the GlassFish CallbackHandler cannot handle the following: SAML Callbacks and Require ThumbPrint Reference assertions under an X.509 Token. This may be addressed in a future milestone.
- Authentication Credentials: Select Static or Dynamic.
- Default Username, Default Password: Type the name of an authorized user and the password for this user. This option is best used only in the development environment. When the Default Username and Default Password are specified, the username and password are stored in the wsit-client.xml file in clear text, which presents a security risk. Do not use this option for production.
- SAML Callback Handler: To use a SAML Callback Handler, you need to create one, as there is no default. References to example SAML Callback Handlers are provided in Example SAML Callback Handlers. An example that uses a SAML Callback Handler can be found in Example: SAML Authorization over SSL (SA).

Example SAML Callback Handlers

Creating a SAML Callback Handler is beyond the scope of this document. However, the following web pages may be helpful for this purpose:

A client-side configuration, which includes a SAML Callback Handler, can be viewed at the following URL:

https://wsit.dev.java.net/source/browse/*checkout*/wsit/wsit/test/e2e/testcases/xwss/s11/resources/wsit-client.xml
An example of a SAML Callback Handler can be viewed and/or downloaded from the following URL:

https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645[amp ]expandFolder=6645[amp ]folderID=6645
An example application in this tutorial that uses a SAML Callback Handler can be found in Example: SAML Authorization over SSL (SA).

When writing SAML Callback Handlers for different security mechanisms, set the subject confirmation method to SV (Sender Vouches) or HOK (Holder of Key) and the appropriate SAML Assertion version depending on the SAML version and SAML Token Profile selected when setting the security mechanism for the service.

For example, the following code snippet for one of the SAMLCallbackHandlers listed above demonstrates how to set the subject confirmation method and sets the SAMLAssertion version to 1.0, profile 1.0.

if (callbacks[i] instanceof SAMLCallback) {
    try {

        SAMLCallback samlCallback = (SAMLCallback)callbacks[i];

        /*
         Set confirmation Method to SV [SenderVouches] or HOK[Holder of Key]
        */
        samlCallback.setConfirmationMethod
            (samlCallback.SV_ASSERTION_TYPE);

        if (samlCallback.getConfirmationMethod().equals(
                samlCallback.SV_ASSERTION_TYPE)) {
            samlCallback.setAssertionElement
                (createSVSAMLAssertion());

            svAssertion_saml10 =
                 samlCallback.getAssertionElement();
            /*
            samlCallback.setAssertionElement
                (createSVSAMLAssertion20());
            svAssertion_saml20 =
                 samlCallback.getAssertionElement();
            */
        } else if (samlCallback.getConfirmationMethod().equals(
                samlCallback.HOK_ASSERTION_TYPE)) {
            samlCallback.setAssertionElement
                (createHOKSAMLAssertion());
            hokAssertion_saml10 =
                 samlCallback.getAssertionElement();
            /*
            samlCallback.setAssertionElement
                (createHOKSAMLAssertion20());
            hokAssertion_saml20 =
                 samlCallback.getAssertionElement();
            */
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
} else {
    throw unsupportedCallback;
}

Security Mechanisms

This section describes security mechanisms you can implement with WSIT. This section covers the following topics:

A table that summarizes the configuration options on the server side is available in Summary of Service-Side Configuration Requirements.

Some common communication issues that need to be addressed using security mechanisms are discussed in Using Security Mechanisms.

Username Authentication with Symmetric Keys

The Username Authentication with Symmetric Keys mechanism protects your application for integrity and confidentiality. Symmetric key cryptography relies on a single, shared secret key that is used to both sign and encrypt a message. Symmetric keys are usually faster than public key cryptography.

For this mechanism, the client does not possess any certificate/key of his own, but instead sends its username/password for authentication. The client shares a secret key with the server. The shared, symmetric key is generated at runtime and encrypted using the service’s certificate. The client must specify the alias in the truststore by identifying the server’s certificate alias.

Mutual Certificates Security

The Mutual Certificates Security mechanism adds security through authentication and message protection that ensures integrity and confidentiality. When using mutual certificates, a keystore and truststore file must be configured for both the client and server sides of the application.

Transport Security (SSL)

The Transport Security mechanism protects your application during transport using SSL for authentication and confidentiality. Transport-layer security is provided by the transport mechanisms used to transmit information over the wire between clients and providers, thus transport-layer security relies on secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). Transport security is a point-to-point security mechanism that can be used for authentication, message integrity, and confidentiality. When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data. Security is “live” from the time it leaves the consumer until it arrives at the provider, or vice versa. The problem is that it is not protected once it gets to its destination. For protection of data after it reaches its destination, use one of the security mechanisms that uses SSL and also secures data at the message level.

Digital certificates are necessary when running secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). The HTTPS service of most web servers will not run unless a digital certificate has been installed. Digital certificates have already been created for GlassFish, and the default certificates are sufficient for running this mechanism, and are required when using Atomic Transactions (see Chapter 12, Using Atomic Transactions). However, the message security mechanisms require a newer version of certificates than is available with GlassFish. You can download valid keystore and truststore files for the client and server as described in To Update GlassFish Certificates.

To use this mechanism, follow the steps in Configuring SSL For Your Applications.

Transport Security (SSL) Workaround

This note applies to cases where https is the transport protocol used between a WSIT client and a secure web service using transport binding, and you are referencing localhost when creating the client.

Note –

If you use the fully-qualified hostname (FQHN) in the URL for the service WSDL when you are adding the web service client to the client application, this workaround is not required. It is only required when you specify localhost in the URL for the service WSDL.

During development (not production) it is sometimes convenient to use certificates whose CN (Common Name) does not match the host name in the URL.

A developer would want to use a CN which is different from the host name in the URL in WSIT when using https addresses in Dispatch clients and during wsimport. The below mentioned workaround is only for the Dispatch clients, which are also used in WS-Trust to communicate with STS. This has to be done even if the client’s main service is not on https, but only the STS is on https.

Java by default verifies that the certificate CN (Common Name) is the same as host name in the URL. If the CN in the certificate is not the same as the host name, your web service client fails with the following exception:

javax.xml.ws.WebServiceException: java.io.IOException: 
HTTPS hostname wrong: should be <hostname as in the certificate>

The recommended way to overcome this issue is to generate the server certificate with the Common Name (CN) matching the host name.

To work around this only during development, in your client code, you can set the default host name verifier to a custom host name verifier which does a custom check. An example is given below. It is sometimes necessary to include this in the static block of your main Java class as shown below to set this verifier before any connections are made to the server.

static {
    //WORKAROUND. TO BE REMOVED.

    javax.net.ssl.HttpsURLConnection.setDefaultHostnameVerifier(
    new javax.net.ssl.HostnameVerifier(){

        public boolean verify(String |hostname|,
                javax.net.ssl.SSLSession sslSession) {
            if (hostname.equals("mytargethostname")) {
                return true;
            }
            return false;
        }
    });
}

Please remember to remove this code once you install valid certificates on the server.

Message Authentication over SSL

The Message Authentication over SSL mechanism attaches a cryptographically secured identity or authentication token with the message and use SSL for confidentiality protection.

By default, a Username Supporting Token will be used for message authentication. To use an X.509 Supporting Token instead, click the Configure button and select X509. Under this scenario, you will need to configure your system for using SSL as described in Configuring SSL For Your Applications.

SAML Authorization over SSL

The SAML Authorization over SSL mechanism attaches an authorization token with the message and uses SSL for confidentiality protection. In this mechanism, the SAML token is expected to carry some authorization information about an end user. The sender of the token is actually vouching for the credentials in the SAML token.

To use this mechanism, configure SSL on the server, as described in Configuring SSL For Your Applications, and, on the clients side, configure a SAMLCallbackHandler as described in Example SAML Callback Handlers.

Endorsing Certificate

This mechanism uses secure messages using symmetric key for integrity and confidentiality protection, and uses an endorsing client certificate to augment the claims provided by the token associated with the message signature. For this mechanism, the client knows the service’s certificate, and requests need to be endorsed/authorized by a special identity. For example, all requests to a vendor must be endorsed by a purchase manager, so the certificate of the purchase manager should be used to endorse (or counter sign) the original request.

SAML Sender Vouches with Certificates

This mechanism protects messages with mutual certificates for integrity and confidentiality and with a Sender Vouches SAML token for authorization. The Sender Vouches method establishes the correspondence between a SOAP message and the SAML assertions added to the SOAP message. The attesting entity provides the confirmation evidence that will be used to establish the correspondence between the subject of the SAML subject statements (in SAML assertions) and SOAP message content. The attesting entity, presumed to be different from the subject, vouches for the verification of the subject. The receiver has an existing trust relationship with the attesting entity. The attesting entity protects the assertions (containing the subject statements) in combination with the message content against modification by another party. For more information about the Sender Vouches method, read the SAML Token Profile document at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf.

For this mechanism, the SAML token is included as part of the message signature as an authorization token and is sent only to the recipient. The message payload needs to be signed and encrypted. The requestor is vouching for the credentials (present in the SAML assertion) of the entity on behalf of which the requestor is acting.

The initiator token, which is an X.509 token, is used for signature. The recipient token, which is also an X.509 token, is used for encryption. For the server, this is reversed, the recipient token is the signature token and the initiator token is the encryption token. A SAML token is used for authorization.

SAML Holder of Key

This mechanism protects messages with a signed SAML assertion (issued by a trusted authority) carrying client public key and authorization information with integrity and confidentiality protection using mutual certificates. The Holder-of-Key (HOK) method establishes the correspondence between a SOAP message and the SAML assertions added to the SOAP message. The attesting entity includes a signature that can be verified with the key information in the confirmation method of the subject statements of the SAML assertion referenced for key info for the signature. For more information about the Holder of Key method, read the SAML Token Profile document at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf.

Under this scenario, the service does not trust the client directly, but requires the client to send a SAML assertion issued by a particular SAML authority. The client knows the recipient’s public key, but does not share a direct trust relationship with the recipient. The recipient has a trust relationship with the authority that issues the SAML token. The request is signed with the client’s private key and encrypted with the server certificate. The response is signed using the server’s private key and encrypted using the key provided within the HOK SAML assertion.

STS Issued Token

This security mechanism protects messages using a token issued by a trusted Secure Token Service (STS) for message integrity and confidentiality protection.

An STS is a service that implements the protocol defined in the WS-Trust specification (you can find a link to this specification at https://wsit.dev.java.net/). This protocol defines message formats and message exchange patterns for issuing, renewing, canceling, and validating security tokens.

Service providers and consumers are in potentially different managed environments but use a single STS to establish a chain of trust. The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate. The issued tokens contain a key, which is encrypted for the server and which is used for deriving new keys for signing and encrypting.

To use this mechanism for the web service, you simply select this option as your security mechanism. However, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS). In this section, you select a security mechanism for the STS. The security configuration for 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. The client truststore must contain the certificate of the STS, which has the alias of wssip if you are using the updated GlassFish certificates.

STS Issued Token with Service Certificate

This security mechanism is similar to the one discussed in STS Issued Token, with the difference being that in addition to the service requiring the client to authenticate using a SAML token issued by a designated STS, confidentiality protection is achieved using a service certificate. A service certificate is used by a client to authenticate the service and provide message protection. For GlassFish, a default certificate of s1as is installed.

STS Issued Endorsing Token

This security mechanism is similar to the one discussed in STS Issued Token, with the difference being that the client authenticates using a SAML token that is issued by a designated STS. An endorsing token is used to sign the message signature.

In this mechanism, message integrity and confidentiality are protected using ephemeral keys encrypted for the service. Ephemeral keys use an algorithm where the exchange key value is purged from the cryptographic service provider (CSP) when the key handle is destroyed. The service requires messages to be endorsed by a SAML token issued by a designated STS.

Service providers and consumers are in potentially different managed environments. For this mechanism, the service requires that secure communications be endorsed by a trusted STS. The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate.

For this mechanism, authentication of the client is achieved in this way:

The client authenticates with the STS and obtains the necessary token with credentials.
The client’s request is signed and encrypted using ephemeral key K.
The server’s response is signed and encrypted using the same K.
The primary signature of the request is endorsed using the issued token.

Configuring SSL and Authorized Users

This section discusses configuring security for your web service and web service client using the WSIT security mechanisms. Some of these mechanisms require some configuration outside of NetBeans IDE. Depending upon which security mechanism you plan to use, some of the following tasks will need to be completed:

If you are using the GlassFish container and message security, you must update the GlassFish keystore and truststore by importing v3 certificates. The procedure for updating the certificates is described in To Update GlassFish Certificates.
If you are using a security mechanism that requires a user to enter a user name and password, create authorized users for your container. Steps for creating an authorized user for the GlassFish container are described in Adding Users to GlassFish.
To use a mechanism that uses secure transport (SSL), you must configure the system to point to the client and server keystore and truststore files. Steps for doing this are described in Configuring SSL For Your Applications.

This section covers the following topics:

Configuring SSL For Your Applications

This section describes adding the steps to configure your application for SSL. These steps will need to be accomplished for any application that uses one of the mechanisms:

To Configure SSL for Your Application

The following steps are generic to any application, but have example configurations that will work with the tutorial examples, in particular, Example: SAML Authorization over SSL (SA) and Example: Transport Security (SSL).

To configure SSL for your application, follow these steps.

Select one of the mechanisms that require SSL.

These include Transport Security (SSL), Message Authentication over SSL, and SAML Authorization over SSL.

Server Configuration
- GlassFish is already configured for SSL. No further SSL configuration is necessary if you are using Transport Security. However, if you are using one of the Message Security mechanisms with SSL, you must update the GlassFish certificates as described in To Update GlassFish Certificates.
- Configure a user on GlassFish as described in Adding Users to GlassFish.

Client Configuration

For configuring your system for SSL in order to work through the examples in this tutorial, the same keystore and truststore files are used for both the client and the service. This makes it unnecessary to set system properties to point to the client stores, as both GlassFish and NetBeans IDE are aware of these certificates and point to them by default.

In general, for the client side of SSL you will not be using the same certificates for the client and the service. In that case, you need to define the client certificate stores by setting the system properties -Djavax.net.ssl.trustStore, -Djavax.net.ssl.keyStore, -Djavax.net.ssl.trustStorePassword, and -Djavax.net.ssl.keyStorePassword in the application client container.

You can specify the environment variables for keystore and truststore by setting the environment variable VMARGS through the shell environment or inside an Ant script, or by passing them in when you start NetBeans IDE from the command line. For example, in the latter case, you would specify the property settings as follows:

netbeans-install/bin/netbeans.exe
 -J-Djavax.net.ssl.trustStore=as-install/domains/domain1/config/cacerts.jks
 -J-Djavax.net.ssl.keyStore=as-install/domains/domain1/config/keystore.jks
 -J-Djavax.net.ssl.trustStorePassword=changeit
 -J-Djavax.net.ssl.keyStorePassword=changeit

Use the hard-coded path to the keystore and truststore files, not variables.

For the SSL mechanism, The browser will prompt you to accept the server alias s1as.

On the client side, for the Transport Security (SSL) mechanism, you must either use the fully-qualified hostname in the URL for the service WSDL when you are creating the web sercie client, or else you must follow the steps in Transport Security (SSL) Workaround.

Service Configuration

To require the service to use the HTTPS protocol, you have to specify the security requirements in the service’s application deployment descriptor. This file is ejb-jar.xml for a web service that is implemented as an EJB endpoint, and web.xml for a web service implemented as a servlet. To specify the security information, follow these steps:
1. From your web service application, expand Web Pages->WEB-INF.
2. Double-click web.xml (or ejb-jar.xml) to open it in the editor.
3. Select the Security tab.
4. On the Security Constraints line, click Add Security Constraint.
5. Under Web Resource Collection, click Add.
6. Type a Name for the Resource (for example, CalcWebResource), and type the URL Pattern to be protected (for example, /*). Select which HTTP Methods to protect, for example, POST. Click OK to close this dialog.
7. Check the Enable User Data Constraint box. Select CONFIDENTIAL for the Transport Guarantee to specify that the application uses SSL because the application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission.
  
  The IDE appears as shown in Figure 7–4.
  
  Figure 7–4 Deployment Descriptor Page
8. Click the XML tab to display the additions to web.xml. The security constraint looks like this:
```
<security-constraint>
  <display-name>Constraint1</display-name>
  <web-resource-collection>
    <web-resource-name>CalcWebResource</web-resource-name>
    <description/>
    <url-pattern>/*</url-pattern>
    <http-method>POST</http-method>
  </web-resource-collection>
  <user-data-constraint>
    <description/>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>
```
9. When you run this project (right-click, select Run Project), the browser will ask you to accept the server certificate of s1as. Accept this certificate. The WSDL appears in the browser.

Creating a Client

When creating your client application, use the fully-qualified hostname to specify the secure WSDL location (use https://fully_qualified_hostname:8181/CalculatorApplication/CalculatorWSService?wsdl, for example, in place of http://localhost:8080/CalculatorApplication/CalculatorWSService?wsdl).

In some cases, you might get an error dialog telling you that the URL https://fully_qualified_hostname:8181/CalculatorApplication/CalculatorWSService?wsdl couldn’t be downloaded. However, this is the correct URL, and it does load when you run the service. So, when this error occurs, repeat the steps that create the Web Service Client using the secure WSDL. The second time, the web service reference is created and you can continue creating the client.

Adding Users to GlassFish

This section describes the following tasks:

To Add Users to GlassFish Using the Admin Console

To add users to GlassFish using the Admin Console, follow these steps.

Start GlassFish if you haven’t already done so.

Start the Admin Console if you haven’t already done so.

You can start the Admin Console by starting a web browser and specifying the URL http://localhost:4848/asadmin. If you changed the default Admin port during installation, type the correct port number in place of 4848.

To log in to the Admin Console, type the user name and password of a user in the admin-realm who belongs to the asadmin group.

The name and password entered during installation will work, as will any users added to this realm and group subsequent to installation.

Expand the Configuration node in the Admin Console tree.

Expand the Security node in the Admin Console tree.

Expand the Realms node, then select the file realm.

Click the Manage Users button.

Click New to add a new user to the realm.

Type the correct information into the User ID, Password, and Group(s) fields.

The example applications reference a user with the following attributes:
- User ID = wsitUser
- Group List = wsit
- New Password = changeit
- Confirm New Password = changeit

Click OK to add this user to the list of users in the realm.

Click Logout when you have completed this task.

To Add Users to GlassFish From the Command Line

Make sure GlassFish is running, then type the following command:
as-install/asadmin create-file-user --groups wsit wsitUser

When you are prompted for the password, type changeit.

Configuring Keystores and Truststores

This section describes configuring keystores and truststores. Security mechanisms that use certificates require keystore and truststore files for deployment.

For GlassFish, default keystore and truststore files come bundled. However, WSIT security mechanisms for message security require X.509 version 3 certificates. GlassFish contains version 1 certificates. Therefore, to enable the WSIT applications to run on GlassFish, you will need to follow the instructions in To Update GlassFish Certificates.
For Tomcat, keystore and truststore files do not come bundled with this container, so they must be provided. You can download valid keystore and truststore files for the client and server from https://xwss.dev.java.net/.

This section covers the following topics:

To Update GlassFish Certificates

The WSIT message security mechanisms require the use of v3 certificates. The default GlassFish keystore and truststore do not contain v3 certificates at this time (but should before FCS). (GlassFish instances installed using JDK 1.6 do have a v3 certificate but the certificate lacks a particular extension required for supporting some secure WSIT mechanisms.) In order to use message security mechanisms with GlassFish, it is necessary to download keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.

Note –

The XWSS keystores are sample keystores containing sample v3 certificates. These sample keystores can be used for development and testing of security with WSIT technology. Once an application is in production, you should definitely use your own v3 certificates issued by a trusted authority. In order to use WSIT security on GlassFish, you will have to import your trusted stores into GlassFish’s keystore and specify those certificates from NetBeans IDE.

To update the GlassFish certificates, follow these steps.

Download the zip file that contains the certificates and the Ant scripts (copyv3.zip) by going to this URL:

https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645[amp ]expandFolder=6645[amp ]folderID=6645

Unzip this file and change into its directory, copyv3.

From the copyv3 directory, execute the Ant command that will copy the keystore and truststore files to the appropriate location, and import the appropriate certificates into the GlassFish keystore and truststore.

This Ant command is as follows:

as-install/lib/ant/bin/ant

The command window will echo back the certificates that are being added to the keystore and truststore files, and should look something like this:

[echo] WARNING: currently we add non-CA certs to GF truststore, this 
will not be required in later releases when WSIT starts supporting CertStore(s)
     [java] Added Key Entry  :xws-security-server
     [java] Added Key Entry  :xws-security-client
     [java] Added Trusted Entry  :xwss-certificate-authority
     [java] Added Key Entry  :wssip
     [java] Added Trusted Entry  :xws-security-client
     [java] Added Trusted Entry  :xws-security-server
     [java] Added Trusted Entry  :wssip
     [echo] Adding JVM Option for https outbound alias, this will take at least 
One Minute.
...

To verify that the updates were successful, follow these steps:

Change to the directory containing the GlassFish keystore and truststore files, as-install/domains/domain1/config.

Verify that the v3 certificate has been imported into the GlassFish truststore. To do this, run the following keytool command (all on one line):
java-home/bin/keytool -list -keystore cacerts.jks -alias wssip -storepass changeit
If the certificates are successfully updated, your response will look something like this:
wssip, Aug 20, 2007, trustedCertEntry, Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1
If the certificates were not successfully update, your response will look something like this:
keytool error: java.lang.Exception: Alias <wssip> does not exist

Verify that the v3 certificate has been imported into the GlassFish keystore. To do this, run the following keytool commands:

java-home/bin/keytool -list -keystore keystore.jks 
-alias xws-security-server -storepass changeit 
java-home/bin/keytool -list -keystore keystore.jks 
-alias xws-security-client -storepass changeit

If the certificates were successfully updated, your response should look something like this:

xws-security-server, Aug 20, 2007, PrivateKeyEntry,
Certificate fingerprint (MD5): E4:E3:A9:02:3C:B0:36:0C:C1:48:6E:0E:3E:5C:5E:84

If your certificates were not successfully updated, your response will look more like this:

keytool error: java.lang.Exception: Alias <xws-security-server> does not exist

Specifying Aliases with the Updated Stores

The configuration of the aliases for all containers (Tomcat, GlassFish) and for all applications (JSR-109-compliant and non-JSR-109-compliant), except for applications that use a Security Token Service (STS) mechanism, is as shown in Table 7–3.

Table 7–3 Keystore and Truststore Aliases


	Keystore Alias	Truststore Alias
Client-Side Configuration	xws-security-client	xws-security-server
Server-Side Configuration	xws-security-server	xws-security-client

The configuration of the aliases for applications that use a Security Token Service (STS) mechanism is as shown in Table 7–4.

Table 7–4 Keystore and Truststore Aliases for STS


	Keystore Alias	Truststore Alias
Client-Side Configuration	xws-security-client	xws-security-server
STS Configuration	xws-security-client	wssip

Configuring the Keystore and Truststore

NetBeans IDE already knows the location of the default keystore file and its password, but you need to specify which alias is to be used. The following sections discuss configuring the keystore on the service and on the client.

To Configure the Keystore on a Service

A keystore is a database of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. A key is a piece of information that controls the operation of a cryptographic algorithm. For example, in encryption, a key specifies the particular transformation of plaintext into ciphertext, or vice versa during decryption. Keys are used in digital signatures for authentication.

To configure a keystore on a service, perform the following steps.

Check the table in Summary of Service-Side Configuration Requirements to see if a keystore needs to be configured for the selected security mechanism. If so, continue.

Right-click the web service and select Edit Web Service Attributes.

The Web Service Attributes editor is displayed.

Enable Secure Service, then select a security mechanism.

Check the table in Summary of Service-Side Configuration Requirements to see what keystore configuration, if any, is required for that mechanism.

Click the Keystore button. The dialog shown in Figure 7–5 appears.

Figure 7–5 Keystore Configuration Dialog

Depending on what is required for the selected mechanism, you may specify the following information in the Keystore Configuration dialog:
- Keystore Password: Specifies the password for the keystore file. If you are running under GlassFish, GlassFish’s password is already entered. If you have changed the keystore’s password from the default, you must specify the correct value in this field.
- Load Aliases: Click the Load Aliases button to populate the Alias field with the aliases contained in the keystore file. The Location and Store Password fields must be specified correctly for this option to work.
- Alias: Specifies the alias of the certificate in the specified keystore to be used for authentication. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias to choose for the selected security mechanism.
- Key Password: Specifies the password of the key within the keystore. For this sample, leave this blank. For this field, the default assumes the key password is the same as the store password, so you only need to specify this field when the key password is different.
Note –
The Key Password field enables you to specify a password for the keystore used by the application. When specified, this password is stored in a WSIT configuration file in clear text, which is a security risk. Setting the keystore password in the development environment is fine, however, when you go into production, remember to use the container’s Callback Handler to obtain the keys from the keystore. This eliminates the need for the keystore passwords to be supplied by the users. You can also specify the passwords for keystores and truststores by specifying a Callback Handler class that implements the javax.security.auth.callback.CallbackHandler interface in the Key Password or Store Password fields.

When creating JSR-109-compliant application, GlassFish will only use the default CallbackHandlers and Validators, and you cannot override the location of the keystore and truststore files. Any attempt to override the default location will be ignored. You do, however, need to specify the keystore and truststore locations in these dialogs in order to specify the alias.

When creating non-JSR-109-compliant application, you can specify the passwords for keystores and truststores by specifying a CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Key Password or Store Password fields.

Click OK to close the dialog.

To Configure the Truststore on a Service

A truststore is a database of trusted entities and their associated X.509 certificate chains authenticating the corresponding public keys.

The truststore contains the Certificate Authority (CA) certificates and the certificates of the other party to which this entity intends to send encrypted (confidential) data. This file must contain the public key certificates of the CA and the client’s public key certificate. Any kind of encryption without WS-SecureConversation will generally require that a truststore be configured on the client side. Any kind of signature without WS-SecureConversation will generally require a truststore on the server side.

Note –

For this release, place the trusted certificates of other parties in GlassFish’s truststore, cacerts.jks. This is not normally a recommended practice because any certificate you add to the cacerts.jks file effectively means it can be a trusted root for any and all certificate chains, which can be a security problem. In future releases, trusted certificates from other parties will be placed in a certstore, and only trusted roots will be placed inside cacerts.jks.

To set the truststore configuration options on a service, perform the following steps.

Check the table in Summary of Service-Side Configuration Requirements to see if a truststore is required for the selected security mechanism. If so, continue.

Right-click the web service and select Edit Web Service Attributes.

The Web Service Attributes editor is displayed.

Enable Secure Service.

Click the Truststore button.

On the Truststore Configuration page, specify the following options:
- Location: By default, the location and name of the truststore that stores the public key certificates of the CA and the client’s public key certificate is already entered. The GlassFish truststore file is as-install/domains/domain1/config/cacerts.jks.
- Store Password: Specifies the password for the truststore. If you are using GlassFish, the value of changeit is already entered. If you have changed the value of the truststore password, you must type the new value in this field.
  
  Note –
  The Store Password field enables you to specify a password for the truststore used by the application. When specified, this password is stored in a WSIT configuration file in clear text, which is a security risk. Setting the truststore password in the development environment is fine, however, when you go into production, remember to use the container’s Callback Handler to obtain the keys from the truststore. This eliminates the need for the truststore passwords to be supplied by the users. You can also specify the passwords for keystores and truststores by specifying a CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Key Password or Store Password fields.
  
  When creating JSR-109-compliant application, GlassFish will only use the default CallbackHandlers and Validators, and you cannot override the location of the keystore and truststore files. Any attempt to override the default location will be ignored. You do, however, need to specify the keystore and truststore locations in these dialogs in order to specify the alias.
- Load Aliases: Click the Load Aliases button to populate the Alias field with the aliases contained in the truststore file. The Location and Store Password fields must be specified correctly for this option to work.
- Alias: Specifies the peer alias of the certificate in the truststore that is to be used when the client needs to send encrypted data. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism. A truststore contains trusted other-party certificates and certificates of Certificate Authorities (CA). A peer alias is the alias of the other party (peer) that the sending party needs to use to encrypt the request.

Click OK to close the dialog.

To Configure the Keystore and Truststore on a Client

On the client side, a keystore and truststore file must be configured for some of the security mechanisms. Refer to the table in Summary of Client-Side Configuration Requirements for information on which mechanisms require the configuration of keystores and truststores.

If the mechanism configured for the service requires the configuration of keystores and truststores, follow these steps.

Check the table in Summary of Client-Side Configuration Requirements to see if a keystore needs to be configured for the client for the selected security mechanism. If so, continue.

In the Projects window, expand the node for the web service 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 Configuration tab to display the WSIT options.

Expand the Certificates section to specify the keystore and truststore information if required by the service.

Depending on what is required for the selected mechanism, you may specify the following information in the Certificates section:
- Keystore Location: The directory and file name containing the certificate key to be used to authenticate the client. By default, the location is already set to the default GlassFish keystore, as-install/domains/domain1/config/keystore.jks.
- Keystore Password: The password for the keystore used by the client. By default, the password for the GlassFish keystore is already entered. This password is changeit.
  
  Note –
  When specified, this password is stored in a WSIT configuration file in clear text. Setting the keystore password in the development environment is fine, however, when you go into production, remember to use the container’s default CallbackHandler to obtain the keys from the keystore. This eliminates the need for the keystore passwords to be supplied by the users. You can also specify the passwords for keystores and truststores by specifying a CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Keystore Password, Truststore Password, or Key Password fields.
- Load Aliases: Click this button to populate the Alias list with all of the certificates available in the selected keystore. This option will only work if the keystore location and password are correct.
- Keystore Alias: Select the alias in the keystore. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism.
- Key Password: If the client key has been password-protected, type the password for this key. The GlassFish certificate key password is changeit.
- Truststore Location: The directory and file name of the client truststore containing the certificate of the server. By default, this field points to the default GlassFish truststore, as-install/domains/domain1/config/cacerts.jks.
- Truststore Password: The password for the truststore used by the client. By default, the password for the GlassFish truststore is already specified. The password is changeit.
  
  Note –
  When specified, this password is stored in a WSIT configuration file in clear text. Setting the truststore password in the development environment is fine; however, when you go into production, remember to use the container’s default CallbackHandler to obtain the keys from the keystore. This eliminates the need for the keystore passwords to be supplied by the users. You can also specify the passwords for keystores and truststores by specifying a CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Keystore Password, Truststore Password, or Key Password fields.
- Load Aliases: Click this button to populate the Alias list with all of the certificates available in the selected keystore. This option will only work if the truststore location and password are correct.
- Truststore Alias: Select the alias of the server certificate and private key in the client truststore. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism.
When the certificates are configured as suggested for some of the examples in this chapter, the dialog will appear as shown in Figure 7–6.

Figure 7–6 Client-side Certificate Configuration Dialog

Click OK to close the dialog.

Configuring Validators

A validator is an optional set of classes used to check the validity of a token, a certificate, a timestamp, or a username and password.

Applications that run under a GlassFish 9.1 container do not need to configure Callback Handlers and Validators when using the IDE with WSIT enabled. This is because the container handles the callbacks and validation. You only need to make sure that the certificates are available at locations that GlassFish requires and/or create authorized users using the Admin Console (described in Adding Users to GlassFish.

Validators are always optional because there are defaults in the runtime (regardless of the container and regardless of whether the application is a JSR-109 or a non-JSR-109 deployment.) For non-JSR-109 deployment, you only need to specify a validator when you want to override the default validators. For JSR-109 deployments, there is no point in specifying an overriding validator, as these will be overridden back to the defaults by GlassFish, thus the Validators button is not available when the selected web service is a JSR-109-compliant application.

To Set Validator Configuration Options

To set the validator configuration options for a non-JSR-109-compliant application (such as a J2SE client), perform the following steps.

Right-click the web service and select Edit Web Service Attributes.

The Web Service Attributes editor is displayed.

Enable Secure Service.

Click the Validator button.

On the Validator Configuration page, specify the following options, when necessary:
- Username Validator: Specifies the validator class to be used to validate username and password on the server side. This option is only used by a web service.
  
  Note –
  When using the default Username Validator, make sure that the username and password of the client are registered with GlassFish (using Admin Console, described in Adding Users to GlassFish) if using GlassFish, or is included in the tomcat-users.xml file if using Tomcat.
- Timestamp Validator: Specifies the validator class to be used to check the token timestamp to determine whether the token has expired or is still valid.
- Certificate Validator: Specifies the validator class to be used to validate the certificate supplied by the client or the web service.
- SAML Validator: Specifies the validator class to be used to validate SAML token supplied by the client or the web service.

Click OK to close the dialog.

Securing Operations and Messages

This section explains how to specify security mechanisms at the operation level and at the message level.

You can specify security mechanisms at the following levels:

Operation

At times, you may need to configure different operations with different supporting tokens. You may wish to configure security at the operation level, for example, in the situation where only one operation requires a UsernameToken to be passed and the rest of the operations do not require this, or in the situation where only one operation needs to be endorsed by a special token and the others do not.
Input Message and Output Message

Security mechanisms at this level are used to specify what is being protected and the level of protection required.

In this section, you can specify parts of a message that require integrity protection (digital signature) and/or confidentiality (encryption). When you do this, the specified part of the message, outside of security headers, requires signature and/or encryption. For example, a message producer might submit an order that contains an orderID header. The producer signs and/or encrypts the orderID header (the SOAP message header) and the body of the request (the SOAP message body). Parts that can be signed and/or encrypted include the body, the header, the local name of the SOAP header, and the namespace of the SOAP header.

You can also specify arbitrary elements in the message that require integrity protection and/or confidentiality. Because of the mutability of some SOAP headers, a message producer may decide not to sign and/or encrypt the SOAP message header or body as a whole, but instead sign and/or encrypt elements within the header and body. Elements that can be signed and/or encrypted include an XPath expression or a URI which indicates the version of XPath to use.

This section covers the following topics:

To Specify Security at the Operation, Input Message, or Output Message Level

To specify security mechanisms at the level of the operation, input message, or output message, perform the following steps.

Right-click the web service and select Web Service Attributes.

The Web Service Attributes editor is displayed.

Select Secure Service.

Select a security mechanism.

The following mechanisms do not support Input message level protection:

Expand the operationOperation node.

Expand the Operation node. It should look like Figure 7–7.

Figure 7–7 Web Service Attributes Editor Page: Operation Level

Expand the Operation section.

The section will be grayed out if Secure Service is not selected.

Select an option from the Transactions list to specify a level at which transactions will be secured.

For this release, transactions will only use SSL for security. Transactions are discussed in Chapter 12, Using Atomic Transactions.

Expand the Input Message section.

This section will be grayed out if Secure Service is not selected.

Specify the following options, as appropriate:
- Authentication Token: Specifies which supporting token will be used to sign and/or encrypt the specified message parts. Options include Username, X509, SAML, Issued, or None. For further description of these options, read Supporting Token Options.
- Signed: Specifies that the authentication token must be a signed, supporting token. A signed, supporting token is signed by the primary signature token and is part of primary signature.
- Endorsing: Specifies that the authentication token must be endorsed. With an endorsing supporting token, the key represented by the token is used to endorse/sign the primary message signature.
If both Signed and Endorsing are selected, the authentication token must be a signed, endorsing, supporting token. In this situation, the token is signed by the primary signature. The key represented by the token is used to endorse/sign the primary message signature.

For the Input Message and/or Output Message, click the Message Parts button to specify which parts of the message need to be encrypted, signed, and/or required.

See the following section for more information on the options in the Message Parts dialog.

The Message Parts dialog appears. It should look like Figure 7–8.

Figure 7–8 Web Service Attributes Editor Page: Message Parts

Click in a checkbox to the right of the message part or element that you would like to sign, encrypt or require.
- Select Sign to specify the parts or elements of a message that require integrity protection (digital signature).
- Select Encrypt to specify the parts or elements of a message that require confidentiality (encryption).
- Select Require to specify the set of parts and/or elements that a message must contain.

Click Add Body to add a row for the message body.

This will only be necessary if the row has been removed.

Click Add Header to add a row for either a specific SOAP header part or for all SOAP header parts.

This will only be necessary if the SOAP header row in question has been deleted. The header parts that are available to sign and/or encrypt before clicking the Add Header button include To (Addressing), From (Addressing), FaultTo (Addressing), ReplyTo (Addressing), MessageID (Addressing), RelatesTo (Addressing), and Action (Addressing). After clicking Add Header, and then clicking All Headers, you may also specify AckRequested (RM), SequenceAcknowledgement (RM), and Sequence (RM).

There are no XPath elements displayed by default. Click Add XPath to add rows that enable you to specify signature and/or encryption for an XPath expression or a URI which indicates the version of XPath to use.

By default, the Required field is selected. This is an editable field. Double-click the XPath row to specify the XPath expression or URI. Only one XPath element is allowed.

Note –
There is a limitation when specifying XPath elements. To use XPath elements, switch off Optimize Security manually by adding the disableStreamingSecurity policy assertion. For information on how to do this, refer to http://blogs.sun.com/venu/ for more information on disableStreamingSecurity.

To remove an element, select it in the Message Part section, and then click Remove to remove it from message security.

Click OK to save these settings.

Supporting Token Options

You can use one of the following options for supporting tokens:

Username Token: A username token is used to identify the requestor by their username, and optionally using a password (or shared secret, or password equivalent) to authenticate that identity. When using a username token, the user must be configured on GlassFish. For information on configuring users on GlassFish, read Adding Users to GlassFish.
X.509 Certificate: An X.509 certificate specifies a binding between a public key and a set of attributes that includes (at least) a subject name, issuer name, serial number, and validity interval. An X.509 certificate may be used to validate a public key that may be used to authenticate a SOAP message or to identify the public key with a SOAP message that has been encrypted. When this option is selected, you must specify a truststore. For information on specifying a truststore, read To Configure the Truststore on a Service.
Issued Token: An issued token is a token issued by a trusted Secure Token Service (STS). The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate. The issued tokens contain a key, which is encrypted for the server and which is used for deriving new keys for signing and encrypting.
SAML Token: A SAML Token uses Security Assertion Markup Language (SAML) assertions as security tokens.

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

Endpoint:

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

WSDL Location: http://131.107.72.15//Security_Federation_SecurityTokenService_Indigo/Symmetric.svc?wsdl
```
http://131.107.72.15//Security_Federation_SecurityTokenService_Indigo/
Symmetric.svc?wsdl
```
Service Name: MySTSService
Port Name: CustomBinding_IMySTSService
Namespace: http://tempuri.org/

Example Applications

The following example applications demonstrate configuring web services and web service clients for different security mechanisms. If you are going to work through the examples sequentially, you must manually undo the changes to the service and then refresh the client in order for the client to receive the most recent version of the service’s WSDL file, which contains the latest security configuration information.

Example: Username Authentication with Symmetric Keys (UA)

The section describes the following tasks:

To Secure the Example Service Application (UA)

The following example application starts with the example provided in Chapter 3, WSIT Example Using a Web Container and NetBeans IDE and demonstrates adding security to both the web service and to the web service client.

For this example, the security mechanism of Username Authentication with Symmetric Keys is used to secure the application. To add security to the service part of the example, follow these steps.

If you haven’t already completed these steps, complete them now:
1. Update the GlassFish keystore and truststore files as described in To Update GlassFish Certificates.
2. Create a user on GlassFish as described in Adding Users to GlassFish.

Create the CalculatorApplication example by following the steps described in the following sections of Chapter 3, WSIT Example Using a Web Container and NetBeans IDE.
1. Creating a Web Service
2. Skip the section on adding Reliable Messaging.
3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)

Expand CalculatorApplication->Web Services, then right-click the node for the web service (CalculatorWS) and select Edit Web Service Attributes.

Deselect Reliable Messaging if it is selected.

In the CalculatorWSPortBinding section, select Secure Service.

From the drop-down list for Security Mechanism, select Username Authentication with Symmetric Keys.

Click the Keystore button to provide your keystore with the alias identifying the service certificate. To do this, click the Load Aliases button and select xws-security-server, then click OK to close the dialog.

Click OK to close the WSIT Configuration dialog.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore element.

An example of this file can be viewed in the tutorial by clicking this link: Service-Side WSIT Configuration Files.

Right-click the CalculatorApplication node and select Run Project. A browser will open and display the WSDL file for the application.

Verify that the WSDL file contains the following elements: SymmetricBinding and UsernameToken.

Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (UA).

To Secure the Example Web Service Client Application (UA)

This section demonstrates adding security to the web service client that references the web service created in the previous section. This web service is secured using the security mechanism described in Username Authentication with Symmetric Keys. When this security mechanism is used with a web service, the web service client must provide a username and password in addition to specifying the certificate of the server.

To add security to the client that references this web service, complete the following steps.

Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service.

Note –
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.

Expand the node for the web service client application, CalculatorWSServletClient.

Expand the node for Web Service References.

Right-click CalculatorWSService and select Edit Web Service Attributes.

Select the WSIT Configuration tab of the CalculatorWSService dialog.

For this testing environment, provide a default username and password. To do this, follow these steps:
1. Expand the Username Authentication node.
2. Type the username and password that you created on GlassFish into the Default Username and Default Password fields. If you followed the steps in the section Adding Users to GlassFish, the user name is wsitUser and the password is changeit.
Note –
In a production environment, you should configure a Username Handler and a Password Handler class to eliminate the security risk associated with the default username and password options.

Provide the server’s certificate by pointing to an alias in the client truststore. To do this, select the Certificates node, click the Load Aliases button for the Truststore, then select xws-security-server from the Truststore Alias list.

Click OK to close this dialog.

In the tree, drill down from the project to Source Packages->META-INF. Double-click on CalculatorWSService.xml, and verify that lines similar to the following are present:

<wsp:All>
  <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
  <sc:CallbackHandlerConfiguration wspp:visibility="private">
    <sc:CallbackHandler default="wsitUser" name="usernameHandler"/>
    <sc:CallbackHandler default="changeit" name="passwordHandler"/>
  </sc:CallbackHandlerConfiguration>
  <sc:TrustStore wspp:visibility="private" 
      location="home\glassfish\domains\domain1\config\cacerts.jks"
      storepass="changeit" peeralias="xws-security-server"/>
</wsp:All>

An example of this file can be viewed in the tutorial by clicking this link: Client-Side WSIT Configuration Files.

Right-click the CalculatorWSServletClient node and select Run Project.

Example: Mutual Certificates Security (MCS)

The section describes the following tasks:

To Secure the Example Service Application (MCS)

For this example, the security mechanism of Mutual Certificates Security is used to secure the application. To add security to the service part of the example, follow these steps.

If you haven’t already done so, update the GlassFish keystore and truststore files as described in To Update GlassFish Certificates.

Create the CalculatorApplication example by following the steps described in the following sections of Chapter 3, WSIT Example Using a Web Container and NetBeans IDE.
1. Creating a Web Service
2. Skip the section on adding Reliable Messaging.
3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)

Expand CalculatorApplication->Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.

Deselect Reliable Messaging if it is selected.

Select Secure Service.

From the drop-down list for Security Mechanism, select Mutual Certificates Security.

Click the Keystore button, then click the Load Aliases button and select xws-security-server. Click OK to close the dialog.

Click OK to close the WSIT Configuration dialog.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore element.

Right-click the CalculatorApplication node and select Run Project.

A browser will open and display the WSDL file for the application.

Verify that the WSDL file contains the AsymmetricBinding element.

Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (MCS).

To Secure the Example Web Service Client Application (MCS)

To add security to the client that references this web service, complete the following steps.

Create the client application following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service.

Note –
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.

Expand the node for the web service client, CalculatorWSServletClient.

Expand the node for Web Service References.

Right-click CalculatorWSService and select Edit Web Service Attributes.

Select the WSIT Configuration tab of the CalculatorWSService dialog.

Provide the client’s private key by pointing to an alias in the keystore. To do this, expand the Certificates node, click the Load Aliases button for the keystore, then select xws-security-client from the Alias list.

Provide the server’s certificate by pointing to an alias in the client truststore. To do this, from the Certificates node, click the Load Aliases button for the truststore and select xws-security-server from the Alias list. Click OK to close this dialog.

In the tree, drill down from the project to Source Packages->META-INF. Double-click on CalculatorWSService.xml, and verify that lines similar to the following are present:

<wsp:All>
  <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
  <sc:KeyStore wspp:visibility="private" 
    location="C:\Sun\glassfish\domains\domain1\config\keystore.jks"
    storepass="changeit" alias="xws-security-server" keypass="changeit"/>
  <sc:TrustStore wspp:visibility="private" 
    location="C:\Sun\glassfish\domains\domain1\config\cacerts.jks"
    storepass="changeit" peeralias="xws-security-server"/>
</wsp:All>

Compile and run this application by right-clicking the CalculatorWSServletClient node and selecting Run Project.

Example: Transport Security (SSL)

This section describes the following tasks:

To Secure the Example Service Application (SSL)

The following example application starts with the example provided in Chapter 3, WSIT Example Using a Web Container and NetBeans IDE and demonstrates adding transport security to both the web service and to the web service client.

For this example, the security mechanism of Transport Security (SSL) is used to secure the application. To add security to the service part of the example, follow these steps.

Create the CalculatorApplication example by following the steps described in the following sections of Chapter 3, WSIT Example Using a Web Container and NetBeans IDE:
1. Creating a Web Service
2. Skip the section on adding Reliable Messaging.
3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)

Expand CalculatorApplication->Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.

Deselect Reliable Messaging if it is selected.

Select Secure Service.

From the drop-down list for Security Mechanism, select Transport Security (SSL).

Click OK to close the WSIT Configuration dialog.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml.

Note –
For Transport Security, the keystore and truststore files are configured outside of NetBeans IDE, in GlassFish. The keystore and truststore files for basic SSL come pre-configured with GlassFish, so there are no additional steps required for this configuration.

To require the service to use the HTTPS protocol, you have to specify the security requirements in the service’s application deployment descriptor, which is web.xml for a web service implemented as a servlet.

To specify the security information, follow these steps:
1. From your web service application, expand Web Pages->WEB-INF.
2. Double-click web.xml to open it in the editor.
3. Select the Security tab.
4. On the Security Constraints line, click Add Security Constraint.
5. Under Web Resource Collection, click Add.
6. Type a Name for the Resource, CalcWebResource. Type the URL Pattern to be protected, /*. Select which HTTP Methods to protect, for example, POST. Click OK to close this dialog.
7. Check the Enable User Data Constraint box. Select CONFIDENTIAL as the Transport Guarantee to specify that the application uses SSL.
8. Click the XML tab to view the resulting deployment descriptor additions.

Right-click the CalculatorApplication node and select Run Project. If the server presents its certificate, s1as, accept this certificate. A browser will open and display the WSDL file for the application.

Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (SSL).

To Secure the Example Web Service Client Application (SSL)

To add security to the client that references this web service, complete the following steps.

Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service, with the exception that you need to specify the secure WSDL when creating the Web Service Client.

To do this, create the client application up to the step where you create the Servlet (step 7 as of this writing) by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service, with the following exception.

In the step where you are directed to cut and paste the URL of the web service that you want the client to consume into the WSDL URL field, type https://fully-qualified-hostname:8181/CalculatorApplication/CalculatorWSService?wsdl (changes indicated in bold) to indicate that this client should reference the web service using the secure port. The first time you access this service, accept the certificate (s1as) when you are prompted. This is the server certificate popping up to confirm its identity to the client.

In some cases, you might get an error dialog telling you that the URL https://fully-qualified-hostname:8181/CalculatorApplication/CalculatorWSService?wsdl couldn’t be downloaded. However, this the correct URL, and it does load when you run the service. So, when this error occurs, repeat the steps that create the Web Service Client using the secure WSDL. The second time, the web service reference is created and you can continue creating the client.

Note –
If you prefer to use localhost in place of the fully-qualified hostname (FQHN) in this example, you must follow the steps in Transport Security (SSL) Workaround.

Continue creating the client following the remainder of the instructions in Creating a Client to Consume a WSIT-Enabled Web Service.

Note –
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.

Compile and run this application by right-clicking on the CalculatorWSServletClient node and selecting Run Project.

Example: SAML Authorization over SSL (SA)

This section describes the following tasks:

To Secure the Example Service Application (SA)

For this example, the security mechanism of SAML Authorization over SSL is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Keys (UA), with the addition of the writing of a client-side SAML callback handler to populate the client’s request with a SAML assertion.

To add security to the service part of the example, follow these steps.

If you haven’t already completed these steps, complete them now:
1. Update the GlassFish keystore and truststore files as described in To Update GlassFish Certificates.
2. Create a user on GlassFish as described in Adding Users to GlassFish.

Create the CalculatorApplication example by following the steps described in the following sections of Chapter 3, WSIT Example Using a Web Container and NetBeans IDE:
1. Creating a Web Service
2. Skip the section on adding Reliable Messaging.
3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)

Expand CalculatorApplication->Web Services, right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.

Deselect the Reliable Messaging option if it is selected.

Select Secure Service.

From the drop-down list for Security Mechanism, select SAML Authorization over SSL.

Click the Keystore button to provide your keystore with the alias identifying the service certificate and private key. To do this, click the Load Aliases button and select xws-security-server, then click OK to close the dialog.

For this example, the Truststore information that you need is specified by default, so there is no need to change these settings.

Click OK to exit the WSIT Configuration editor.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore and sc:Truststore elements.

To require the service to use SSL, you have to specify the security requirements in the service’s application deployment descriptor, which is web.xml for a web service implemented as a servlet. To specify the security information, follow these steps:
1. From your web service application expand Web Pages->WEB-INF.
2. Double-click web.xml to open it in the editor.
3. Select the Security tab.
4. On the Security Constraints line, click Add Security Constraint.
5. Under Web Resource Collection, click Add.
6. Type a Name for the Resource, CalcWebResource. Type the URL Pattern to be protected, /*. Select which HTTP Methods to protect, for example, POST. Click OK to close this dialog.
7. Check the Enable User Data Constraint box. Select CONFIDENTIAL as the Transport Guarantee to specify that the application uses SSL.
8. Click the XML tab to view the resulting deployment descriptor additions.

Right-click the CalculatorApplication node and select Run Project. Accept the s1as certificate if you are prompted to. A browser will open and display the WSDL file for the application.

Verify that the WSDL file contains the TransportBinding and SignedSupportingTokens element, which in turn contains a SamlToken element.

Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (SA).

To Secure the Example Web Service Client Application (SA)

To add security to the client that references this web service, complete the following steps.

This example uses a non-JSR-109-compliant client for variety. To do this, create the client application up to the step where you create the Servlet (step 7 as of this writing) by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service, with the following exceptions:
1. In the step where you are directed to cut and paste the URL of the web service that you want the client to consume into the WSDL URL field, type https://fully-qualified-hostname:8181/CalculatorApplication/CalculatorWSService?wsdl, to indicate that this client should reference the web service using the secure port.
  
  The first time you access this service, accept the certificate (s1as) when you are prompted. This is the server certificate popping up to confirm its identity to the client.
  
  In some cases, you might get an error dialog telling you that the URL https://fully-qualified-hostname:8181/CalculatorApplication/CalculatorWSService?wsdl couldn’t be downloaded. However, this the correct URL, and it does load when you run the service. So, when this error occurs, repeat the steps that create the Web Service Client using the secure WSDL. The second time, the web service reference is created and you can continue creating the client.
  
  Note –
  If you prefer to use localhost in place of the fully-qualified hostname (FQHN) in this example, you must follow the steps in Transport Security (SSL) Workaround.
2. Name the application CalculatorClient (since it’s not a servlet.).

Instead of creating a client servlet as is described in Creating a Client to Consume a WSIT-Enabled Web Service, just add the web service operation to the generated index.jsp file to create a non-JSR-109 client. To do this, perform these steps:
1. If the index.jsp file is not open in the right pane, double-click it to open it.
2. Drill down through the Web Service References node until you get to the add operation.
3. Drag the add operation to the line immediately following the following line:
```
<h1>JSP Page</h1>
```
4. Edit the values for i and j if you’d like.

Write a SAMLCallback handler for the client side to populate a SAML assertion into the client’s request to the service.

To create the SAMLCallbackHandler, follow these steps:
1. Right-click the CalculatorClient node.
2. Select New->Java Package.
3. For Package Name, type xwss.saml and click Finish.
4. Drill down from CalculatorClient->Source Packages->xwss.saml.
5. Right-click xwss.saml and select New->File/Folder.
6. From the Categories list, select Java Classes.
7. From the File Types list, select Empty Java File and click Next.
8. For Class Name, type SamlCallbackHandler and click Finish.
  
  The empty file appears in the IDE.
9. Download the example file SamlCallbackHandler.java from the following URL:
  
  https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645[amp ]expandFolder=6645[amp ]folderID=6645
10. Open the file in a text editor.
11. Modify the home variable to provide the hard-coded path to your GlassFish installation.
  
  For example, modify the line:
```
        String home = System.getProperty("WSIT_HOME");
```
  to
```
        String home = "/home/glassfish";
```
12. Copy the contents of this file into the SamlCallbackHandler.java window that is displaying in the IDE.

Drill down from CalculatorClient->Web Service References.

Right-click CalculatorWSService and select Edit Web Service Attributes.

Select the WSIT Configuration tab of the CalculatorWSService dialog.

Provide the client’s private key by pointing to an alias in the keystore. To do this, expand the Certificates node, click the Load Aliases button for the keystore, and select xws-security-client from the Alias list.

Note –
If you are using a certificate other than the updated GlassFish certificates described in To Update GlassFish Certificates, or are otherwise using a different alias for the client’s private key alias, correct the private key alias in the line in the SAMLCallbackHandler.java file that looks like this:
```
String client_priv_key_alias="xws-security-client";
```
If you are using different keystore/truststore files than those described in To Update GlassFish Certificates, edit the following code in the SAMLCallbackHandler.java file accordingly:
```
this.keyStoreURL = home + fileSeparator + "domains" +
  fileSeparator + fileSeparator + "config" + "domain1" +
  fileSeparator + "keystore.jks";
this.keyStoreType = "JKS";
this.keyStorePassword = "changeit";
this.trustStoreURL = home + fileSeparator + "domains" +
  fileSeparator + "domain1" + fileSeparator + "config" +
  fileSeparator + "cacerts.jks";
this.trustStoreType = "JKS";
this.trustStorePassword = "changeit";
```

Provide the server’s certificate by pointing to an alias in the client truststore. To do this, from the Certificates node, click the Load Aliases button for the Truststore and select xws-security-server.

Expand the Username Authentication node. In the SAML Callback Handler field, type the name of the class written in step 3 above, xwss.saml.SamlCallbackHandler.

Click OK to close this dialog.

In the tree, drill down from the project to Source Packages->META-INF. Double-click CalculatorWSService.xml, and verify that lines similar to the following are present, where xwss.saml.SamlCallbackHandler is the SAML Callback Handler class for the client:

<wsp:All>
  <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
  <sc:CallbackHandlerConfiguration wspp:visibility="private">
    <sc:CallbackHandler name="samlHandler" classname="xwss.saml.SamlCallbackHandler"/>
  </sc:CallbackHandlerConfiguration>
  <sc:KeyStore wspp:visibility="private" 
    location="as-install\domains\domain1\config\keystore.jks"
    storepass="changeit" alias="xws-security-client" keypass="changeit"/>
  <sc:TrustStore wspp:visibility="private" 
    location="as-install\domains\domain1\config\cacerts.jks"
    storepass="changeit" peeralias="xws-security-server"/>
</wsp:All>

Compile and run this application by right-clicking the CalculatorClient node and selecting Run Project.

Example: SAML Sender Vouches with Certificates (SV)

This section describes the following tasks:

To Secure the Example Service Application (SV)

For this example, the security mechanism of SAML Sender Vouches with Certificates is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Keys (UA), with the addition of the writing of a client-side SAML callback handler to populate the client’s request with a SAML assertion.

To add security to the service part of the example, follow these steps.

If you haven’t already completed these steps, complete them now:
1. Update the GlassFish keystore and truststore files as described in To Update GlassFish Certificates.
2. Create a user on GlassFish as described in Adding Users to GlassFish.

Create the CalculatorApplication example by following the steps described in the following sections of Chapter 3, WSIT Example Using a Web Container and NetBeans IDE:
1. Creating a Web Service
2. Skip the section on adding Reliable Messaging.
3. Deploying and Testing a Web Service (first two steps only, do not run the project yet)

Expand CalculatorApplication->Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.

Deselect the Reliable Messaging option if it is selected.

Select Secure Service.

From the drop-down list for Security Mechanism, select SAML Sender Vouches with Certificates.

Click the Keystore button to provide your keystore with the alias identifying the service certificate and private key. To do this, click the Load Aliases button and select xws-security-server, then click OK to close the dialog.

For this example, the Truststore information that you need is specified by default, so there is no need to change these settings.

Click OK to exit the WSIT Configuration editor.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml. This file contains the sc:KeyStore and sc:Truststore elements.

Right-click the CalculatorApplication node and select Run Project. Accept the s1as certificate if you are prompted to.

A browser will open and display the WSDL file for the application.

Verify that the WSDL file contains the TransportBinding and SignedSupportingTokens element, which in turn contains a SamlToken element.

Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (SV).

To Secure the Example Web Service Client Application (SV)

To add security to the client that references this web service, complete the following steps.

This example uses a non-JSR-109-compliant client. To do this, create the client application up to the step where you create the Servlet (step 7 as of this writing) by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service, with one exception: name the application CalculatorClient (since it’s not a servlet.).

Instead of creating a client servlet as is described in Creating a Client to Consume a WSIT-Enabled Web Service, just add the web service operation to the generated index.jsp file to create a non-JSR-109 client. To do this, follow these steps:
1. If the index.jsp file is not open in the right pane, double-click it to open it.
2. Drill down through the Web Service References node until you get to the add operation.
3. Drag the add operation to the line immediately following the following line:
```
    <h1>JSP Page</h1>
```
4. Edit the values for i and j if you’d like.

Write a SAMLCallback handler for the client side to populate a SAML assertion into the client’s request to the service.

To create the SAMLCallbackHandler, follow these steps:
1. Right-click the CalculatorClient node and select New->Java Package.
2. For Package Name, type xwss.saml, then click Finish.
3. Drill down from CalculatorClient->Source Packages->xwss.saml.
4. Right-click xwss.saml and select New->File/Folder.
5. From the Categories list, select Java Classes.
6. From the File Types list, select Empty Java File and click Next.
7. For Class Name, type SamlCallbackHandler, then click Finish.
  
  The empty file appears in the IDE.
8. Download the example file SamlCallbackHandler.java from the following URL: https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645[amp ]expandFolder=6645[amp ]folderID=6645
9. Open the file in a text editor.
10. Modify the home variable to provide the hard-coded path to your GlassFish installation. For example, modify the line:
```
        String home = System.getProperty("WSIT_HOME");
```
  to
```
        String home = "/home/glassfish";
```
11. Set the subject confirmation method to SV (Sender Vouches). For more information on this topic, read Example SAML Callback Handlers.
12. Copy the contents of this file into the SamlCallbackHandler.java window that is displaying in the IDE.

Drill down from CalculatorClient->Web Service References.

Right-click on CalculatorWSService and select Edit Web Service Attributes.

Select the WSIT Configuration tab of the CalculatorWSService dialog.

Provide the client’s private key by pointing to an alias in the keystore. To do this, expand the Certificates node, click the Load Aliases button for the keystore, then select xws-security-client from the Alias list.

Provide the server’s certificate by pointing to an alias in the client truststore. To do this, from the Certificates node, click the Load Aliases button for the Truststore and select xws-security-server.

Expand the Username Authentication node. In the SAML Callback Handler field, type the name of the class written in step 3 above, xwss.saml.SamlCallbackHandler.

Click OK to close this dialog.

In the tree, drill down from the project to Source Packages->META-INF. Double-click CalculatorWSService.xml, and verify that lines similar to the following are present, where xwss.saml.SamlCallbackHandler is the SAML Callback Handler class for the client:

<wsp:All>
  <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
  <sc:CallbackHandlerConfiguration wspp:visibility="private">
    <sc:CallbackHandler name="samlHandler" classname="xwss.saml.SamlCallbackHandler"/>
  </sc:CallbackHandlerConfiguration>
  <sc:KeyStore wspp:visibility="private" 
    location="as-install\domains\domain1\config\keystore.jks"
    storepass="changeit" alias="xws-security-client" keypass="changeit"/>
  <sc:TrustStore wspp:visibility="private" 
    location="as-install\domains\domain1\config\cacerts.jks"
    storepass="changeit" peeralias="xws-security-server"/>
</wsp:All>

Compile and run this application by right-clicking the CalculatorClient node and selecting Run Project.

Example: STS Issued Token (STS)

This section describes the following tasks:

Another STS example application can be found at the following URL: https://wsit.dev.java.net/source/browse/wsit/wsit/samples/ws-trust/.

To Secure the Example Service Application (STS)

For this example, the security mechanism of STS Issued Token is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Keys (UA), with the addition of creating and securing an STS.

To add security to the service part of the example, follow these steps.

Create a user on GlassFish if you haven’t already done so. (see Adding Users to GlassFish).

Create the CalculatorApplication example by following the steps described in the following sections of Chapter 3, WSIT Example Using a Web Container and NetBeans IDE.
1. Creating a Web Service
2. Skip the section on adding Reliable Messaging.
3. Deploying and Testing a Web Service (first two steps only, do not run the project yet).

Expand CalculatorApplication->Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.

Deselect the Reliable Messaging option if it is selected.

Select Secure Service.

From the drop-down list for Security Mechanism, select STS Issued Token.

Select the Configure button. For Algorithm Suite, select Basic128 bit. For Key Size, select 128. Select OK to close the configuration dialog (the algorithm suite value of the service must match the algorithm suite value of the STS.)

Note –
If you have configured Unlimited Strength Encryption as described in To Create a Third-Party STS, you can leave the key size at 256. Otherwise, you must set it to 128.

Click OK to exit the WSIT Configuration editor.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml.

Right-click the CalculatorApplication node and select Run Project. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.

Next Steps

Follow the steps for creating and securing the Security Token Service as described in To Create and Secure the STS (STS).

To Create and Secure the STS (STS)

To create and secure a Security Token Service for this example, follow these steps.

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

Select Web, then Web Application, then Next.

Type MySTSProject for the Project Name, then click Finish.

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

Select Web Services from the Categories list.

Select Secure Token Service (STS) from the File Type(s) list, then click Next.

Type the name MySTS for the Web Service Class Name.

Select org.me.my.sts from the Package list, then click Finish.

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

The STS wizard creates an empty implementation of the provider class. Implement the provider implementation class by copying the following code into the MySTS.java file.

Add these import statements to the list of imports:

    import com.sun.xml.ws.security.trust.sts.BaseSTSImpl;
    import javax.annotation.Resource;
    import javax.xml.ws.Provider;
    import javax.xml.ws.Service;
    import javax.xml.ws.ServiceMode;
    import javax.xml.ws.WebServiceContext;
    import javax.xml.ws.WebServiceProvider;
    import javax.xml.transform.Source;
    import javax.xml.ws.handler.MessageContext;

Add the following Resource annotation after the line public class MySTS implements javax.xml.ws.Provider<Source> {:
```
    @Resource protected WebServiceContext context;
```

Change the following line of code:

    public class MySTS implements
        javax.xml.ws.Provider<Source>

to:

    public class MySTS extends BaseSTSImpl implements
        javax.xml.ws.Provider<Source>

For the invoke method, replace the return null line with the following return statement:
```
    return super.invoke(source);
```

Add the following method after the invoke method:

    protected MessageContext getMessageContext() {
         MessageContext msgCtx = context.getMessageContext();
         return msgCtx;
    }

Back in the Projects window, expand the MySTSProject node, then expand the Web Services node. Right-click the MySTSService[IMySTSService_Port] node and select Edit Web Service Attributes to configure the STS.

Select Secure Service if it’s not already selected.

Verify that the Security Mechanism of Username Authentication with Symmetric Keys is selected.

Select the Configure button. For Algorithm Suite, verify that Basic128 bit is selected (so that it matches the value selected for the service.) For the Key Size, verify that 128 is selected. Select OK to close the configuration dialog.

Select Act as Secure Token Service (STS), then click OK to close the Select STS Service Provider dialog.

Click the Keystore button to provide your keystore with the alias identifying the service certificate and private key. To do this, click the Load Aliases button, select wssip, then click OK to close the dialog.

Click OK to close the WSIT Configuration dialog.

A new file is added to the project. To view the WSIT configuration file, expand Web Pages->WEB-INF->wsdl->MySTS, then double-click the file MySTSService.wsdl. This file contains the sc:KeyStore element.

Right-click the MySTSProject tab, select Properties. Select the Run category, and type the following in the Relative URL field: /MySTSService?wsdl.

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

The STS WSDL appears in the browser.

Next Steps

Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (STS).

To Secure the Example Web Service Client Application (STS)

This section demonstrates adding security to the CalculatorApplication’s web service client, which was secured using the security mechanism described in STS Issued Token.

To add security to the client, complete the following steps.

Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service.

Note –
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.

Drill down from CalculatorWSServletClient->Web Service References.

Right-click CalculatorWSService and select Edit Web Service Attributes, then select the WSIT Configuration tab.

Provide the client’s private key by pointing to an alias in the keystore. To do this, expand the Certificates node, click the Load Aliases button for the keystore, and select xws-security-client from the Alias list.

Provide the service’s certificate by pointing to an alias in the client truststore. To do this, from the Certificates node, click the Load Aliases button for the truststore and select xws-security-server from the Alias list.

Expand the Security Token Service node to provide details for the STS to be used. When the Endpoint and the Metadata values are the same, you only need to enter the Endpoint value. For the Endpoint field, type the following value:
http://localhost:8080/MySTSProject/MySTSService

Click OK to close this dialog.

The service requires a token to be issued from the STS at http://localhost:8080/MySTSProject/MySTSService, with WSDL file http://localhost:8080/MySTSProject/MySTSService?wsdl. To do this, follow these steps:
1. Right-click the CalculatorWSServletClient node and select New->Web Service Client.
  
  The New Web Service Client window appears.
2. Select the WSDL URL option.
3. Cut and paste the URL of the web service that you want the client to consume into the WSDL URL field. For example, here is the URL for the MySTS web service:
  http://localhost:8080/MySTSProject/MySTSService?wsdl
4. Type org.me.calculator.client.sts in the Package field, then click Finish.
  
  The Projects window displays the new web service client.

Drill down from CalculatorWSServletClient->Web Service References.

Right-click MySTSService and select Edit Web Service Attributes.

Select the WSIT Configuration tab of the MySTSService dialog.

Provide the client’s private key by pointing to an alias in the keystore. To do this, expand the Certificates node, click the Load Aliases button for the keystore, and select xws-security-client from the Alias list.

Verify the STS’s certificate by pointing to an alias in the client truststore. To do this, from the Certificates node, click the Load Aliases button and select wssip from the Alias list.

Expand the Username Authentication node and verify that the default user name and password as specified in GlassFish.

If you followed the steps in Adding Users to GlassFish, this will be User Name wsitUser and Password changeit.

Click OK to close this dialog.

Compile and run this application by right-clicking the CalculatorWSServletClient project and selecting Run Project.

Further Information

For more information on securing web applications using WSIT, visit the Project Tango web site at https://wsit.dev.java.net/. On this page, you will find information about the specifications implemented in this product, source code, support information, links to documentation updates, and much more.

Some other sources that contain blogs and/or screencasts about using WSIT include the following:

Sun WSIT Bloggers:

http://planet.sun.com/webservices/group/blogs/
Project Tango: An Overview:

https://wsit.dev.java.net/docs/tango-overview.pdf
Web Services blog:

http://blogs.sun.com/arungupta/category/webservices
Manual Web Service Configuration In From Java Case (and others):

http://blogs.sun.com/japod/date/20070226
Develop WSTrust Application Using NetBeans (and others):

http://blogs.sun.com/shyamrao/
Security in WSIT (and others):

http://blogs.sun.com/ashutosh/
WSIT Screencasts:

https://metro.dev.java.net/discover/screencasts.htm
Specifications Implemented by WSIT:

https://wsit.dev.java.net/specification-links.html

Chapter 7 Using WSIT Security

Configuring Security Using NetBeans IDE

To Secure the Service

Figure 7–1 Web Service Attributes Editor Page

Next Steps

To Secure the Client

Figure 7–2 Web Service References Attributes Editor Page for Web Service Clients

Next Steps

Summary of Configuration Requirements

Summary of Service-Side Configuration Requirements

Summary of Client-Side Configuration Requirements

Configuring Username Authentication on the Client

To Configure Username Authentication on the Client

Figure 7–3 WSIT Configuration - Client - Username Authentication

Example SAML Callback Handlers

Security Mechanisms

Username Authentication with Symmetric Keys

Mutual Certificates Security

Transport Security (SSL)

Transport Security (SSL) Workaround

Message Authentication over SSL

SAML Authorization over SSL

Endorsing Certificate

SAML Sender Vouches with Certificates

SAML Holder of Key

STS Issued Token

STS Issued Token with Service Certificate

STS Issued Endorsing Token

Configuring SSL and Authorized Users

Configuring SSL For Your Applications

To Configure SSL for Your Application

Figure 7–4 Deployment Descriptor Page

Adding Users to GlassFish

To Add Users to GlassFish Using the Admin Console

To Add Users to GlassFish From the Command Line

Configuring Keystores and Truststores

To Update GlassFish Certificates

Specifying Aliases with the Updated Stores

Configuring the Keystore and Truststore

To Configure the Keystore on a Service

Figure 7–5 Keystore Configuration Dialog

To Configure the Truststore on a Service

To Configure the Keystore and Truststore on a Client

Figure 7–6 Client-side Certificate Configuration Dialog

Configuring Validators

To Set Validator Configuration Options

Securing Operations and Messages

To Specify Security at the Operation, Input Message, or Output Message Level

Figure 7–7 Web Service Attributes Editor Page: Operation Level

Figure 7–8 Web Service Attributes Editor Page: Message Parts

Supporting Token Options

Configuring A Secure Token Service (STS)

To Create a Third-Party STS

To Specify an STS on the Service Side

To Specify an STS on the Client Side

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

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

Example Applications

Example: Username Authentication with Symmetric Keys (UA)

To Secure the Example Service Application (UA)

To Secure the Example Web Service Client Application (UA)

Example: Mutual Certificates Security (MCS)

To Secure the Example Service Application (MCS)

To Secure the Example Web Service Client Application (MCS)

Example: Transport Security (SSL)

To Secure the Example Service Application (SSL)

To Secure the Example Web Service Client Application (SSL)

Example: SAML Authorization over SSL (SA)

To Secure the Example Service Application (SA)

To Secure the Example Web Service Client Application (SA)

Example: SAML Sender Vouches with Certificates (SV)

To Secure the Example Service Application (SV)

To Secure the Example Web Service Client Application (SV)

Example: STS Issued Token (STS)

To Secure the Example Service Application (STS)

Next Steps

To Create and Secure the STS (STS)

Next Steps