Chapter 12. Using WSIT Security

Create or open your web service.
If you need an example of how to create a web service, refer to Developing with NetBeans.
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 Quality of Service options appear (see Web Service Attributes Editor Page).
Figure 12.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.
Choose 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.
Select Use Development Defaults.
Select this option to import certificates into the GlassFish keystore and truststore so that they can be used immediately for development. 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. In order to use message security mechanisms with GlassFish, it is necessary to obtain keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.
In addition to importing certificates, when this option is selected a default user is created in the file realm with username wsitUser.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
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 Summary of Service-Side Configuration Requirements . 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.
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.

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 CalculatorWSService 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 Quality of Service tab to display the security options (see Web Service References Attributes Editor Page for Web Service Clients ).
Figure 12.2. Web Service References Attributes Editor Page for Web Service Clients
Select Use Development Defaults.
Refer to Summary of Client-Side Configuration Requirements 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 security configuration information is saved in two files under Source Packages/META-INF. For more information on the format and runtime usage of these files, see Client-Side WSIT Configuration Files .

12.2. 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:

12.2.1. Summary of Service-Side Configuration Requirements

Summary of Service-Side Configuration Requirements summarizes the options that need to be configured for each security mechanism. Each of the columns is briefly discussed after the table.

Table 12.1. Summary of Service-Side Configuration Requirements

Mechanism	Keystore	Truststore	STS	SSL	User in GlassFish	Kerberos
Username Authentication with Symmetric Key	X				X
Username Authentication with Password Derived Keys					X
Mutual Certificates	X	X (no alias)
Symmetric Binding with Kerberos Tokens						X
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
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, select Use Development Defaults, or 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.
Truststore : If this column has an X, select Use Development Defaults, or 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.
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. Select Use Development Defaults, or follow the instructions for doing this at Adding Users to GlassFish .
Kerberos : This option is only valid for 'Symmetri Binding with Kerberos Tokens' Profile. Click the Kerbeos button to specify the login module to be used for this service. Login Modules can be specified in $GLASSFISH_HOME/domains/domain1/config/login.conf for Glassfish. An example showing use of Kerberos Tokens can be found at Example: Kerberos Token (Kerb).

12.2.2. Summary of Client-Side Configuration Requirements

Summary of Client-Side Configuration Requirements 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 12.2. Summary of Client-Side Configuration Requirements

Mechanism	Keystore	Truststore	Default User	SAML Callback Handler	STS	SSL	User in GlassFish	Kerberos
Username Authentication with Symmetric Key		X	X				X
Username Authentication with Password Derived Keys			X				X
Mutual Certificates	X	X
Symmetric Binding with Kerberos Tokens								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, select Use Development Defaults, or click Keystore to 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.
Truststore: If this column has an X, select Use Development Defaults, or click Truststore to 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 Manually 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 sectionTo 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. Note that on the service side, it is optionally to set Issuer for the STS to be used. You only need to configure the STS information on the client side if Issuer if not available in the service wsdl. If both configured, the service side Issuer takes high priority.
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, select Use Development Defaults, or add a user to the file realm of GlassFish. Instructions for doing this can be found at Adding Users to GlassFish.
Kerberos: This option is only valid for 'Symmetric Binding with Kerberos Tokens' profile. Click Kerberos button to configure the Login Module and Service Principal to be used by client, and if credential delegation should be set. An example showing use of Kerberos Tokens can be found at Example: Kerberos Token (Kerb).

12.2.2.1. 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 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 Quality of Service tab to display the WSIT Security options.
Expand the Security section to specify the user name and password information as required by the service. The dialog appears as shown in Quality of Service - Client - Security.
Figure 12.3. Quality of Service - Client - Security
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.
- Use Development Defaults:
  Select this option to import certificates into the GlassFish keystore and truststore so that they can be used immediately for development. 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. In order to use message security mechanisms with GlassFish, it is necessary to obtain keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.
  In addition to importing certificates, when this option is selected a default user is created in the file realm with username wsitUser.
  In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
- Authentication Credentials: Select Static or Dynamic. Select Static to supply a static username and password, or select Dynamic and specify the Username and Password CallbackHandlers. Select Static if you want to fill in the exact user credentials that the client is providing, and which cannot be changed after deployment. Static is useful to developing and testing applications prior to deployment. Select Dynamic to use CallbackHandlers to provide a dynamic way to provide credentials. Dynamic is useful if the credentials need to be obtained from some third party, for example, or if the developer doesn't want to store the user name and password in a configuration file because it might introduce a security risk.
- Default Username, Default Password : These options are available when Static is selected as the Authentication Credential. 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.
- Default Username Callback Handler, Default Password Callback Handler : These options are available when the Authentication Credential is Dynamic. If you create JSR-109-compliant web services and web service clients that run under an Application Server container (JSR-109 deployment), the container handles the callbacks and you do not need to configure Callback Handlers of your own. If you are using another container, select the Browse button to select the class implementing the javax.security.auth.callback.CallbackHandler interface.
- 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).
- Timestamp Timeout: This property specifies the duration(in seconds) for which timestamp should be considered valid. The default is 5 mins(300 seconds).

12.2.2.2. 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:
http://java.net/projects/wsit/sources/svn/content/trunk/wsit/tests/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:
http://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&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. When the subject confirmation method is HOK, a keystore and truststore file must be configured in the SAMLCallbackHandler. When the method is SV, you can either comment out the keystore and truststore information, or leave it, as it will not be used.

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.

Example 12.1.

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;
}

12.3. Security Mechanisms

This section describes security mechanisms you can implement with WSIT. This section provides an overview of the following mechanisms:

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.

12.3.1. Username Authentication with Symmetric Key

The Username Authentication with Symmetric Key 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.

12.3.2. Username Authentication with Password Derived Keys

This feature is same as "Username Authentication with Symmetric Key", except that the protection token is Username Token.This feature relies on a single, shared secret key that is derived using password, salt(a 16 byte random array),iterations(an int value).This key will be used for signing and encrypting a message.

For this mechanism, the client does not need to have any certificate/key of his own.A 160 bit secret key will be generated using password,salt and iterations. This secret key will be used for signature/encryption. In the request the username,salt and iterations will be send to the server.The server generates the same key using the password(which it already has),salt and iterations. Using this key the server is able to decrypt the message and verify the signature.The default value for iterations is 1000.Current Netbeans versions doesn't show this feature in the security features list.So for a detailed explanation about this feature and to know how to configure this , please visit the blog: http://blogs.sun.com/SureshMandalapu/entry/passwordderivedkeys_support_in_metro

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

12.3.4. Symmetric Binding with Kerberos Tokens

Symmetric Binding with Kerberos Tokens does client authentication using Kerberos Tokens and integrity and confidentiality protection using symmetric keys generated with Kerberos V5 Protocol. This profile assumes that Kerberos authentication is supported by the underlying platform and a KDC is configured. When using Kerberos Tokens Profile, a Login Module must be configured for the service, and a Login Module and Service Principal must be specified for the client.

Note

Kerberos is supported in Metro since 1.1 release. Netbeans support is available for Kerberos from Metro 1.3 and Netbeans 6.5 release. Kerberos is NOT supported on AIX systems.

12.3.5. 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 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 Manually Update GlassFish Certificates.

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

12.3.5.1. 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:

Example 12.2.

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.

Example 12.3.

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.

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

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

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

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

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

12.3.11. 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 http://wsit.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.

12.3.12. 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 Unhandled tag caution used by a client to authenticate the service and provide message protection. For GlassFish, a default certificate of s1as is installed.

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

12.4. 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 Manually 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:

12.4.1. 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, andSAML 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 Manually 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.
Service Configuration
To require the service to use the HTTPS protocol, you must select a security mechanism that uses SSL (as described in a previous step), and 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, expand the node for SSL transport for CalculatorWSService. This will display when a security mechanism that requires SSL is selected. This constraint will be sufficient for the example applications. This sections walks you through making some changes in the event that you would like to customize the security constraint for your application.
5. Under Web Resource Collection, click Edit.
6. Change the URL Pattern to be protected (for example, /* ). Select which HTTP Methods to protect, for example, POST. Click OK to close this dialog.
7. Unselect Enable Authentication Constraint. Ensure that the Enable User Data Constraint box is checked. Verify that CONFIDENTIAL is selected 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 Deployment Descriptor Page.
  Figure 12.4. Deployment Descriptor Page
8. Click the XML tab to display the additions to web.xml . The security constraint looks like this:
  Example 12.4.
```
<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), 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.

12.4.2. Adding Users to GlassFish

This section describes the following tasks:

To Add a User to GlassFish for Development

To create a user in the GlassFish file realm to be used for testing and development purposes, follow these steps.

In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
In addition to setting up keystore and truststore files, this option creates a default user on GlassFish. The user has the name wsitUser and the password of changeit .

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 ( admin ) and password ( adminadmin ) 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/bin/asadmin create-file-user --groups wsit wsitUser
```
When you are prompted for the password, type changeit .

12.5. 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 Manually 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 http://xwss.java.net/ .

This section covers the following topics:

To Automatically Update GlassFish Certificates

You can have NetBeans automatically update the GlassFish certificates to the version needed to work with message security. To do this, follow these steps:

In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
This option imports certificates into the GlassFish keystore and truststore so that they can be used immediately for development.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.

To Manually Update GlassFish Certificates

The WSIT message security mechanisms require the use of v3 certificates. The default GlassFish keystore and truststore Unhandled tag varname 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 manually 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.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
Unzip this file and change into its directory, copyv3 .
Set the variable to the location where GlassFish is installed, as described in the README.txt file in this directory.

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:
1. Change to the directory containing the GlassFish keystore and truststore files, as-install /domains/domain1/config .
2. 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
```
3. 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
```

12.5.1. 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 Keystore and Truststore Aliases .

Table 12.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 Keystore and Truststore Aliases for STS .

Table 12.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

12.5.2. 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 Automatically

To have NetBeans IDE configure the keystore to its default values, follow these steps.

In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
This option imports certificates into the GlassFish keystore and truststore so that they can be used immediately for development. This option also inserts the location and alias of the keystore and truststore files into the configuration file.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.

To Configure the Keystore on a Service Manually

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.
Unselect Use Development Defaults.
Click the Keystore button. The dialog shown in Keystore Configuration Dialog displays.
Figure 12.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 Automatically

To have NetBeans IDE configure the truststore to its default values, follow these steps.

In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
This option imports certificates into the GlassFish keystore and truststore so that they can be used immediately for development. This option also inserts the location and alias of the keystore and truststore files into the configuration file, when required for a selected security mechanism.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.

To Configure the Truststore on a Service Manually

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.
Unselect Use Development Defaults.
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 : Unhandled tag tip 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 Quality of Service tab to display the WSIT Security options.
Click Keystore or Truststore to specify the keystore or truststore information if required by the service.
Depending on what is required for the selected mechanism, you may specify the following information:
- 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.
Click OK to close the dialog.

12.5.3. 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. The Validators button will be enabled when all of the following are true:

Security is enabled for the service.
Target server for the service is not GlassFish.
Development defaults are disabled.
Security profile for the service is not one of the three STS based profiles.

Applications that run under a GlassFish 9.1 or higher 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.
Unselect Use Development Defaults.
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.

12.6. Configuring Kerberos for Glassfish and Tomcat

This section explains how to setup Glassfish or Tomcat to use Kerberos Authentication. It assumes that the underlying infrastructure has Kerberos Authentication available. If you need information on how to setup Kerberos in Solaris or Ubuntu Linux environments, refer to the following links:

Note that in a Windows environment you can set up a Kerberos KDC only on Window Server editions 2000, 2003 and 2008. The KDC is bundled in these editions with its own Kerberos implementation as part of Active Directory. You can not install MIT Kerberos KDC on Windows. A Windows XP/Vista system can act as a client of the Windows Server editions KDC. Alternatively, you can install a client module of MIT Kerberos for Windows -- see Kerberos for Windows Release 3.2.2.You can then use the client module to authenticate against a KDC that was set up on a UNIX system.

12.6.1. For Glassfish

Specify the JAAS login modules to be used for Kerberos in the $GLASSFISH_HOME/domains/domain1/config/login.conf file, as follows:

KerberosClient {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true;
}

KerberosServer {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true keyTab="/etc/krb5.keytab"
    doNotPrompt=true storeKey=true
    principal="websvc/service@INDIA.SUN.LOCAL";
}

You can give any names to the login modules, that is, instead of KerberosClient and KerberosServer. You need to refer to these names in the <sc:KerberosConfig> assertion in the WSDL file and in the wsit-client.xml file.

Also edit the principal in KerberosServer to the service_principal that you created, and specify the correct location of krb5.keytab file.

12.6.2. For Tomcat

Glassfish picks the login modules from $GLASSFISH_HOME/domains/domain1/config/login.conf. In Tomcat we need to specify the file explicitly using java.security.auth.login.config system property. Here are the steps:

Create a file jaas.conf , and place it in $CATALINA_HOME/conf. Here's what jaas.conf looks like:

KerberosClient {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true;
};
KerberosServer {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true keyTab="/etc/krb5.keytab"
    doNotPrompt=true storeKey=true
    principal="websvc/service@INDIA.SUN.COM";
};

Add following line to the catalina.sh script (or specify the mentioned JAVA_OPTS property):
```
JAVA_OPTS="$JAVA_OPTS "-Djava.security.auth.login.config=$CATALINA_HOME/conf/jaas.conf
```

Specify the following system property in your client code:

-Djava.security.policy=${tomcat.home}/conf/catalina.policy
-Djava.security.auth.login.config=${tomcat.home}/conf/jaas.conf

12.7. 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 operation Operation node (for example, the add Operation node.) It should look like Web Service Attributes Editor Page: Operation Level.
Figure 12.6. 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 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.
- Encrypted: Specifies that the authentication token must be an encrypted supporting token.
One can select any (or none) combination of the three options above. 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. If Encrypted is selected as well, the supporting token is also encrypted in the request message.
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 Web Service Attributes Editor Page: Message Parts.
Figure 12.7. 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).
Click Add Attachments to add a row the SOAP attachments.
This is useful if the web service has MIME attachments which should be protected. All the attachments in the message are secured on selecting this option. This option is only available for the specification version of Security Policy, supported in Netbeans IDE from 6.5 version.
Note
Attachments Protection is not supported in .NET 3.0 and 3.5. So it is best to avoid this feature for interop with .NET.
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.

12.7.1. 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 Manually.
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.

12.8. 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 service, a client, and a trusted third party called a Security Token Service (STS). Policy flows from service to client, and from STS to client. Policy may be embedded inside an issued token assertion, or acquired out-of-hand. There must be an explicit trust relationship between the service and the STS and the client and the STS. There does not need to be a trust relationship between the client and service.

When the web service being referenced by the client uses any of the STS security mechanisms (refer to tables in Summary of Service-Side Configuration Requirements and Summary of Client-Side Configuration Requirements ), an STS must be specified. You can specify the STS in the following 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 .
For more information on managing the STS, see Managing multiple services with Metro based 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 at Example: STS Issued Token (STS) .
An example that shows how to achieve the trust brokering between different domains using an STS can be found at Example: Broker Trust STS (BT) .
An example that shows how to use SecureConversation with an STS can be found at Example: STS Issued Token With SecureConversation (STS+SC) .
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. 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 Java Web, then Web Application, then Next.
Type a Project Name, then Next, then the desired Server. Click Finish.
Right-click the STS Project, and select New, then select Other.
Select Web Services 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_STS Service , and the Java file appears in the right pane.
The STS wizard creates an implementation of the provider class.
Back in the Projects window, expand the STS project folder, expand the Web Services node, right-click on the web service, and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Make sure Secure Service is selected.
Select a Security Mechanism that is NOT one of the STS mechanisms. The example application uses Username Authentication with Symmetric Key.
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. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. Installation instructions are provided in the JCE zip file. You can download JCE from this URL: http://www.oracle.com/technetwork/java/javase/downloads/index.html
Make sure Act as Secure Token Service (STS) is selected.
The default values will create a valid STS.
Optionally, you can change the following configuration options by clicking the Configure button:
- 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.security.trust.impl.WSTRustContractImpl 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 36,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, if open.
Click OK to close the STS Configuration dialog, if open.
Click the Keystore button to configure the keystore.
If you are using the GlassFish stores, click the Load Aliases button and select wssip . Otherwise, browse to the location of your keystore and enter the relevant information.
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_STS Service?wsdl .
Run the Project (right-click the Project and select Run). The STS WSDL displays in a browser window.
Note
If you are receiving compilation errors during the build, you may need to update your JRE's JAX-WS version to the latest release version. See here for more details.

Check Building custom STS to build a custom STS to control the user attributes to be included in the SAML assertion.

Managing multiple services with Metro based STS

Metro based STS can be used to secure multiple services. One need to register a service provider to an STS before the issued tokens of the STS can be used for that service.

Each resgisted service comes up as a ServiceProvide in the STSConfiguration:

Example 12.5.

<tc:STSConfiguration
        xmlns:tc="http://schemas.sun.com/ws/2006/05/trust/server"
        encryptIssuedKey="true" encryptIssuedToken="false">
   <tc:LifeTime>36000</tc:LifeTime>
   <tc:Contract>com.sun.xml.ws.security.trust.impl.WSTrustContractImpl
   </tc:Contract>
   <tc:Issuer>SunSTS</tc:Issuer>
   <tc:ServiceProviders>
      <tc:ServiceProvider endPoint="http://localhost:8080/jaxws-s5/simple">
         <tc:CertAlias>bob</tc:CertAlias>
         <tc:TokenType>
            http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1
            #SAMLV1.1
         </tc:TokenType>
      </tc:ServiceProvider>
      <!-- more service providers -->
   </tc:ServiceProviders>
</tc:STSConfiguration>

At the minimum, you need to specify the endpoint as well as the cert alias for each service provider. At run time, the actual service is identified for each request RST from a client to the STS. The RST contains an AppliesTo element pointing to the endpoint of the targeted service. On the STS side, the certificate of the service is used to encrypt the issued tokens and proof keys for the service.

With Netbeans, one can add Service Providers to an STS through the configuration panel for STS:

Click Configure button besides Act as Secure Token Service (STS).
In the STS Configuration panel, click Add
In the Select Service Provider panel, add information of the service provider. Note that you must import the certificate of the service provider to the TrustStore of the STS.

We provide a default Service Provider with endpoint="default". This default setting, working with any service providers, is for testing purpose only. In a product, you must remove it and add all the service providers to be secured by the STS. You may also implement STSConfigurationProvider with your own STSConfiguration and TrustSPMetada to configure STS and register service providers to a deployed STS at run time.

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 the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
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. Select 128 if you have not installed Unlimited Strength Encryption.
Click OK to close the dialog.
Click OK.
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- package-name . service-name .xml and select the Source page.
Right-click the project node and select Run to compile the application and deploy it onto GlassFish. A browser will open and display the WSDL file for the application.

To Specify an STS on the Client Side

Once you've determined whether it is required to configure an STS on the client side (see Summary of Client-Side Configuration Requirements), configure the client Secure Token Service options. To configure the client-side with STS, you need to configure the clients for the service and STS follow these steps.

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 Quality of Service tab.
Provide the service's certificate by pointing to an alias in the client truststore. For development purposes, click the Truststore button,, click the Load Aliases button for the truststore and select xws-security-server from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the truststore entries be manually configured. To do this, follow the steps in this section.
- Expand the client project node, then expand Source Packages/META-INF.
- Double-click <service-project> ..xml to open it in the Source window. Click the Source tab to view the code. Find the sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements could be specified.
  Example 12.6.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="xws-security-server"/>
```
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 example application you would enter the following value in the Endpoint field: http://localhost:8080/MySTSProject/MySTSService . For WS Trust Version field, select 1.3 if STS endpoint uses ".NET 3.5 / Metro 1.3" version compatibility. Otherwise use the default WS Trust Version.
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 examples following this section describe a few potential STS configurations.
Click OK to close this dialog.
The service requires a token to be issued from the STS, which, for the example, is http://localhost:8080/MySTSProject/MySTSService , with WSDL file http://localhost:8080/MySTSProject/MySTSService?wsdl . To do this, follow these steps:
1. Right-click the web service client project 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 the tutorial example, the URL for the MySTS web servicen is:
```
http://localhost:8080/MySTSProject/MySTSService?wsdl
```
4. Type the package name, for example, org.me.calculator.client.sts , into the Package field, then click Finish.
  The Projects window displays the new web service client.
Drill down from the web service client project node to the Web Service References node.
Right-click the node for the STS service, and select Edit Web Service Attributes.
Select the Quality of Service tab.
If required, provide the client's private key by pointing to an alias in the keystore. For development purposes, click the Keystore button, click the Load Aliases button, and select xws-security-client from the Alias list.
Verify the STS's certificate by pointing to an alias in the client truststore. For development purposes, click the Truststore button,, click the Load Aliases button and select wssip from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
- Expand the web services client project node, then Source Packages | META-INF.
- Double-click <sts-service> .xml to open it in the Source window. Click the Source tab to view the code. Find the sc:KeyStore and/or sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements could be specified.
  Example 12.7.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="wssip"/>
<sc:KeyStore
 wspp:visibility="private"
 location="<GF_HOME>\glassfish\domains\domain1\config\truststore.jks"
 storepass="changeit" alias="xws-security-client"/>
```
If required, enter the default user name and password.
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 web services client project and selecting Run.

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

12.9.1. Example: Username Authentication with Symmetric Key (UA)

The section describes the following tasks:

To Secure the Example Service Application (UA)

The following example application starts with the example provided in Developing with NetBeans 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 Key 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 Developing with NetBeans .
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 Key.
Select Use Development Defaults to set up the keystore and truststore files, and to create a user for this application, if needed.
Click OK to close the CalculatorWSService 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 security elements within wsp:Policy tags.
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. 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 (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 Key . 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 Web Service References node.
Right-click on CalculatorWSService, select Edit Web Service Attributes.
In the Security section of the Quality of Service tab, select Use Development Defaults. Click OK to close.
Note
By default, the user name of wsitUser and the password of changeit will be entered in this section. If the example doesn't run, make sure that you have a user with this name and password set up in the file realm of the Application Server or GlassFish, as described in Adding Users to GlassFish .
If you'd like to, 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:
Example 12.8.
```
<wsp:All>
   <sc:TrustStore
         wspp:visibility="private"
         location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
         storepass="changeit" peeralias="xws-security-server"/>
   <sc:CallbackHandlerConfiguration wspp:visibility="private">
      <sc:CallbackHandler default="wsitUser" name="usernameHandler"/>
      <sc:CallbackHandler default="changeit" name="passwordHandler"/>
   </sc:CallbackHandlerConfiguration>
</wsp:All>
```
By selecting Use Development Defaults when securing the service, these values are automatically generated for you.
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. The result of the add operation will display in a browser window.

12.9.2. Example: Username with Digest Passwords

This example is similar to Example: Username Authentication with Symmetric Key (UA) except that digest passwords (along with Created and Nonce) are used in UsernameToken, and UsernameToken is not encrypted in the message.

To Secure the Service Application, all the steps remain same, except for step 6. For step 6, do the following:

Click on Configure, select Support Hash Passwords. Click OK.
Unselect Use Development Defaults, if already selected. Specify the KeyStore. Click on Validators, and specify the username validator.
The Username Validator created should extend PasswordValidationCallback.WsitDigestPasswordValidator. Here is a sample UsernameValidator for Digest passwords.
Example 12.9.
```
import com.sun.xml.wss.impl.callback.PasswordValidationCallback;

public class SampleWsitDigestPasswordValidator extends
        PasswordValidationCallback.WsitDigestPasswordValidator {
    public  void setPassword(PasswordValidationCallback.Request request){
        //Get this password from somewhere - for example a JDBC Realm
        String passwd = "abcd!1234";
        PasswordValidationCallback.DigestPasswordRequest req =
                (PasswordValidationCallback.DigestPasswordRequest)request;
        req.setPassword(passwd);
    }
}
```
Note
Use of Digest Passwords can be supported for any realm which store plain passwords (not hashed ones). Currently this is supported for JDBC realm in Glassfish. Or optionally, a user can write his own custom realm.

The steps for securing the client remain same as in Example: Username Authentication with Symmetric Key (UA).

12.9.3. Example: Mutual Certificates Security (MCS)

The section describes the following tasks:

To Secure the Example Service Application (MCS)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

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.

Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans .
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.
Select Use Development Defaults.
Click OK to close the 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 security elements within wsp:Policy tags.
Right-click the CalculatorApplication node and select Run.
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.
If you'd like, in the tree, drill down from the project to Source Packages | META-INF. Double-click on CalculatorWSService.xml , click the Source tab, and look at the section in the section <wsp:All> to see the WSIT code that has been added to this configuration file.
Compile and run this application by right-clicking the CalculatorWSServletClient node and selecting Run. The result of the add operation will display in a browser window.

12.9.4. 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 Developing with NetBeans 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 Developing with NetBeans :
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).
Select Use Development Defaults.
Click OK to close the 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 security elements within wsp:Policy tags.
To require the service to use the HTTPS protocol, security requirements must be specified in the service's application deployment descriptor, which is web.xml for a web service implemented as a servlet. Selecting Use Development Defaults takes care of this task for you.
To view or change 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. Expand the Security Constraint named SSL transport for CalculatorWSService .
5. A Web Resource Collection named Secure Area contains the URL Pattern to be protected, /CalculatorWSService//* and the HTTP Methods to be protected, , POST.
6. Unselect Enable Authentication Constraint if it is selected.
7. The Enable User Data Constraint box is checked and CONFIDENTIAL is chosen 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. 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 5 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
Some users are working through this document and just making the recommended changes and refreshing the client. For this example, you must create a new client so that you can specify the secure WSDL to create the correct setup for the client.
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. The result of the add operation will display in a browser window.

12.9.5. Example: SAML Authorization over SSL (SA)

This section describes the following tasks:

To Secure the Example Service Application (SA)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

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 Key (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.

Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans :
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.
Select Use Development Defaults to have the web.xml file modified to include a security constraint that forces the use of SSL.
Click OK to exit the 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 security elements within wsp:Policy tags.
To require the service to use the HTTPS protocol, security requirements must be specified in the service's application deployment descriptor, which is web.xml for a web service implemented as a servlet. Selecting Use Development Defaults takes care of this task for you.
To view or change the security information in the deployment descriptor, 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. Expand the Security Constraint named SSL transport for CalculatorWSService .
5. A Web Resource Collection named Secure Area contains the URL Pattern to be protected, /CalculatorWSService//* and the HTTP Methods to be protected, , POST.
6. Unselect Enable Authentication Constraint if it is selected.
7. The Enable User Data Constraint box is checked and CONFIDENTIAL is chosen 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. Accept the s1as certificate if you are prompted to. 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 (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 5 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, 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, expand Web Pages, then double-click index.jsp 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:
  Example 12.10.
```
<body>
```
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 | Other.
6. From the Categories list, select Java.
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:
  http://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&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:
  Example 12.11.
```
String home = System.getProperty("WSIT_HOME");
```
  to
  Example 12.12.
```
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 Quality of Service tab of the CalculatorWSService dialog.
Unselect Use Development Defaults.
Enter the name of the SAML Callback Handler written earlier in this section, xwss.saml.SamlCallbackHandler , into the SAML Callback Handler field.
Click OK to close this dialog.
To view the WSIT Configuration options, in the tree, drill down from the project to Source Packages | META-INF. Double-click CalculatorWSService.xml , click the Source tab, and look for the lines where xwss.saml.SamlCallbackHandler is specified as the SAML Callback Handler class for the client.
Compile and run this application by right-clicking the CalculatorClient node and selecting Run. The result of the add operation will display in a browser window.

12.9.6. Example: SAML Sender Vouches with Certificates (SV)

This section describes the following tasks:

To Secure the Example Service Application (SV)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

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 Key (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.

Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans :
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.
Select Use Development Defaults. This step properly configures the keystore, truststore, and default user for this security mechanism.
Click OK.
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 security elements within wsp:Policy tags.
Right-click the CalculatorApplication node and select Run. Accept the s1as certificate if you are prompted to.
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 (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 5 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:
  Example 12.13.
```
<body>
```
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 | Other.
6. From the Categories list, select Java.
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:
  http://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&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:
  Example 12.14.
```
String home = System.getProperty("WSIT_HOME");
```
  to
  Example 12.15.
```
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 on CalculatorWSService and select Edit Web Service Attributes.
Select the Quality of Service tab of the CalculatorWSService dialog.
In the SAML Callback Handler field, type the name of the class written in step 3 above, xwss.saml.SamlCallbackHandler .
Configure the keys: Click on the keystore button, select the alias "xws-security-client", enter the password "changeit", in the password field. Submit this dialog; Click on the truststore button, select the alias "xws-security-server". Submit the dialog.
Click OK to close this dialog.
In the tree, drill down from the project to Source Packages | META-INF. Double-click CalculatorWSService.xml, click the Source tab, and look for that lines where xwss.saml.SamlCallbackHandler is specified as the SAML Callback Handler class for the client. In some instances, NetBeans will not correctly specify the keystore and truststore information for non-JSR-196 clients, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the example in this section.
- Find the sc:KeyStore and sc:TrustStore elements. If these elements contain parameters for location and storepass in CalculatorWSService.xml, then just continue to the next step. If not, replace the existing keystore and truststore attributes to include these parameters. The following code shows an example of how these elements should be specified.
  Example 12.16.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="xws-security-server"/>
<sc:KeyStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks"
   storepass="changeit" alias="xws-security-client"/>
```
Compile and run this application by right-clicking the CalculatorClient node and selecting Run. The result of the add operation will display in a browser window.

12.9.7. Example: STS Issued Token (STS)

This section describes the following tasks:

Another STS example application can be found at the following URL: http://java.net/projects/wsit/sources/svn/show/trunk/wsit/samples/ws-trust .

To Create and Secure the STS (STS)

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

Note

For development with NetBeans 6.8, there are some temporary setup changes that will need to be done--see here for more details.

Create a new project for the STS by selecting File | New Project.
Select Java Web, then Web Application, then Next.
Type MySTSProject for the Project Name, then Next, then the desired Server. Click Finish.
Right-click the MySTSProject node, select New, then select Other.
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.
Enter or select org.me.my.sts in the Package field, then click Finish. If prompted to reload the catalog.xml file, click No.
The IDE takes a while to create the STS. When created, it appears under the project's Web Services node as MySTSService .
The STS wizard creates an implementation of the provider class. To view it, expand Source Packages, then org.me.my.sts. Double-click MySTS.java to open it in the right pane.
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 the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service if it's not already selected.
Verify that the Security Mechanism of Username Authentication with Symmetric Key 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.) Select OK to close the configuration dialog.
If not already selected, select Act as Secure Token Service (STS).
Note
If you'd like to use an STS other than the default, click the STS Configure button, and click the Add button to add a different service provider. Click OK to close the STS Configuration dialog.
Click Configure. In the Issuer field, enter MySTS. Click OK to close.
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.
A new file is added to the project. To view the WSIT configuration file, expand Configuration Files | xml-resources | web-services | MySTS | wsdl, then double-click the file MySTSService.wsdl . This file contains the tc:STSConfiguration element within the wsp:Policy elements..
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).
The STS WSDL appears in the browser.

Check Building custom STS to build a custom STS to control the user attributes to be included in the SAML assertion.

To Secure the Example Service Application (STS)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

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 Key (UA) , with the addition of creating and securing an STS.

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 Developing with NetBeans .
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.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select STS Issued Token.
Click Configure. For Issuer Address and Issuer Metadata Address, enter http://localhost:8080/MySTSProject/MySTSService . For Issuer Metadata, enter http://localhost:8080/MySTSProject/MySTSService/mex
For Algorithm Suite, select Basic 128 bit. For Key Size, select 128 (the algorithm suite value of the service must match the algorithm suite value of the STS). Select OK to close the configuration dialog.
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.
Select Use Development Defaults.
Click OK.
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 and select the Source page. This file contains the security elements within wsp:Policy tags.
Right-click the CalculatorApplication node and select Run. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.

To Secure the Example Web Service Client Application (STS)

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

To add security to the web service 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 Quality of Service tab.
Provide the client's private key by pointing to an alias in the keystore. To do this, click the Keystore button, click the Load Aliases button, 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, click the Truststore button,, click the Load Aliases button for the truststore and select xws-security-server from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
- Expand CalculatorWSServletClient | Source Packages | META-INF.
- Double-click CalculatorWSService.xml to open it in the Source window. Click the Source tab to view the code. Find the sc:KeyStore and sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements should be specified.
  Example 12.17.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="xws-security-server"/>
<sc:KeyStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks"
   storepass="changeit" alias="xws-security-client"/>
```
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, enter the following value: http://localhost:8080/MySTSProject/MySTSService. For WS Trust Version field, select 1.3 if STS endpoint uses ".NET 3.5 / Metro 1.3" version compatibility. Otherwise use the default WS Trust Version.
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 this 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 Quality of Service tab of the MySTSService dialog.
Provide the client's private key by pointing to an alias in the keystore. To do this, click the Keystore button, click the Load Aliases button, and select xws-security-client from the Alias list. If the Keystore button is not selectable, follow the instructions in the next step for adding the keystore entry manually.
Verify the STS's certificate by pointing to an alias in the client truststore. To do this, click the Truststore button,, click the Load Aliases button and select wssip from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
- Expand CalculatorWSServletClient | Source Packages | META-INF.
- Double-click MySTSService.xml to open it in the Source window. Click the Source tab to view the code. Find the sc:KeyStore and sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements should be specified.
  Example 12.18.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="wssip"/>
<sc:KeyStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks"
   storepass="changeit" alias="xws-security-client"/>
```
Enter the default user name and password.
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. The result of the add operation will display in a browser window.

12.9.8. Example: Broker Trust STS (BT)

Broker Trust STS example illustrates the interaction between client and server of different domains through STS's of corresponding domains. In this kind of scenarios, STS of different domains must have a trust relationship between them. Lets take client/STS2 are in domain A, and server/STS1 are in domain B. Here, STS1 is the remote STS on the server domain(B) and STS2 is the local STS on the client domain(B). There is a trust relationship between STS1 and STS2. Here are steps which client has to follow to comminicate with server.

Client wants to communicate with Server.
Server asks Client to get a token from STS1 to comminicate with it.
Now Client would like to communicate with remote STS (i.e. STS1).
STS1 asks Client to get a token from Client's local STS (i.e. STS2) to comminicate with it.
Now Client sends a request to local STS (i.e. STS2) asking for a token to communicate with STS1.
STS2 issues a token to Client, which Client uses to comminicate with STS1.
STS1 issues a token to Client, which Client uses to comminicate with Server.
Now Client comminicates with server using a token issued by STS1, which Server understands.

This section describes the following tasks:

To Create and Secure the First STS (BT)

To create and secure a Security Token Service(i.e. Remote STS) 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 MySTS1Project for the Project Name, then click Finish.
Right-click the MySTS1Project node, select New, then select Other.
Select Web Services from the Categories list.
Select Secure Token Service (STS) from the File Type(s) list, then click Next.
Type the name MySTS1 for the Web Service Class Name.
Enter or select org.me.my.sts1 in the Package field, then click Finish. If prompted to reload the catalog.xml file, click No.
The IDE takes a while to create the first STS. When created, it appears under the project's Web Services node as MySTS1Service .
The STS wizard creates an implementation of the provider class. To view it, expand Source Packages, then org.me.my.sts1. Double-click MySTS1.java to open it in the right pane.
In the Projects window, expand the MySTS1Service node, then expand the Web Services node. Right-click the MySTS1Service[IMySTS1Service_Port] node and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service if it's not already selected.
Verify that the Security Mechanism of "STS Issued Token" 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.) Select OK to close the configuration dialog.
If not already selected, select Act as Secure Token Service (STS).
Note
If you'd like to use an STS other than the default, click the STS Configure button, and click the Add button to add a different service provider. Click OK to close the STS Configuration dialog.
Click Configure. In the Issuer field, enter MySTS1. Click OK to close.
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.
A new file is added to the project. To view the WSIT configuration file, expand Configuration Files | xml-resources | web-services | MySTS1 | wsdl, then double-click the file MySTS1Service.wsdl . This file contains the tc:STSConfiguration element within the wsp:Policy elements..
Right-click the MySTS1Project tab, select Properties. Select the Run category, and type the following in the Relative URL field: /MySTS1Service?wsdl .
Run the Project (right-click the project and select Run).
The STS WSDL appears in the browser.

To Create and Secure the Second STS (BT)

To create and secure a Security Token Service(i.e. local STS) for this example, follow these steps.

Create a new project for the 2nd STS by selecting File | New Project.
Select Web, then Web Application, then Next.
Type MySTS2Project for the Project Name, then click Finish.
Right-click the MySTS2Project node, select New, then select Other.
Select Web Services from the Categories list.
Select Secure Token Service (STS) from the File Type(s) list, then click Next.
Type the name MySTS2 for the Web Service Class Name.
Enter or select org.me.my.sts2 in the Package field, then click Finish. If prompted to reload the catalog.xml file, click No.
The IDE takes a while to create the first STS. When created, it appears under the project's Web Services node as MySTS2Service .
The STS wizard creates an implementation of the provider class. To view it, expand Source Packages, then org.me.my.sts2. Double-click MySTS2.java to open it in the right pane.
In the Projects window, expand the MySTS2Service node, then expand the Web Services node. Right-click the MySTS2Service[IMySTS2Service_Port] node and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service if it's not already selected.
Verify that the Security Mechanism of Username Authentication with Symmetric Key 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.) Select OK to close the configuration dialog.
If not already selected, select Act as Secure Token Service (STS).
Note
If you'd like to use an STS other than the default, click the STS Configure button, and click the Add button to add a different service provider. Click OK to close the STS Configuration dialog.
Click Configure. In the Issuer field, enter MySTS2. Click OK to close.
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.
A new file is added to the project. To view the WSIT configuration file, expand Configuration Files | xml-resources | web-services | MySTS2 | wsdl, then double-click the file MySTS2Service.wsdl . This file contains the tc:STSConfiguration element within the wsp:Policy elements..
Right-click the MySTS2Project tab, select Properties. Select the Run category, and type the following in the Relative URL field: /MySTS2Service?wsdl .
Run the Project (right-click the project and select Run).
The STS WSDL appears in the browser.

To Secure the Example Service Application (BT)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

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 Key (UA), with the addition of creating and securing an STS.

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 Developing with NetBeans .
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.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select STS Issued Token.
Click Configure. For Issuer Address and Issuer Metadata Address, enter http://localhost:8080/MySTS1Project/MySTS1Service . For Issuer Metadata, enter http://localhost:8080/MySTS1Project/MySTS1Service/mex
For Algorithm Suite, select Basic 128 bit. For Key Size, select 128 (the algorithm suite value of the service must match the algorithm suite value of the STS). Select OK to close the configuration dialog.
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.
Select Use Development Defaults.
Click OK.
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 and select the Source page. This file contains the security elements within wsp:Policy tags.
Right-click the CalculatorApplication node and select Properties. Select the Run category, and type the following in the Relative URL field: /CalculatorWSService?wsdl .
Right-click the CalculatorApplication node and select Run. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.

To Secure the Example Web Service Client Application (BT)

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

To add security to the web service 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 Quality of Service tab.
Provide the client's private key by pointing to an alias in the keystore. To do this, click the Keystore button, click the Load Aliases button, 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, click the Truststore button,, click the Load Aliases button for the truststore and select xws-security-server from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
- Expand CalculatorWSServletClient | Source Packages | META-INF.
- Double-click CalculatorWSService.xml to open it in the Source window. Click the Source tab to view the code. Find the sc:KeyStore and sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements should be specified.
  Example 12.19.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="xws-security-server"/>
<sc:KeyStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks"
   storepass="changeit" alias="xws-security-client"/>
```
Click OK to close this dialog.
The service requires a token to be issued from the first STS (i.e Remote STS) at http://localhost:8080/MySTS1Project/MySTS1Service , with WSDL file http://localhost:8080/MySTS1Project/MySTS1Service?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 this example, here is the URL for the MySTS1 web service:
```
http://localhost:8080/MySTS1Project/MySTS1Service?wsdl
```
4. Type org.me.calculator.client.sts1 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 MySTS1Service and select Edit Web Service Attributes.
Select the Quality of Service tab of the MySTS1Service dialog.
Provide the client's private key by pointing to an alias in the keystore. To do this, click the Keystore button, click the Load Aliases button, and select xws-security-client from the Alias list. If the Keystore button is not selectable, follow the instructions in the next step for adding the keystore entry manually.
Verify the STS's certificate by pointing to an alias in the client truststore. To do this, click the Truststore button,, click the Load Aliases button and select wssip from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
- Expand CalculatorWSServletClient | Source Packages | META-INF.
- Double-click MySTSService.xml to open it in the Source window. Click the Source tab to view the code. Find the sc:KeyStore and sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements should be specified.
  Example 12.20.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="wssip"/>
<sc:KeyStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks"
   storepass="changeit" alias="xws-security-client"/>
```
Expand the Security Token Service node to provide details for the second STS(i.e. local 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, enter the following value: http://localhost:8080/MySTS2Project/MySTS2Service. For WS Trust Version field, select 1.3 if STS endpoint uses ".NET 3.5 / Metro 1.3" version compatibility. Otherwise use the default WS Trust Version.
Click OK to close this dialog.
The First STS(i.e. Remote STS) requires a token to be issued from the second STS(i.e. local STS) at http://localhost:8080/MySTS2Project/MySTS2Service , with WSDL file http://localhost:8080/MySTS2Project/MySTS2Service?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 this example, here is the URL for the MySTS2 web service:
```
http://localhost:8080/MySTS2Project/MySTS2Service?wsdl
```
4. Type org.me.calculator.client.sts2 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 MySTS2Service and select Edit Web Service Attributes.
Select the Quality of Service tab of the MySTS2Service dialog.
Provide the client's private key by pointing to an alias in the keystore. To do this, click the Keystore button, click the Load Aliases button, and select xws-security-client from the Alias list. If the Keystore button is not selectable, follow the instructions in the next step for adding the keystore entry manually.
Verify the STS's certificate by pointing to an alias in the client truststore. To do this, click the Truststore button,, click the Load Aliases button and select wssip from the Alias list.
- In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
- Expand CalculatorWSServletClient | Source Packages | META-INF.
- Double-click MySTS2Service.xml to open it in the Source window. Click the Source tab to view the code. Find the sc:KeyStore and sc:TrustStore elements. If these elements contain parameters for location and storepass , then just continue to the next section. If not, add these attributes to this file. The following code shows an example of how these elements should be specified.
  Example 12.21.
```
<sc:TrustStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
   storepass="changeit" peeralias="wssip"/>
<sc:KeyStore
   wspp:visibility="private"
   location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks"
   storepass="changeit" alias="xws-security-client"/>
```
Enter the default user name and password.
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. The result of the add operation will display in a browser window.

12.9.9. Example: STS Issued Token With SecureConversation (STS+SC)

This example illustrates, how SecureConversation Token is used to interact with STS. To have a basic idea of SecureConversation, find this article : Secure Conversations for Web Services With Metro

This section describes the following tasks:

To Create and Secure the STS with SecureConversationToken (STS+SC).

Same as provided in To Create and Secure the STS (STS)

To Secure the Example Service Application (STS+SC)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

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 Developing with NetBeans .
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.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select STS Issued Token.
Click Configure. For Issuer Address and Issuer Metadata Address, enter http://localhost:8080/MySTSProject/MySTSService . For Issuer Metadata, enter http://localhost:8080/MySTSProject/MySTSService/mex
Select the Configure button and do the following :
For Algorithm Suite, verify that Basic128 bit is selected (so that it matches the value selected for the service.)
Check the Establish Secure Session (Secure Conversation) check box to enable the secure conversaion feature
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.
Select OK to close the configuration dialog.
Select Use Development Defaults.
Click OK.
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 and select the Source page. This file contains the security elements within wsp:Policy tags.
Right-click the CalculatorApplication node and select Run. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.

To Secure the Example Web Service Client Application (STS+SC).

Same as provided in To Secure the Example Web Service Client Application (STS)

12.9.10. Example: Kerberos Token (Kerb)

This section contains the steps for running a Kerberos Token Profile-based WS Security scenario. Kerberos support was added to Metro in 1.1 release. The Netbeans support for configuring a Kerberos Token based secure web service is available from Metro 1.3 and Netbeans 6.5.

For an article discussing using Kerberos with WSIT, go to Building Kerberos-Based Secure Services Using Metro. This article has a sample application, but does not use Netbeans IDE.

The section describes the following tasks:

To Set Up Your System for Kerberos Profile.

If your system is not already set up to use Kerberos, refer to the steps mentioned in Configuring Kerberos for Glassfish and Tomcat.

To Secure the Example Service Application (Kerb)

The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.

For this example, a Kerberos token 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 Developing with NetBeans.
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 Symmetric Binding with Kerberos Tokens.
Select Kerberos button, and specify the Login Module to be used for the service. For details on Login Module to specify refer Configuring Kerberos for Glassfish and Tomcat.
Figure 12.8. Kerberos Configuration Attributes - Service

Click OK to close the CalculatorWSService dialog.

Expand Web Pages | WEB-INF, then double-click the file wsit-org.me.calculator.CalculatorWS.xml to open it in the edit window.The Binding level policy looks like: (This section of code has been formatted to fit the page)

Example 12.22.

<wsp:Policy wsu:Id="IFinancialService_policy">
   <wsp:ExactlyOne>
      <wsp:All>
         <wsaws:UsingAddressing
                 xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
         <sp:SymmetricBinding>
            <wsp:Policy>
               <sp:ProtectionToken>
                  <wsp:Policy>
                     <sp:KerberosToken
                             sp:IncludeToken="http://docs.oasis-open.org/
                        ws-sx/ws-securitypolicy/200702/IncludeToken/Once">
                        <wsp:Policy>
                           <sp:WssGssKerberosV5ApReqToken11/>
                        </wsp:Policy>
                     </sp:KerberosToken>
                  </wsp:Policy>
               </sp:ProtectionToken>
               <sp:Layout>
                  <wsp:Policy>
                     <sp:Strict/>
                  </wsp:Policy>
               </sp:Layout>
               <sp:IncludeTimestamp/>
               <sp:OnlySignEntireHeadersAndBody/>
               <sp:AlgorithmSuite>
                  <wsp:Policy>
                     <sp:Basic128/>
                  </wsp:Policy>
               </sp:AlgorithmSuite>
            </wsp:Policy>
         </sp:SymmetricBinding>
         <sp:Wss11>
            <wsp:Policy>
               <sp:MustSupportRefKeyIdentifier/>
               <sp:MustSupportRefIssuerSerial/>
               <sp:MustSupportRefThumbprint/>
               <sp:MustSupportRefEncryptedKey/>
            </wsp:Policy>
         </sp:Wss11>
         <sc:KerberosConfig xmlns:
                            sc="http://schemas.sun.com/2006/03/wss/server"
                            loginModule="KerberosServer"/>
      </wsp:All>
   </wsp:ExactlyOne>
</wsp:Policy>

Right-click the CalculatorApplication node and select Run. A browser will open and display the WSDL file for the application.
If the application doesn't build, expand CalculatorApplication | Web Pages | WEB-INF, and double-click web.xml to open it in the right pane. Select the Security tab, and remove any existing security constraints. Then run the project again.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (Kerb).

To Secure the Example Web Service Client Application (Kerb)

This section demonstrates adding security to the web service client that references the web service created in the previous section. . This section also assumes that Kerberos environment has already been setup on the system. Refer to Configuring Kerberos for Glassfish and Tomcat for more details.

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 Web Service References node.
Right-click on CalculatorWSService, select Edit Web Service Attributes.
Expand the Web Service References node.
In the Security section of the Quality of Service tab, select Kerberos. Specify Login Module, Service Principal and check the box if credentials should be delegated.
Specify the Login Module to the one you created in login.conf file for the client in the section Configuring Kerberos for Glassfish and Tomcat, and the service principal for which the ticket needs to be obtained.
Kerberos support in Metro security supports credential delegation from client to service, such that the server can initiate other security contexts on behalf of the client. This feature is useful for single sign-on in a multi-tier environment. Select the checkbox for credential delegation.
Note
At the service, we can obtain the delegated credentials from the Subject of the authenticated user. The PrivateCredential set of the will have the delegated client credentials (as GSSCredential). We can pass this GSSCredential to GSSManager.createContext() pretending to be the client.
Also, the PublicCredential set of the authenticated Subject will always have KerberosPrincipal corresponding to the client.
Figure 12.9. Kerberos Configuration Attributes - Client
Right-click the CalculatorWSServletClient node and select Run. The result of the add operation will display in a browser window.
Note
If your client is a Java SE client, you need to set the following system properties while running your client code:
Example 12.23.
```
-Djava.security.policy=${glassfish.home}/domains/domain1/config/server.policy

-Djava.security.auth.login.config=${glassfish.home}/domains/domain1/config/login.conf
```
If it is WebApp deployed on glassfish, nothing else needs to be done.

Prev		Next
Chapter 11. WS-MakeConnection support	Home	Chapter 13. WSIT Security Features: Advanced: Topics