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.

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.

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.

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:

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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:

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:

From your web service
application, expand Web Pages |
WEB-INF.

Double-click
web.xml (or ejb-jar.xml )
to open it in the editor.

Select the Security
tab.

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.

Under Web Resource
Collection, click Edit.

Change the URL Pattern
to be protected (for example, /* ).
Select which HTTP Methods to protect, for example,
POST. Click OK to close this dialog.

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.

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.

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

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:

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 .

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.

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.

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.

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.

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.

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.

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:

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:

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.

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.

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.

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.

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 .

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_STSService ,
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 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_STSService?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:

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.

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.

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:

Right-click the web
service client project node and select New | Web
Service Client.

The New Web Service Client window
appears.

Select the WSDL URL
option.

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

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.

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.

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.

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.

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.

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.

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:

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.

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.

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 Mutual Certificates Security .

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

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.

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:

From your web service
application, expand Web Pages |
WEB-INF.

Double-click
web.xml to open it in the editor.

Select the Security
tab.

Expand the Security
Constraint named SSL transport for
CalculatorWSService .

A Web Resource
Collection named Secure Area contains
the URL Pattern to be protected,
/CalculatorWSService//* and the HTTP
Methods to be protected, , POST.

Unselect Enable
Authentication Constraint if it is
selected.

The Enable User Data
Constraint box is checked and CONFIDENTIAL is chosen
as the Transport Guarantee to specify that the
application uses SSL.

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 Transport Security (SSL) .

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

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

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.

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:

From your web service
application, expand Web Pages |
WEB-INF.

Double-click
web.xml to open it in the editor.

Select the Security
tab.

Expand the Security
Constraint named SSL transport for
CalculatorWSService .

A Web Resource
Collection named Secure Area contains
the URL Pattern to be protected,
/CalculatorWSService//* and the HTTP
Methods to be protected, , POST.

Unselect Enable
Authentication Constraint if it is
selected.

The Enable User Data
Constraint box is checked and CONFIDENTIAL is chosen
as the Transport Guarantee to specify that the
application uses SSL.

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 SAML Authorization over SSL .

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:

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.

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.

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.

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 SAML Sender Vouches with Certificates .

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

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

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.

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.

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

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.

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:

Right-click the
CalculatorWSServletClient node and select New | Web
Service Client.

The New Web Service Client window
appears.

Select the WSDL URL
option.

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

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.

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.

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.

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.

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

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.

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:

Right-click the
CalculatorWSServletClient node and select New | Web
Service Client.

The New Web Service Client window
appears.

Select the WSDL URL
option.

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

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.

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:

Right-click the
CalculatorWSServletClient node and select New | Web
Service Client.

The New Web Service Client window
appears.

Select the WSDL URL
option.

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

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.

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.

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.

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)

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.

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.

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.

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: