Table of Contents
This section describes the following tasks:
To Secure the Service
To use the IDE to configure security for a web service and/or a web service operation, perform the following steps.
Create or open your web service.
If you need an example of how to create a web service, refer to Developing with NetBeans.
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 Jakarta Enterprise Web Services Specification, which can be read at https://jakarta.ee/specifications/enterprise-ws/. If you select a value other than the default, for example, J2EE 1.4, the application that is created is not Jakarta Enterprise Web Services compliant, which means that the application is not Jakarta XML Web Service, but is JAX-RPC.
In the Projects window, expand the Web Services node.
Right-click the node for the web service you want to secure.
Select .
When the Web Service Attributes Editor is opened, the Quality of Service options appear (see Web Service Attributes Editor Page).
Select Secure Service.
This option enables WSIT security for all of the operations of a web service.
For information on how to secure selected operations, refer to Securing Operations and Messages.
Choose a Security Mechanism from the list.
Most of the mechanisms are fully functional without further configuration, however, if you'd like to customize the mechanism, click Configure to specify the configuration for that mechanism.
Options in the Configure dialog are discussed in Security Mechanism Configuration Options.
Select Use Development Defaults.
Select this option to import certificates into the GlassFish keystore and truststore so that they can be used immediately for development. The WSIT message security mechanisms require the use of v3 certificates. The default GlassFish keystore and truststore do not contain v3 certificates at this time. In order to use message security mechanisms with GlassFish, it is necessary to obtain keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.
In addition to importing certificates, when this
option is selected a default user is created in the
file realm with username
wsitUser.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
Specify Keystore, Truststore, STS, SSL, and/or user information as required for the selected security mechanism.
Refer to the entry for the selected security mechanism in Summary of Service-Side Configuration Requirements . This table summarizes the information that needs to be set up for each of the security mechanisms.
Click to save your changes.
Run the web application by right-clicking the project node and selecting .
Verify the URL of the WSDL file before proceeding with the creation of the web service client.
The client will be created from this WSDL file, and will get the service's security policies through the web service reference URL when the client is built or refreshed.
To Secure the Client
All of the steps in To Secure the Service need to be completed before you create your web service client. The service's security policies are defined in its WSDL. You specify this WSDL file when you create the client application so that the client is configured to work with the service's security mechanism through the web service reference URL when the client is built or refreshed.
To use the IDE to configure security for a web service client, perform the following steps.
Create a client for your web service.
If you need an example of how to do this, see Creating a Client to Consume a WSIT-Enabled Web Service .
If you are creating a client for a mechanism that
will use SSL, specify the secure port for running the
client when completing the New Web Service Client step. To
do this, type https://
fully_qualified_hostname
:8181/ rest_of_url in
the WSDL URL field of the New Web Service Client wizard.
For the example, this is the way to specify the secure URL
for CalculatorWSService web service:
https://fully_qualified_hostname:8181/CalculatorApplication/CalculatorWSService?wsdlIf you prefer to use localhost in
place of the fully-qualified hostname when specifying
the URL for the service WSDL, you must follow the
workaround described in Transport Security (SSL) Workaround.
In the Projects window, expand the client node.
Expand the Web Service References node.
Right-click the node for the web service reference you want to secure.
Select Edit Web Service Attributes.
When the Web Service References Attributes Editor is opened, select the Quality of Service tab to display the security options (see Web Service References Attributes Editor Page for Web Service Clients ).
Select Use Development Defaults.
Refer to Summary of Client-Side Configuration Requirements for a summary of what options are required on the client side. The configuration requirements for the client are dependent upon which security mechanism is specified on the server side.
Click OK to save your changes.
The security configuration information is saved in two files under Source Packages/META-INF. For more information on the format and runtime usage of these files, see Client-Side WSIT Configuration Files .
The following sections summarize the options that need to be configured for each of the security mechanisms on both the service and client side. The configuration requirements for the client are dependent upon which security mechanism is specified on the server side.
This section covers the following topics:
Summary of Service-Side Configuration Requirements summarizes the options that need to be configured for each security mechanism. Each of the columns is briefly discussed after the table.
Table 12.1. Summary of Service-Side Configuration Requirements
Mechanism | Keystore | Truststore | STS | SSL | User in GlassFish | Kerberos |
|---|---|---|---|---|---|---|
Username Authentication with Symmetric Key | X | X | ||||
Username Authentication with Password Derived Keys | X | |||||
Mutual Certificates | X | X (no alias) | ||||
Symmetric Binding with Kerberos Tokens | X | |||||
Transport Security | X | X | ||||
Message Authentication over SSL - Username Token | X | X | ||||
Message Authentication over SSL - X.509 Token | X (no alias) | X | ||||
SAML Authorization over SSL | X | |||||
Endorsing Certificate | X | X | ||||
SAML Sender Vouches with Certificate | X | X (no alias) | ||||
SAML Holder of Key | X | X (no alias) | ||||
STS Issued Token | X | X | X | |||
STS Issued Token with Service Cert. | X | X | X | |||
STS Issued Endorsing Token | X | X | X |
Keystore: If this column has an
X, select Use Development Defaults, or click the Keystore
button and configure the keystore to specify the alias
identifying the service certificate and private key. For
the GlassFish keystores, the file is
keystore.jks and the alias is
xws-security-server, assuming that you've
updated the GlassFish default certificate stores.
Truststore : If this column has
an X, select Use Development Defaults, or click the
Truststore button and configure the truststore to specify
the alias that contains the certificate and trusted roots
of the client. For the GlassFish keystores, the file is
cacerts.jks and the alias is
xws-security-client , assuming that you've
updated the GlassFish default certificate stores.
STS : If this column has an X, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the section To Create and Secure the STS (STS) . The STS is secured using a separate (non-STS) security mechanism. The security configuration for the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application.
SSL : To use a mechanism that uses secure transport (SSL), you must configure the system to point to the client and server keystore and truststore files. Steps for doing this are described in Configuring SSL For Your Applications .
User in GlassFish : To use a mechanism that requires a user database for authentication, you can add a user to the file realm of GlassFish. Select Use Development Defaults, or follow the instructions for doing this at Adding Users to GlassFish .
Kerberos : This option is only valid for 'Symmetri Binding with Kerberos Tokens' Profile. Click the Kerbeos button to specify the login module to be used for this service. Login Modules can be specified in $GLASSFISH_HOME/domains/domain1/config/login.conf for GlassFish. An example showing use of Kerberos Tokens can be found at Example: Kerberos Token (Kerb).
Summary of Client-Side Configuration Requirements summarizes the options that need to be configured for each of the security mechanisms on the client-side. Each of the columns is briefly discussed after the table.
Table 12.2. Summary of Client-Side Configuration Requirements
Mechanism | Keystore | Truststore | Default User | SAML Callback Handler | STS | SSL | User in GlassFish | Kerberos |
|---|---|---|---|---|---|---|---|---|
Username Authentication with Symmetric Key | X | X | X | |||||
Username Authentication with Password Derived Keys | X | X | ||||||
Mutual Certificates | X | X | ||||||
Symmetric Binding with Kerberos Tokens | X | |||||||
Transport Security | X | X | ||||||
Message Authentication over SSL - Username Token | X | X | X | |||||
Message Authentication over SSL - X.509 Token | X | X | ||||||
SAML Authorization over SSL | X | X | X | X | ||||
Endorsing Certificate | X | X | ||||||
SAML Sender Vouches with Certificate | X | X | X | |||||
SAML Holder of Key | X | X | X | |||||
STS Issued Token | X | X | X | |||||
STS Issued Token with Service Certificate | X | X | X | |||||
STS Issued Endorsing Token | X | X | X |
Keystore: If this column has an
X, select Use Development Defaults, or click Keystore to
configure the keystore to point to the alias for the
client certificate. For the GlassFish keystores, the
keystore file is keystore.jks and the alias
is xws-security-client, assuming that you've
updated the GlassFish default certificate stores.
Truststore: If this column has
an X, select Use Development Defaults, or click Truststore
to configure the truststore that contains the certificate
and trusted roots of the server. For the GlassFish
keystores, the file is cacerts.jks and the
alias is xws-security-server , assuming that
you've updated the GlassFish default certificate stores as
described in To Manually Update GlassFish Certificates.
When using an STS mechanism, the client specifies
the truststore and certificate alias for the STS, not the
service. For the GlassFish stores, the file is
cacerts.jks and the alias is
wssip.
Default User: When this column has an X, you must configure either a default username and password, a UsernameCallbackHandler, or leave these options blank and specify a user at runtime. More information on these options can be found at Configuring Username Authentication on the Client.
SAML Callback Handler : When this column has an X, you must specify a SAML Callback Handler. Examples of SAML Callback Handlers are described in Example SAML Callback Handlers.
STS : If this column has an X, you must have a Security Token Service that can be referenced by the service. An example of an STS can be found in the sectionTo Create and Secure the STS (STS). The STS is secured using a separate (non-STS) security mechanism. The security configuration for the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application. Note that on the service side, it is optionally to set Issuer for the STS to be used. You only need to configure the STS information on the client side if Issuer if not available in the service wsdl. If both configured, the service side Issuer takes high priority.
SSL : To use a mechanism that uses secure transport (SSL), you must configure the system to point to the client and server keystore and truststore files. Steps for doing this are described in Configuring SSL For Your Applications.
User in GlassFish: To use a
mechanism that requires a user database for
authentication, select Use Development Defaults, or add a
user to the file realm of GlassFish.
Instructions for doing this can be found at Adding Users to GlassFish.
Kerberos: This option is only valid for 'Symmetric Binding with Kerberos Tokens' profile. Click Kerberos button to configure the Login Module and Service Principal to be used by client, and if credential delegation should be set. An example showing use of Kerberos Tokens can be found at Example: Kerberos Token (Kerb).
On the client side, a user name and password must be configured for some of the security mechanisms. For this purpose, you can use the default Username and Password Callback Handlers (when deploying to GlassFish), specify a SAML Callback Handler, specify a default user name and password for development purposes, create and specify your own Callback Handlers if the container you are using does not provide defaults, or specify the username and password dynamically at runtime. When using any of these options, you must create an authorized user on GlassFish using the Admin Console, as described in Adding Users to GlassFish.
To Configure Username Authentication on the Client
Once you've created an authorized user and determined how your application needs to specify the user, configure the Username Authentication options as follows.
In the Projects window, expand the node for the web service client.
Expand the Web Service References node.
Right-click the node for the web service reference for which you want to configure security options.
Select Edit Web Service Attributes.
Select the Quality of Service tab to display the WSIT Security options.
Expand the Security section to specify the user name and password information as required by the service. The dialog appears as shown in Quality of Service - Client - Security.
The following options are available.
Currently the GlassFish
CallbackHandler cannot handle the
following: SAML Callbacks and Require ThumbPrint
Reference assertions under an X.509 Token. This may
be addressed in a future milestone.
Use Development Defaults:
Select this option to import certificates into the GlassFish keystore and truststore so that they can be used immediately for development. The WSIT message security mechanisms require the use of v3 certificates. The default GlassFish keystore and truststore do not contain v3 certificates at this time. In order to use message security mechanisms with GlassFish, it is necessary to obtain keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.
In addition to importing certificates, when
this option is selected a default user is created in
the file realm with username
wsitUser.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
Authentication Credentials: Select Static or Dynamic. Select Static to supply a static username and password, or select Dynamic and specify the Username and Password CallbackHandlers. Select Static if you want to fill in the exact user credentials that the client is providing, and which cannot be changed after deployment. Static is useful to developing and testing applications prior to deployment. Select Dynamic to use CallbackHandlers to provide a dynamic way to provide credentials. Dynamic is useful if the credentials need to be obtained from some third party, for example, or if the developer doesn't want to store the user name and password in a configuration file because it might introduce a security risk.
Default Username,
Default Password : These
options are available when Static is selected as the
Authentication Credential. Type the name of an
authorized user and the password for this user. This
option is best used only in the development
environment. When the Default Username and Default
Password are specified, the username and password
are stored in the wsit-client.xml file
in clear text, which presents a security risk. Do
not use this option for production.
Default Username Callback
Handler, Default Password
Callback Handler : These options are
available when the Authentication Credential is
Dynamic. If you create JSR-109-compliant web
services and web service clients that run under an
Application Server container (JSR-109 deployment),
the container handles the callbacks and you do not
need to configure Callback Handlers of your own. If
you are using another container, select the Browse
button to select the class implementing the
javax.security.auth.callback.CallbackHandler
interface.
SAML Callback Handler : To use a SAML Callback Handler, you need to create one, as there is no default. References to example SAML Callback Handlers are provided in Example SAML Callback Handlers. An example that uses a SAML Callback Handler can be found in Example: SAML Authorization over SSL (SA).
Timestamp Timeout: This property specifies the duration(in seconds) for which timestamp should be considered valid. The default is 5 mins(300 seconds).
Creating a SAML Callback Handler is beyond the scope of this document. However, the following web pages may be helpful for this purpose:
A client-side configuration, which includes a SAML Callback Handler, can be viewed at the following URL:
An example of a SAML Callback Handler can be viewed and/or downloaded from the following URL:
http://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
An example application in this tutorial that uses a SAML Callback Handler can be found in Example: SAML Authorization over SSL (SA) .
When writing SAML Callback Handlers for different security mechanisms, set the subject confirmation method to SV (Sender Vouches) or HOK (Holder of Key) and the appropriate SAML Assertion version depending on the SAML version and SAML Token Profile selected when setting the security mechanism for the service. When the subject confirmation method is HOK, a keystore and truststore file must be configured in the SAMLCallbackHandler. When the method is SV, you can either comment out the keystore and truststore information, or leave it, as it will not be used.
For example, the following code snippet for one of the SAMLCallbackHandlers listed above demonstrates how to set the subject confirmation method and sets the SAMLAssertion version to 1.0, profile 1.0.
Example 12.1.
if (callbacks[i] instanceof SAMLCallback) {
try {
SAMLCallback samlCallback = (SAMLCallback) callbacks[i];
/*
Set confirmation Method to SV [SenderVouches] or
HOK[Holder of Key]
*/
samlCallback.setConfirmationMethod(samlCallback
.SV_ASSERTION_TYPE);
if (samlCallback.getConfirmationMethod().equals
(samlCallback.SV_ASSERTION_TYPE)) {
samlCallback.setAssertionElement
(createSVSAMLAssertion());
svAssertion_saml10 = samlCallback.getAssertionElement();
/*
samlCallback.setAssertionElement
(createSVSAMLAssertion20());
svAssertion_saml20 =
samlCallback.getAssertionElement();
*/
} else if (samlCallback.getConfirmationMethod().equals
(samlCallback.HOK_ASSERTION_TYPE)) {
samlCallback.setAssertionElement
(createHOKSAMLAssertion());
hokAssertion_saml10 = samlCallback
.getAssertionElement();
/*
samlCallback.setAssertionElement
(createHOKSAMLAssertion20());
hokAssertion_saml20 =
samlCallback.getAssertionElement();
*/
}
} catch (Exception e) {
e.printStackTrace();
}
} else {
throw unsupportedCallback;
}This section describes security mechanisms you can implement with WSIT. This section provides an overview of the following mechanisms:
A table that summarizes the configuration options on the server side is available in Summary of Service-Side Configuration Requirements.
Some common communication issues that need to be addressed using security mechanisms are discussed in Using Security Mechanisms.
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.
See Also: Example: Username Authentication with Symmetric Key (UA).
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
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.
See Also: Example: Mutual Certificates Security (MCS).
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.
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.
See Also: Example: Kerberos Token (Kerb).
The Transport Security mechanism protects your application during transport using SSL for authentication and confidentiality. Transport-layer security is provided by the transport mechanisms used to transmit information over the wire between clients and providers, thus transport-layer security relies on secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). Transport security is a point-to-point security mechanism that can be used for authentication, message integrity, and confidentiality. When running over an SSL-protected session, the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data. Security is "live" from the time it leaves the consumer until it arrives at the provider, or vice versa. The problem is that it is not protected once it gets to its destination. For protection of data after it reaches its destination, use one of the security mechanisms that uses SSL and also secures data at the message level.
Digital certificates are necessary when running secure HTTP transport (HTTPS) using Secure Sockets Layer (SSL). The HTTPS service of most web servers will not run unless a digital certificate has been installed. Digital certificates have already been created for GlassFish, and the default certificates are sufficient for running this mechanism, and are required when using Atomic Transactions (see Using Atomic Transactions ). However, the message security mechanisms require a newer version of certificates than is available with GlassFish. You can download valid keystore and truststore files for the client and server as described in To Manually Update GlassFish Certificates.
To use this mechanism, follow the steps in Configuring SSL For Your Applications.
See Also: Example: Transport Security (SSL).
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.
If you use the fully-qualified hostname (FQHN) in
the URL for the service WSDL when you are adding the web
service client to the client application, this workaround
is not required. It is only required when you specify
localhost in the URL for the service
WSDL.
During development (not production) it is sometimes convenient to use certificates whose CN (Common Name) does not match the host name in the URL.
A developer would want to use a CN which is different
from the host name in the URL in WSIT when using
https addresses in Dispatch clients and during
wsimport . The below mentioned workaround is only
for the Dispatch clients, which are also used in WS-Trust to
communicate with STS. This has to be done even if the client's
main service is not on https, but only the STS is on
https.
Java by default verifies that the certificate CN (Common Name) is the same as host name in the URL. If the CN in the certificate is not the same as the host name, your web service client fails with the following exception:
Example 12.2.
javax.xml.ws.WebServiceException: java.io.IOException: HTTPS hostname wrong: should be <hostname as in the certificate>
The recommended way to overcome this issue is to generate the server certificate with the Common Name (CN) matching the host name.
To work around this only during development, in your client code, you can set the default host name verifier to a custom host name verifier which does a custom check. An example is given below. It is sometimes necessary to include this in the static block of your main Java class as shown below to set this verifier before any connections are made to the server.
Example 12.3.
static {
//WORKAROUND. TO BE REMOVED.
javax.net.ssl.HttpsURLConnection.setDefaultHostnameVerifier(
new javax.net.ssl.HostnameVerifier(){
public boolean verify(String hostname,
javax.net.ssl.SSLSession sslSession) {
if (hostname.equals("mytargethostname")) {
return true;
}
return false;
}
});
} Please remember to remove this code once you install valid certificates on the server.
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.
The SAML Authorization over SSL mechanism attaches an authorization token with the message and uses SSL for confidentiality protection. In this mechanism, the SAML token is expected to carry some authorization information about an end user. The sender of the token is actually vouching for the credentials in the SAML token.
To use this mechanism, configure SSL on the server, as described in Configuring SSL For Your Applications, and, on the clients side, configure a SAMLCallbackHandler as described in Example SAML Callback Handlers.
See Also: Example: SAML Authorization over SSL (SA).
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.
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.
See Also: Example: SAML Sender Vouches with Certificates (SV).
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.
This security mechanism protects messages using a token issued by a trusted Secure Token Service (STS) for message integrity and confidentiality protection.
An STS is a service that implements the protocol defined in the WS-Trust specification (you can find a link to this specification at https://eclipse-ee4j.github.io/metro-wsit ). 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.
See Also: Example: STS Issued Token (STS).
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.
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.
This section discusses configuring security for your web service and web service client using the WSIT security mechanisms. Some of these mechanisms require some configuration outside of NetBeans IDE. Depending upon which security mechanism you plan to use, some of the following tasks will need to be completed:
If you are using the GlassFish container and message security, you must update the GlassFish keystore and truststore by importing v3 certificates. The procedure for updating the certificates is described in To Manually Update GlassFish Certificates.
If you are using a security mechanism that requires a user to enter a user name and password, create authorized users for your container. Steps for creating an authorized user for the GlassFish container are described in Adding Users to GlassFish.
To use a mechanism that uses secure transport (SSL), you must configure the system to point to the client and server keystore and truststore files. Steps for doing this are described in Configuring SSL For Your Applications.
This section covers the following topics:
This section describes adding the steps to configure your application for SSL. These steps will need to be accomplished for any application that uses one of the mechanisms:
To Configure SSL for Your Application
The following steps are generic to any application, but have example configurations that will work with the tutorial examples, in particular, Example: SAML Authorization over SSL (SA) and Example: Transport Security (SSL).
To configure SSL for your application, follow these steps.
Select one of the mechanisms that require SSL.
These include Transport Security (SSL), Message Authentication over SSL, andSAML Authorization over SSL.
Server Configuration
GlassFish is already configured for SSL. No further SSL configuration is necessary if you are using Transport Security. However, if you are using one of the Message Security mechanisms with SSL, you must update the GlassFish certificates as described in To Manually Update GlassFish Certificates.
Configure a user on GlassFish as described in Adding Users to GlassFish.
Client Configuration
For configuring your system for SSL in order to work through the examples in this tutorial, the same keystore and truststore files are used for both the client and the service. This makes it unnecessary to set system properties to point to the client stores, as both GlassFish and NetBeans IDE are aware of these certificates and point to them by default.
In general, for the client side of SSL you will
not be using the same certificates for the client and
the service. In that case, you need to define the
client certificate stores by setting the system
properties -Djavax.net.ssl.trustStore ,
-Djavax.net.ssl.keyStore ,
-Djavax.net.ssl.trustStorePassword , and
-Djavax.net.ssl.keyStorePassword in the
application client container.
You can specify the environment variables for
keystore and truststore by setting the environment
variable VMARGS through the shell
environment or inside an Ant script, or by passing
them in when you start NetBeans IDE from the command
line. For example, in the latter case, you would
specify the property settings as follows:
netbeans-install/bin/netbeans.exe
-J-Djavax.net.ssl.trustStore=as-install/domains/domain1/config/cacerts.jks
-J-Djavax.net.ssl.keyStore=as-install/domains/domain1/config/keystore.jks
-J-Djavax.net.ssl.trustStorePassword=changeit
-J-Djavax.net.ssl.keyStorePassword=changeitUse 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.
The IDE appears as shown in Deployment Descriptor Page.
Click the XML tab to
display the additions to web.xml . The
security constraint looks like this:
Example 12.4.
<security-constraint>
<display-name>Constraint1</display-name>
<web-resource-collection>
<web-resource-name>CalcWebResource</web-resource-name>
<description/>
<url-pattern>/*</url-pattern>
<http-method>POST</http-method>
</web-resource-collection>
<user-data-constraint>
<description/>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint> 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.
This section describes the following tasks:
To Add a User to GlassFish for Development
To create a user in the GlassFish file realm to be used for testing and development purposes, follow these steps.
In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
In addition to setting up keystore and
truststore files, this option creates a default user
on GlassFish. The user has the name
wsitUser and the password of
changeit .
To Add Users to GlassFish Using the Admin Console
To add users to GlassFish using the Admin Console, follow these steps.
Start GlassFish if you haven't already done so.
Start the Admin Console if you haven't already done so.
You can start the Admin Console by starting a
web browser and specifying the URL
http://localhost:4848/asadmin . If you
changed the default Admin port during installation,
type the correct port number in place of 4848.
To log in to the Admin
Console, type the user name and password of a user in
the admin-realm who belongs to the
asadmin group.
The name ( admin ) and password (
adminadmin ) entered during installation
will work, as will any users added to this realm and
group subsequent to installation.
Expand the Configuration node in the Admin Console tree.
Expand the Security node in the Admin Console tree.
Expand the Realms node,
then select the file realm.
Click the Manage Users button.
Click New to add a new user to the realm.
Type the correct information into the User ID, Password, and Group(s) fields.
The example applications reference a user with the following attributes:
User ID = wsitUser
Group List = wsit
New Password = changeit
Confirm New Password =
changeit
Click OK to add this user to the list of users in the realm.
Click Logout when you have completed this task.
This section describes configuring keystores and truststores. Security mechanisms that use certificates require keystore and truststore files for deployment.
For GlassFish, default keystore and truststore files come bundled. However, WSIT security mechanisms for message security require X.509 version 3 certificates. GlassFish contains version 1 certificates. Therefore, to enable the WSIT applications to run on GlassFish, you will need to follow the instructions in To Manually Update GlassFish Certificates .
For Tomcat, keystore and truststore files do not come bundled with this container, so they must be provided. You can download valid keystore and truststore files for the client and server from http://xwss.java.net/ .
This section covers the following topics:
To Automatically Update GlassFish Certificates
You can have NetBeans automatically update the GlassFish certificates to the version needed to work with message security. To do this, follow these steps:
In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
This option imports certificates into the GlassFish keystore and truststore so that they can be used immediately for development.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
To Manually Update GlassFish Certificates
The WSIT message security mechanisms require the use of v3 certificates. The default GlassFish keystore and truststore Unhandled tag varname do not contain v3 certificates at this time (but should before FCS). (GlassFish instances installed using JDK 1.6 do have a v3 certificate but the certificate lacks a particular extension required for supporting some secure WSIT mechanisms.) In order to use message security mechanisms with GlassFish, it is necessary to download keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.
The XWSS keystores are sample keystores containing sample v3 certificates. These sample keystores can be used for development and testing of security with WSIT technology. Once an application is in production, you should definitely use your own v3 certificates issued by a trusted authority. In order to use WSIT security on GlassFish, you will have to import your trusted stores into GlassFish's keystore and specify those certificates from NetBeans IDE.
To manually update the GlassFish certificates, follow these steps.
Download the zip file that
contains the certificates and the Ant scripts (
copyv3.zip ) by going to this URL:
https://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
Unzip this file and change
into its directory, copyv3 .
Set the variable to the
location where GlassFish is installed, as described in the
README.txt file in this directory.
From the copyv3
directory, execute the Ant command that will copy the
keystore and truststore files to the appropriate location,
and import the appropriate certificates into the GlassFish
keystore and truststore.
This Ant command is as follows:
as-install/lib/ant/bin/antThe command window will echo back the certificates that are being added to the keystore and truststore files, and should look something like this:
[echo] WARNING: currently we add non-CA certs to GF truststore, this will not be required in later releases when WSIT starts supporting CertStore(s) [java] Added Key Entry :xws-security-server [java] Added Key Entry :xws-security-client [java] Added Trusted Entry :xwss-certificate-authority [java] Added Key Entry :wssip [java] Added Trusted Entry :xws-security-client [java] Added Trusted Entry :xws-security-server [java] Added Trusted Entry :wssip [echo] Adding JVM Option for https outbound alias, this will take at least One Minute. ...
To verify that the updates were successful, follow these steps:
Change to the directory
containing the GlassFish keystore and truststore
files, as-install /domains/domain1/config
.
Verify that the v3
certificate has been imported into the GlassFish
truststore. To do this, run the following
keytool command (all on one line):
java-home/bin/keytool -list -keystore cacerts.jks -alias wssip -storepass changeitIf the certificates are successfully updated, your response will look something like this:
wssip, Aug 20, 2007, trustedCertEntry, Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1
If the certificates were not successfully update, your response will look something like this:
keytool error: java.lang.Exception: Alias <wssip> does not exist
Verify that the v3
certificate has been imported into the GlassFish
keystore. To do this, run the following
keytool commands:
java-home/bin/keytool -list -keystore keystore.jks
-alias xws-security-server -storepass changeit
java-home/bin/keytool -list -keystore keystore.jks
-alias xws-security-client -storepass changeitIf the certificates were successfully updated, your response should look something like this:
xws-security-server, Aug 20, 2007, PrivateKeyEntry, Certificate fingerprint (MD5): E4:E3:A9:02:3C:B0:36:0C:C1:48:6E:0E:3E:5C:5E:84
If your certificates were not successfully updated, your response will look more like this:
keytool error: java.lang.Exception: Alias <xws-security-server> does not exist
The configuration of the aliases for all containers (Tomcat, GlassFish) and for all applications (JSR-109-compliant and non-JSR-109-compliant), except for applications that use a Security Token Service (STS) mechanism, is as shown in Keystore and Truststore Aliases .
Table 12.3. Keystore and Truststore Aliases
Keystore Alias | Truststore Alias | |
|---|---|---|
Client-Side Configuration | xws-security-client | xws-security-server |
Server-Side Configuration | xws-security-server | xws-security-client |
The configuration of the aliases for applications that use a Security Token Service (STS) mechanism is as shown in Keystore and Truststore Aliases for STS .
Table 12.4. Keystore and Truststore Aliases for STS
Keystore Alias | Truststore Alias | |
|---|---|---|
Client-Side Configuration | xws-security-client | xws-security-server |
STS Configuration | xws-security-client | wssip |
NetBeans IDE already knows the location of the default keystore file and its password, but you need to specify which alias is to be used. The following sections discuss configuring the keystore on the service and on the client.
To Configure the Keystore on a Service Automatically
To have NetBeans IDE configure the keystore to its default values, follow these steps.
In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
This option imports certificates into the GlassFish keystore and truststore so that they can be used immediately for development. This option also inserts the location and alias of the keystore and truststore files into the configuration file.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
To Configure the Keystore on a Service Manually
A keystore is a database of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. A key is a piece of information that controls the operation of a cryptographic algorithm. For example, in encryption, a key specifies the particular transformation of plaintext into ciphertext, or vice versa during decryption. Keys are used in digital signatures for authentication.
To configure a keystore on a service, perform the following steps.
Check the table in Summary of Service-Side Configuration Requirements to see if a keystore needs to be configured for the selected security mechanism. If so, continue.
Right-click the web service and select Edit Web Service Attributes.
The Web Service Attributes editor is displayed.
Enable Secure Service, then select a security mechanism.
Check the table in Summary of Service-Side Configuration Requirements to see what keystore configuration, if any, is required for that mechanism.
Unselect Use Development Defaults.
Click the Keystore button. The dialog shown in Keystore Configuration Dialog displays.
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.
The Key Password field enables you to specify
a password for the keystore used by the application.
When specified, this password is stored in a WSIT
configuration file in clear text, which is a
security risk. Setting the keystore password in the
development environment is fine, however, when you
go into production, remember to use the container's
Callback Handler to obtain the keys from the
keystore. This eliminates the need for the keystore
passwords to be supplied by the users. You can also
specify the passwords for keystores and truststores
by specifying a Callback Handler class that
implements the
javax.security.auth.callback.CallbackHandler
interface in the Key Password or Store Password
fields.
When creating JSR-109-compliant application, GlassFish will only use the default CallbackHandlers and Validators, and you cannot override the location of the keystore and truststore files. Any attempt to override the default location will be ignored. You do, however, need to specify the keystore and truststore locations in these dialogs in order to specify the alias.
When creating non-JSR-109-compliant application,
you can specify the passwords for keystores and
truststores by specifying a
CallbackHandler class that implements the
javax.security.auth.callback.CallbackHandler
interface in the Key Password or Store Password
fields.
Click OK to close the dialog.
To Configure the Truststore on a Service Automatically
To have NetBeans IDE configure the truststore to its default values, follow these steps.
In NetBeans IDE, right-click the web service, select Edit Web Service Attributes.
Select Secure Service.
Select Use Development Defaults.
This option imports certificates into the GlassFish keystore and truststore so that they can be used immediately for development. This option also inserts the location and alias of the keystore and truststore files into the configuration file, when required for a selected security mechanism.
In a production environment, you should provide your own certificates and user settings, however, in a development environment you may find these defaults useful.
To Configure the Truststore on a Service Manually
A truststore is a database of trusted entities and their associated X.509 certificate chains authenticating the corresponding public keys.
The truststore contains the Certificate Authority (CA) certificates and the certificates of the other party to which this entity intends to send encrypted (confidential) data. This file must contain the public key certificates of the CA and the client's public key certificate. Any kind of encryption without WS-SecureConversation will generally require that a truststore be configured on the client side. Any kind of signature without WS-SecureConversation will generally require a truststore on the server side.
For this release, place the trusted certificates
of other parties in GlassFish's truststore,
cacerts.jks . This is not normally a
recommended practice because any certificate you add
to the cacerts.jks file effectively means
it can be a trusted root for any and all certificate
chains, which can be a security problem. In future
releases, trusted certificates from other parties will
be placed in a certstore, and only trusted roots will
be placed inside cacerts.jks .
To set the truststore configuration options on a service, perform the following steps.
Check the table in Summary of Service-Side Configuration Requirements to see if a truststore is required for the selected security mechanism. If so, continue.
Right-click the web service and select Edit Web Service Attributes.
The Web Service Attributes editor is displayed.
Enable Secure Service.
Unselect Use Development Defaults.
Click the Truststore button.
On the Truststore Configuration page, specify the following options:
Location : By default,
the location and name of the truststore that stores
the public key certificates of the CA and the
client's public key certificate is already entered.
The GlassFish truststore file is as-install
/domains/domain1/config/cacerts.jks.
Store Password :
Specifies the password for the truststore. If you
are using GlassFish, the value of
changeit is already entered. If you
have changed the value of the truststore password,
you must type the new value in this field.
The Store Password field enables you to
specify a password for the truststore used by the
application. When specified, this password is stored
in a WSIT configuration file in clear text, which is
a security risk. Setting the truststore password in
the development environment is fine, however, when
you go into production, remember to use the
container's Callback Handler to obtain the keys from
the truststore. This eliminates the need for the
truststore passwords to be supplied by the users.
You can also specify the passwords for keystores and
truststores by specifying a CallbackHandler class
that implements the
javax.security.auth.callback.CallbackHandler
interface in the Key Password or Store Password
fields.
When creating JSR-109-compliant application, GlassFish will only use the default CallbackHandlers and Validators, and you cannot override the location of the keystore and truststore files. Any attempt to override the default location will be ignored. You do, however, need to specify the keystore and truststore locations in these dialogs in order to specify the alias.
Load Aliases : Click the Load Aliases button to populate the Alias field with the aliases contained in the truststore file. The Location and Store Password fields must be specified correctly for this option to work.
Alias : Unhandled tag tip Specifies the peer alias of the certificate in the truststore that is to be used when the client needs to send encrypted data. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism. A truststore contains trusted other-party certificates and certificates of Certificate Authorities (CA). A peer alias is the alias of the other party (peer) that the sending party needs to use to encrypt the request.
Click OK to close the dialog.
To Configure the Keystore and Truststore on a Client
On the client side, a keystore and truststore file must be configured for some of the security mechanisms. Refer to the table in Summary of Client-Side Configuration Requirements for information on which mechanisms require the configuration of keystores and truststores.
If the mechanism configured for the service requires the configuration of keystores and truststores, follow these steps.
Check the table in Summary of Client-Side Configuration Requirements to see if a keystore needs to be configured for the client for the selected security mechanism. If so, continue.
In the Projects window, expand the node for the web service client.
Expand the Web Service References node.
Right-click the node for the web service reference for which you want to configure security options.
Select Edit Web Service Attributes.
When the Web Service References Attributes Editor is opened, select the Quality of Service tab to display the WSIT Security options.
Click Keystore or Truststore to specify the keystore or truststore information if required by the service.
Depending on what is required for the selected mechanism, you may specify the following information:
Keystore Location : The
directory and file name containing the certificate
key to be used to authenticate the client. By
default, the location is already set to the default
GlassFish keystore, as-install
/domains/domain1/config/keystore.jks
.
Keystore Password : The
password for the keystore used by the client. By
default, the password for the GlassFish keystore is
already entered. This password is
changeit .
When specified, this password is stored in a
WSIT configuration file in clear text. Setting the
keystore password in the development environment is
fine, however, when you go into production, remember
to use the container's default
CallbackHandler to obtain the keys from
the keystore. This eliminates the need for the
keystore passwords to be supplied by the users. You
can also specify the passwords for keystores and
truststores by specifying a
CallbackHandler class that implements
the
javax.security.auth.callback.CallbackHandler
interface in the Keystore Password, Truststore
Password, or Key Password fields.
Load Aliases : Click this button to populate the Alias list with all of the certificates available in the selected keystore. This option will only work if the keystore location and password are correct.
Keystore Alias : Select the alias in the keystore. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism.
Key Password : If the
client key has been password-protected, type the
password for this key. The GlassFish certificate key
password is changeit .
Truststore Location : The
directory and file name of the client truststore
containing the certificate of the server. By
default, this field points to the default GlassFish
truststore, as-install
/domains/domain1/config/cacerts.jks.
Truststore Password : The
password for the truststore used by the client. By
default, the password for the GlassFish truststore
is already specified. The password is
changeit .
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.
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 Java SE 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.
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.
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.
Specify the JAAS login modules to be used for Kerberos in the $GLASSFISH_HOME/domains/domain1/config/login.conf file, as follows:
KerberosClient {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=true;
}
KerberosServer {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true keyTab="/etc/krb5.keytab"
doNotPrompt=true storeKey=true
principal="websvc/service@INDIA.SUN.LOCAL";
}You can give any names to the login modules, that is, instead of KerberosClient and KerberosServer. You need to refer to these names in the <sc:KerberosConfig> assertion in the WSDL file and in the wsit-client.xml file.
Also edit the principal in KerberosServer to the service_principal that you created, and specify the correct location of krb5.keytab file.
GlassFish picks the login modules from $GLASSFISH_HOME/domains/domain1/config/login.conf. In Tomcat we need to specify the file explicitly using java.security.auth.login.config system property. Here are the steps:
Create a file jaas.conf , and place it in $CATALINA_HOME/conf. Here's what jaas.conf looks like:
KerberosClient {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=true;
};
KerberosServer {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true keyTab="/etc/krb5.keytab"
doNotPrompt=true storeKey=true
principal="websvc/service@INDIA.SUN.COM";
};Add following line to the catalina.sh script (or specify the mentioned JAVA_OPTS property):
JAVA_OPTS="$JAVA_OPTS "-Djava.security.auth.login.config=$CATALINA_HOME/conf/jaas.conf
Specify the following system property in your client code:
-Djava.security.policy=${tomcat.home}/conf/catalina.policy
-Djava.security.auth.login.config=${tomcat.home}/conf/jaas.confThis section explains how to specify security mechanisms at the operation level and at the message level.
You can specify security mechanisms at the following levels:
Operation
At times, you may need to configure different operations with different supporting tokens. You may wish to configure security at the operation level, for example, in the situation where only one operation requires a UsernameToken to be passed and the rest of the operations do not require this, or in the situation where only one operation needs to be endorsed by a special token and the others do not.
Input Message and Output Message
Security mechanisms at this level are used to specify what is being protected and the level of protection required.
In this section, you can specify parts of a message that
require integrity protection (digital signature) and/or
confidentiality (encryption). When you do this, the specified
part of the message, outside of security headers, requires
signature and/or encryption. For example, a message producer
might submit an order that contains an orderID
header. The producer signs and/or encrypts the
orderID header (the SOAP message header) and the
body of the request (the SOAP message body). Parts that can be
signed and/or encrypted include the body, the header, the
local name of the SOAP header, and the namespace of the SOAP
header.
You can also specify arbitrary elements in the message that require integrity protection and/or confidentiality. Because of the mutability of some SOAP headers, a message producer may decide not to sign and/or encrypt the SOAP message header or body as a whole, but instead sign and/or encrypt elements within the header and body. Elements that can be signed and/or encrypted include an XPath expression or a URI which indicates the version of XPath to use.
This section covers the following topics:
To Specify Security at the Operation, Input Message, or Output Message Level
To specify security mechanisms at the level of the operation, input message, or output message, perform the following steps.
Right-click the web service and select Web Service Attributes.
The Web Service Attributes editor is displayed.
Select Secure Service.
Select a security mechanism.
The following mechanisms do not support Input message level protection:
Expand the
operation Operation node (for
example, the add Operation node.) It should
look like Web Service Attributes Editor Page: Operation
Level.
Expand the operation section.
The section will be grayed out if Secure Service is not selected.
Select an option from the Transactions list to specify a level at which transactions will be secured.
For this release, transactions will only use SSL for security. Transactions are discussed in Using Atomic Transactions.
Expand the Input Message section.
This section will be grayed out if Secure Service is not selected.
Specify the following options, as appropriate:
Authentication Token : Specifies which supporting token will be used to sign and/or encrypt the specified message parts. Options include Username, X509, SAML, Issued, or None. For further description of these options, read Supporting Token Options.
Signed : Specifies that the authentication token must be a signed, supporting token. A signed, supporting token is signed by the primary signature token and is part of primary signature.
Endorsing : Specifies that the authentication token must be endorsed. With an endorsing supporting token, the key represented by the token is used to endorse/sign the primary message signature.
Encrypted: Specifies that the authentication token must be an encrypted supporting token.
One can select any (or none) combination of the three options above. If both Signed and Endorsing are selected, the authentication token must be a signed, endorsing, supporting token. In this situation, the token is signed by the primary signature. The key represented by the token is used to endorse/sign the primary message signature. If Encrypted is selected as well, the supporting token is also encrypted in the request message.
For the Input Message and/or Output Message, click the Message Parts button to specify which parts of the message need to be encrypted, signed, and/or required.
See the following section for more information on the options in the Message Parts dialog.
The Message Parts dialog appears. It should look like Web Service Attributes Editor Page: Message Parts.
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.
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.
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.
You can use one of the following options for supporting tokens:
Username Token: A username token is used to identify the requestor by their username, and optionally using a password (or shared secret, or password equivalent) to authenticate that identity. When using a username token, the user must be configured on GlassFish. For information on configuring users on GlassFish, read Adding Users to GlassFish.
X.509 Certificate: An X.509 certificate specifies a binding between a public key and a set of attributes that includes (at least) a subject name, issuer name, serial number, and validity interval. An X.509 certificate may be used to validate a public key that may be used to authenticate a SOAP message or to identify the public key with a SOAP message that has been encrypted. When this option is selected, you must specify a truststore. For information on specifying a truststore, read To Configure the Truststore on a Service Manually.
Issued Token : An issued token is a token issued by a trusted Secure Token Service (STS). The service does not trust the client directly, but instead trusts tokens issued by a designated STS. In other words, the STS is taking on the role of a second service with which the client has to securely authenticate. The issued tokens contain a key, which is encrypted for the server and which is used for deriving new keys for signing and encrypting.
SAML Token : A SAML Token uses Security Assertion Markup Language (SAML) assertions as security tokens.
A Secure Token Service (STS) is a Web service that issues security tokens. That is, it makes assertions based on evidence that it trusts, to whoever trusts it (or to specific recipients). To communicate trust, a service requires proof, such as a signature, to prove knowledge of a security token or set of security tokens. A service itself can generate tokens or it can rely on a separate STS to issue a security token with its own trust statement (note that for some security token formats this can just be a re-issuance or co-signature). This forms the basis of trust brokering.
The issued token security model includes a target service, a client, and a trusted third party called a Security Token Service (STS). Policy flows from service to client, and from STS to client. Policy may be embedded inside an issued token assertion, or acquired out-of-hand. There must be an explicit trust relationship between the service and the STS and the client and the STS. There does not need to be a trust relationship between the client and service.
When the web service being referenced by the client uses any of the STS security mechanisms (refer to tables in Summary of Service-Side Configuration Requirements and Summary of Client-Side Configuration Requirements ), an STS must be specified. You can specify the STS in the following ways.
On the service side, specify the endpoint of the Issuer element and/or specify the Issuer Metadata Exchange (Mex) address of the STS.
If you need to create a third-party STS, follow the steps in To Create a Third-Party STS .
For more information on managing the STS, see Managing multiple services with Metro based STS .
If you already have an STS that you want to use, follow the steps in To Specify an STS on the Service Side .
An example that creates and uses an STS can be found at Example: STS Issued Token (STS) .
An example that shows how to achieve the trust brokering between different domains using an STS can be found at Example: Broker Trust STS (BT) .
An example that shows how to use SecureConversation with an STS can be found at Example: STS Issued Token With SecureConversation (STS+SC) .
On the client side, specify the information for a preconfigured STS. This is mainly used for a local STS that is in the same domain as the client. Configuring the STS for the client is described in To Specify an STS on the Client Side .
This section covers the following topics:
To Create a Third-Party STS
Use the STS wizard to create an STS. When using the STS
wizard, provide the name of the STS implementation class. This
class must extend
com.sun.xml.ws.security.trust.sts.BaseSTSImpl .
After completing the steps of the wizard, your application
will contain a new service that is an STS and includes a
provider implementation class, STS WSDL, and a WSIT
configuration file with a predefined set of policies.
To use the STS wizard to create an STS, follow these steps.
Create a new project for the STS by selecting File | New Project.
Select Java Web, then Web Application, then Next.
Type a Project Name, then Next, then the desired Server. Click Finish.
Right-click the STS Project, and select New, then select Other.
Select Web Services from the Categories list.
Select Secure Token Service (STS) from the File Type(s) list.
Click Next.
Type a name for the Web Service Class Name.
Type or select a name for the Package list.
Click Finish.
The IDE takes a while to create the STS. When
created, it appears under the project's Web Services node
as your_STS Service ,
and the Java file appears in the right pane.
The STS wizard creates an implementation of the provider class.
Back in the Projects window, expand the STS project folder, expand the Web Services node, right-click on the web service, and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Make sure Secure Service is selected.
Select a Security Mechanism that is NOT one of the STS mechanisms. The example application uses Username Authentication with Symmetric Key.
Select the Configure button. For the Algorithm Suite option, specify a value that matches the value of the web service. Set the Key Size to 128 if you have not configured Unlimited Strength Encryption. Select OK to close the configuration dialog.
Some of the algorithm suite settings require that Unlimited Strength Encryption be configured in the Java Runtime Environment (JRE), particularly the algorithm suites that use 256 bit encryption. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. Installation instructions are provided in the JCE zip file. You can download JCE from this URL: http://www.oracle.com/technetwork/java/javase/downloads/index.html
Make sure Act as Secure Token Service (STS) is selected.
The default values will create a valid STS.
Optionally, you can change the following configuration options by clicking the Configure button:
Issuer : Specify an
identifier for the issuer for the issued token. This
value can be any string that uniquely identifies the
STS, for example, MySTS .
Contract Implementation
Class : Specify the actual implementation
class for the WSTrustContract interface
that will handle token issuance, validation, and the
like. Default value is
com.sun.xml.ws.security.trust.impl.WSTRustContractImpl
for issuing SAML assertions, or click Browse to
browse to another contract implementation
class.
Life Time of Issued Tokens : The life span of the token issued by the STS. Default value is 36,000 ms.
Encrypt Issued Key : Select this option if the issued key should be encrypted using the service certificate. Default is true.
Encrypt Issued Token : Select this option if the issued token should be encrypted using the service certificate. Default is false.
Optionally, to add one or more Service Providers that have a trust relationship with the STS, click the Add button, and specify the following configuration options:
Provider Endpoint URI : The endpoint URI of the service provider.
Certificate Alias : The alias of the certificate of the service provider in the keystore.
Token Type : The type of
token the service provider requires, for example,
urn:oasis:names:tc:SAML1.0:assertion
.
Key Type : The type of key the service provider requires. The choices are public key or symmetric key. Symmetric key cryptography relies on a shared secret and is usually faster than public key cryptography. Public key cryptography relies on a key that is made public to all and is primarily used for encryption but can be used for verifying signatures.
Click OK to close the Select STS Service Provider dialog, if open.
Click OK to close the STS Configuration dialog, if open.
Click the Keystore button to configure the keystore.
If you are using the GlassFish stores, click the
Load Aliases button and select wssip .
Otherwise, browse to the location of your keystore and
enter the relevant information.
Click OK to close the dialog.
Right-click the STS Project
and select Properties. Select the Run category, and type
the following in the Relative URL field: /
your_STS Service?wsdl .
Run the Project (right-click the Project and select Run). The STS WSDL displays in a browser window.
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 Section 2.6, “Using Eclipse implementation of Jakarta XML Web Services / Metro with Java SE” for more details.
Check Building custom STS to build a custom STS to control the user attributes to be included in the SAML assertion.
Managing multiple services with Metro based STS
Metro based STS can be used to secure multiple services. One need to register a service provider to an STS before the issued tokens of the STS can be used for that service.
Each resgisted service comes up as a ServiceProvide in the STSConfiguration:
Example 12.5.
<tc:STSConfiguration
xmlns:tc="http://schemas.sun.com/ws/2006/05/trust/server"
encryptIssuedKey="true" encryptIssuedToken="false">
<tc:LifeTime>36000</tc:LifeTime>
<tc:Contract>com.sun.xml.ws.security.trust.impl.WSTrustContractImpl
</tc:Contract>
<tc:Issuer>SunSTS</tc:Issuer>
<tc:ServiceProviders>
<tc:ServiceProvider endPoint="http://localhost:8080/jaxws-s5/simple">
<tc:CertAlias>bob</tc:CertAlias>
<tc:TokenType>
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1
#SAMLV1.1
</tc:TokenType>
</tc:ServiceProvider>
<!-- more service providers -->
</tc:ServiceProviders>
</tc:STSConfiguration>At the minimum, you need to specify the endpoint as well as the cert alias for each service provider. At run time, the actual service is identified for each request RST from a client to the STS. The RST contains an AppliesTo element pointing to the endpoint of the targeted service. On the STS side, the certificate of the service is used to encrypt the issued tokens and proof keys for the service.
With Netbeans, one can add Service Providers to an STS through the configuration panel for STS:
Click Configure button besides Act as Secure Token Service (STS).
In the STS Configuration panel, click Add
In the Select Service Provider panel, add information of the service provider. Note that you must import the certificate of the service provider to the TrustStore of the STS.
We provide a default Service Provider with endpoint="default". This default setting, working with any service providers, is for testing purpose only. In a product, you must remove it and add all the service providers to be secured by the STS. You may also implement STSConfigurationProvider with your own STSConfiguration and TrustSPMetada to configure STS and register service providers to a deployed STS at run time.
To Specify an STS on the Service Side
This section discusses how to specify a Security Token Service that can be referenced by the service. On the service side, you select a security mechanism that includes STS in its title.
The STS itself is secured using a separate (non-STS) security mechanism. The security configuration of the client-side of this application is dependent upon the security mechanism selected for the STS, and not on the security mechanism selected for the application.
To specify an STS for the web service, follow these steps.
Right-click the node for the web service you want to secure.
Select Edit Web Service Attributes.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service.
Select a Security Mechanism that specifies STS from the list.
Click Configure to specify the STS information.
Type the Issuer Address and/or Issuer Metadata Address.
When the Issuer Address and the Metadata values are
the same, you only need to type the Issuer Address. For
the example application, the Issuer Address would be
http://localhost:8080/MySTSProject/MySTSService
.
Set the Algorithm Suite value so that the algorithm suite value of the service matches the algorithm suite value of the STS. Select 128 if you have not installed Unlimited Strength Encryption.
Click OK to close the dialog.
Click OK.
A new file is added to the project. To view the WSIT
configuration file, expand Web Pages | WEB-INF, then
double-click the file wsit- package-name .
service-name .xml and select the Source
page.
Right-click the project node and select Run to compile the application and deploy it onto GlassFish. A browser will open and display the WSDL file for the application.
To Specify an STS on the Client Side
Once you've determined whether it is required to configure an STS on the client side (see Summary of Client-Side Configuration Requirements), configure the client Secure Token Service options. To configure the client-side with STS, you need to configure the clients for the service and STS follow these steps.
In the Projects window, expand the node for the web services client.
Expand the Web Service References node.
Right-click the node for the web service reference for which you want to configure security options.
Select Edit Web Service Attributes.
When the Web Service References Attributes Editor is opened, select the Quality of Service tab.
Provide the service's
certificate by pointing to an alias in the client
truststore. For development purposes, click the Truststore
button,, click the Load Aliases button for the truststore
and select xws-security-server from the Alias
list.
In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the truststore entries be manually configured. To do this, follow the steps in this section.
Expand the client project node, then expand Source Packages/META-INF.
Double-click
<service-project> ..xml
to open it in the Source window. Click the Source
tab to view the code. Find the
sc:TrustStore elements. If these
elements contain parameters for
location and storepass ,
then just continue to the next section. If not, add
these attributes to this file. The following code
shows an example of how these elements could be
specified.
Example 12.6.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="xws-security-server"/>
Expand the Security Token
Service node to provide details for the STS to be used.
When the Endpoint and the Metadata values are the same,
you only need to enter the Endpoint value. For the example
application you would enter the following value in the
Endpoint field:
http://localhost:8080/MySTSProject/MySTSService
. For WS Trust Version field, select 1.3 if STS endpoint
uses ".NET 3.5 / Metro 1.3" version compatibility.
Otherwise use the default WS Trust Version.
The Endpoint field is a mandatory field. Depending on how you plan to configure the STS, you can provide either Metadata information or information regarding the WSDL Location, Service Name, Port Name and Namespace. The examples following this section describe a few potential STS configurations.
Click OK to close this dialog.
The service requires a token
to be issued from the STS, which, for the example, is
http://localhost:8080/MySTSProject/MySTSService
, with WSDL file
http://localhost:8080/MySTSProject/MySTSService?wsdl
. To do this, follow these steps:
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.
Expand the web services client project node, then Source Packages | META-INF.
Double-click
<sts-service> .xml to
open it in the Source window. Click the Source tab
to view the code. Find the sc:KeyStore
and/or sc:TrustStore elements. If these
elements contain parameters for
location and storepass ,
then just continue to the next section. If not, add
these attributes to this file. The following code
shows an example of how these elements could be
specified.
Example 12.7.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="wssip"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\truststore.jks" storepass="changeit" alias="xws-security-client"/>
If required, enter the default user name and password.
If you followed the steps in Adding Users to GlassFish , this will be User Name
wsitUser and Password changeit
.
Click OK to close this dialog.
Compile and run this application by right-clicking the web services client project and selecting Run.
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.
The section describes the following tasks:
To Secure the Example Service Application (UA)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of Username Authentication with Symmetric Key is used to secure the application. To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans .
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet)
Expand CalculatorApplication | Web Services, then right-click the node for the web service (CalculatorWS) and select Edit Web Service Attributes.
Deselect Reliable Messaging if it is selected.
In the CalculatorWSPortBinding section, select Secure Service.
From the drop-down list for Security Mechanism, select Username Authentication with Symmetric Key.
Select Use Development Defaults to set up the keystore and truststore files, and to create a user for this application, if needed.
Click OK to close the
CalculatorWSService dialog.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml .
This file contains the security elements within
wsp:Policy tags.
An example of this file can be viewed in the tutorial by clicking this link: Service-Side WSIT Configuration Files .
Right-click the CalculatorApplication node and select Run. A browser will open and display the WSDL file for the application.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (UA) .
To Secure the Example Web Service Client Application (UA)
This section demonstrates adding security to the web service client that references the web service created in the previous section. This web service is secured using the security mechanism described in Username Authentication with Symmetric Key . When this security mechanism is used with a web service, the web service client must provide a username and password in addition to specifying the certificate of the server.
To add security to the client that references this web service, complete the following steps.
Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service .
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.
Expand the node for the web service client application, CalculatorWSServletClient.
Expand the Web Service References node.
Right-click on CalculatorWSService, select Edit Web Service Attributes.
In the Security section of the Quality of Service tab, select Use Development Defaults. Click OK to close.
By default, the user name of wsitUser and the password of changeit will be entered in this section. If the example doesn't run, make sure that you have a user with this name and password set up in the file realm of the Application Server or GlassFish, as described in Adding Users to GlassFish .
If you'd like to, in the
tree, drill down from the project to Source Packages |
META-INF. Double-click on
CalculatorWSService.xml , and verify that
lines similar to the following are present:
Example 12.8.
<wsp:All>
<sc:TrustStore
wspp:visibility="private"
location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks"
storepass="changeit" peeralias="xws-security-server"/>
<sc:CallbackHandlerConfiguration wspp:visibility="private">
<sc:CallbackHandler default="wsitUser" name="usernameHandler"/>
<sc:CallbackHandler default="changeit" name="passwordHandler"/>
</sc:CallbackHandlerConfiguration>
</wsp:All>By selecting Use Development Defaults when securing the service, these values are automatically generated for you.
An example of this file can be viewed in the tutorial by clicking this link: Client-Side WSIT Configuration Files .
Right-click the CalculatorWSServletClient node and select Run. The result of the add operation will display in a browser window.
This example is similar to Example: Username Authentication with Symmetric Key (UA) except that digest passwords (along with Created and Nonce) are used in UsernameToken, and UsernameToken is not encrypted in the message.
To Secure the Service Application, all the steps remain same, except for step 6. For step 6, do the following:
Click on Configure, select Support Hash Passwords. Click OK.
Unselect Use Development Defaults, if already selected. Specify the KeyStore. Click on Validators, and specify the username validator.
The Username Validator created should extend PasswordValidationCallback.WsitDigestPasswordValidator. Here is a sample UsernameValidator for Digest passwords.
Example 12.9.
import com.sun.xml.wss.impl.callback.PasswordValidationCallback;
public class SampleWsitDigestPasswordValidator extends
PasswordValidationCallback.WsitDigestPasswordValidator {
public void setPassword(PasswordValidationCallback.Request request){
//Get this password from somewhere - for example a JDBC Realm
String passwd = "abcd!1234";
PasswordValidationCallback.DigestPasswordRequest req =
(PasswordValidationCallback.DigestPasswordRequest)request;
req.setPassword(passwd);
}
}
Use of Digest Passwords can be supported for any realm which store plain passwords (not hashed ones). Currently this is supported for JDBC realm in GlassFish. Or optionally, a user can write his own custom realm.
The steps for securing the client remain same as in Example: Username Authentication with Symmetric Key (UA).
The section describes the following tasks:
To Secure the Example Service Application (MCS)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of Mutual Certificates Security is used to secure the application. To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans .
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet)
Expand CalculatorApplication | Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Deselect Reliable Messaging if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select Mutual Certificates Security.
Select Use Development Defaults.
Click OK to close the dialog.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml .
This file contains the security elements within
wsp:Policy tags.
Right-click the CalculatorApplication node and select Run.
A browser will open and display the WSDL file for the application.
Verify that the WSDL file
contains the AsymmetricBinding element.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (MCS) .
To Secure the Example Web Service Client Application (MCS)
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.
Create the client application following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service .
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.
This section describes the following tasks:
To Secure the Example Service Application (SSL)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding transport security to both the web service and to the web service client.
For this example, the security mechanism of Transport Security (SSL) is used to secure the application. To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans :
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet)
Expand CalculatorApplication | Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Deselect Reliable Messaging if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select Transport Security (SSL).
Select Use Development Defaults.
Click OK to close the dialog.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml .
This file contains the security elements within
wsp:Policy tags.
To require the service to
use the HTTPS protocol, security requirements must be
specified in the service's application deployment
descriptor, which is web.xml for a web
service implemented as a servlet. Selecting Use
Development Defaults takes care of this task for you.
To view or change the security information, follow these steps:
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.
Click the XML tab to view the resulting deployment descriptor additions.
Right-click the CalculatorApplication node and select Run. If the server presents its certificate, s1as, accept this certificate. A browser will open and display the WSDL file for the application.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (SSL) .
To Secure the Example Web Service Client Application (SSL)
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.
Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service , with the exception that you need to specify the secure WSDL when creating the Web Service Client.
To do this, create the client application up to the step where you create the Servlet (step 5 as of this writing) by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service , with the following exception.
In the step where you are directed to cut and
paste the URL of the web service that you want the
client to consume into the WSDL URL field, type
https ://
fully-qualified-hostname:8181
/CalculatorApplication/CalculatorWSService?wsdl
(changes indicated in bold) to indicate that this
client should reference the web service using the
secure port. The first time you access this service,
accept the certificate (s1as) when you are prompted.
This is the server certificate popping up to confirm
its identity to the client.
In some cases, you might get an error dialog
telling you that the URL https://
fully-qualified-hostname
:8181/CalculatorApplication/CalculatorWSService?wsdl
couldn't be downloaded. However, this the correct URL,
and it does load when you run the service. So, when
this error occurs, repeat the steps that create the
Web Service Client using the secure WSDL. The second
time, the web service reference is created and you can
continue creating the client.
If you prefer to use localhost in place of the fully-qualified hostname (FQHN) in this example, you must follow the steps in Transport Security (SSL) Workaround .
Continue creating the client following the remainder of the instructions in Creating a Client to Consume a WSIT-Enabled Web Service .
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.
This section describes the following tasks:
To Secure the Example Service Application (SA)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of SAML Authorization over SSL is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Key (UA) , with the addition of the writing of a client-side SAML callback handler to populate the client's request with a SAML assertion.
To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans :
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet)
Expand CalculatorApplication | Web Services, right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select SAML Authorization over SSL.
Select Use Development
Defaults to have the web.xml file
modified to include a security constraint that forces
the use of SSL.
Click OK to exit the editor.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml .
This file contains the security elements within
wsp:Policy tags.
To require the service to
use the HTTPS protocol, security requirements must be
specified in the service's application deployment
descriptor, which is web.xml for a web
service implemented as a servlet. Selecting Use
Development Defaults takes care of this task for you.
To view or change the security information in the deployment descriptor, follow these steps:
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.
Click the XML tab to view the resulting deployment descriptor additions.
Right-click the
CalculatorApplication node and select Run. Accept the
s1as certificate if you are prompted to.
A browser will open and display the WSDL file for the
application.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (SA) .
To Secure the Example Web Service Client Application (SA)
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.
If you prefer to use localhost in
place of the fully-qualified hostname (FQHN) in this
example, follow the steps in Transport Security (SSL) Workaround .
Name the application CalculatorClient (since it's not a servlet.).
Instead of creating a
client servlet as is described in Creating a Client to Consume a WSIT-Enabled Web
Service , just add the web service
operation to the generated index.jsp file
to create a non-JSR-109 client. To do this, perform
these steps:
If the
index.jsp file is not open in the right
pane, expand Web Pages, then double-click
index.jsp to open it.
Drill down through the
Web Service References node until you get to the
add operation.
Drag the
add operation to the line immediately
following the following line:
Edit the values for
i and j if you'd like.
Write a
SAMLCallback handler for the client side
to populate a SAML assertion into the client's request
to the service.
To create the SAMLCallbackHandler ,
follow these steps:
Right-click the CalculatorClient node.
Select New | Java Package.
For Package Name, type
xwss.saml and click Finish.
Drill down from CalculatorClient | Source Packages | xwss.saml.
Right-click xwss.saml and select New | Other.
From the Categories list, select Java.
From the File Types list, select Empty Java File and click Next.
For Class Name, type
SamlCallbackHandler and click Finish.
The empty file appears in the IDE.
Download the example
file SamlCallbackHandler.java from the
following URL:
http://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
Open the file in a text editor.
Modify the
home variable to provide the hard-coded
path to your GlassFish installation.
For example, modify the line:
to
Copy the contents of
this file into the
SamlCallbackHandler.java window that is
displaying in the IDE.
Drill down from CalculatorClient | Web Service References.
Right-click CalculatorWSService and select Edit Web Service Attributes.
Select the Quality of Service tab of the CalculatorWSService dialog.
Unselect Use Development Defaults.
Enter the name of the
SAML Callback Handler written earlier in this section,
xwss.saml.SamlCallbackHandler , into the
SAML Callback Handler field.
Click OK to close this dialog.
To view the WSIT
Configuration options, in the tree, drill down from
the project to Source Packages | META-INF.
Double-click CalculatorWSService.xml ,
click the Source tab, and look for the lines where
xwss.saml.SamlCallbackHandler is
specified as the SAML Callback Handler class for the
client.
Compile and run this
application by right-clicking the CalculatorClient
node and selecting Run. The result of the
add operation will display in a browser
window.
This section describes the following tasks:
To Secure the Example Service Application (SV)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of SAML Sender Vouches with Certificates is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Key (UA) , with the addition of the writing of a client-side SAML callback handler to populate the client's request with a SAML assertion.
To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans :
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet)
Expand CalculatorApplication | Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select SAML Sender Vouches with Certificates.
Select Use Development Defaults. This step properly configures the keystore, truststore, and default user for this security mechanism.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml .
This file contains the security elements within
wsp:Policy tags.
Right-click the
CalculatorApplication node and select Run. Accept the
s1as certificate if you are prompted to.
A browser will open and display the WSDL file for the application.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (SV) .
To Secure the Example Web Service Client Application (SV)
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.).
Instead of creating a
client servlet as is described in Creating a Client to Consume a WSIT-Enabled Web
Service , just add the web service
operation to the generated index.jsp file
to create a non-JSR-109 client. To do this, follow
these steps:
If the
index.jsp file is not open in the right
pane, double-click it to open it.
Drill down through the
Web Service References node until you get to the
add operation.
Drag the
add operation to the line immediately
following the following line:
Edit the values for
i and j if you'd like.
Write a
SAMLCallback handler for the client side
to populate a SAML assertion into the client's request
to the service.
To create the SAMLCallbackHandler ,
follow these steps:
Right-click the CalculatorClient node.
Select New | Java Package.
For Package Name, type
xwss.saml and click Finish.
Drill down from CalculatorClient | Source Packages | xwss.saml.
Right-click xwss.saml and select New | Other.
From the Categories list, select Java.
From the File Types list, select Empty Java File and click Next.
For Class Name, type
SamlCallbackHandler and click Finish.
The empty file appears in the IDE.
Download the example
file SamlCallbackHandler.java from the
following URL:
http://xwss.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645
Open the file in a text editor.
Modify the
home variable to provide the hard-coded
path to your GlassFish installation.
For example, modify the line:
to
Copy the contents of
this file into the
SamlCallbackHandler.java window that is
displaying in the IDE.
Drill down from CalculatorClient | Web Service References.
Right-click on CalculatorWSService and select Edit Web Service Attributes.
Select the Quality of Service tab of the CalculatorWSService dialog.
In the SAML Callback
Handler field, type the name of the class written in
step 3 above,
xwss.saml.SamlCallbackHandler .
Configure the keys: Click on the keystore button, select the alias "xws-security-client", enter the password "changeit", in the password field. Submit this dialog; Click on the truststore button, select the alias "xws-security-server". Submit the dialog.
Click OK to close this dialog.
In the tree, drill down
from the project to Source Packages | META-INF.
Double-click CalculatorWSService.xml, click the Source
tab, and look for that lines where
xwss.saml.SamlCallbackHandler is
specified as the SAML Callback Handler class for the
client. In some instances, NetBeans will not correctly
specify the keystore and truststore information for
non-JSR-196 clients, and thus will require that the
keystore and truststore entries be manually
configured. To do this, follow the example in this
section.
Find the
sc:KeyStore and
sc:TrustStore elements. If these
elements contain parameters for
location and storepass in
CalculatorWSService.xml, then just continue to the
next step. If not, replace the existing keystore and
truststore attributes to include these parameters.
The following code shows an example of how these
elements should be specified.
Example 12.16.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="xws-security-server"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks" storepass="changeit" alias="xws-security-client"/>
Compile and run this application by right-clicking the CalculatorClient node and selecting Run. The result of the add operation will display in a browser window.
This section describes the following tasks:
Another STS example application can be found at the following URL: https://github.com/javaee/metro-wsit/tree/master/wsit/samples/ws-trust .
To Create and Secure the STS (STS)
To create and secure a Security Token Service for this example, follow these steps.
For development with NetBeans 6.8, there are some temporary setup changes that will need to be done--see here for more details.
Create a new project for the STS by selecting File | New Project.
Select Java Web, then Web Application, then Next.
Type
MySTSProject for the Project Name, then
Next, then the desired Server. Click
Finish.
Right-click the
MySTSProject node, select New, then
select Other.
Select Web Services from the Categories list.
Select Secure Token Service (STS) from the File Type(s) list, then click Next.
Type the name
MySTS for the Web Service Class Name.
Enter or select
org.me.my.sts in the Package field, then
click Finish. If prompted to reload the
catalog.xml file, click No.
The IDE takes a while to create the STS. When
created, it appears under the project's Web Services
node as MySTSService .
The STS wizard creates an
implementation of the provider class. To view it,
expand Source Packages, then org.me.my.sts.
Double-click MySTS.java to open it in the
right pane.
In the Projects window, expand the MySTSProject node, then expand the Web Services node. Right-click the MySTSService[IMySTSService_Port] node and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service if it's not already selected.
Verify that the Security Mechanism of Username Authentication with Symmetric Key is selected.
Select the Configure button. For Algorithm Suite, verify that Basic128 bit is selected (so that it matches the value selected for the service.) Select OK to close the configuration dialog.
If not already selected, select Act as Secure Token Service (STS).
If you'd like to use an STS other than the default, click the STS Configure button, and click the Add button to add a different service provider. Click OK to close the STS Configuration dialog.
Click Configure. In the Issuer field, enter MySTS. Click OK to close.
Click the Keystore button
to provide your keystore with the alias identifying
the service certificate and private key. To do this,
click the Load Aliases button, select
wssip , then click OK to close the
dialog.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Configuration Files |
xml-resources | web-services | MySTS | wsdl, then
double-click the file MySTSService.wsdl .
This file contains the
tc:STSConfiguration element within the
wsp:Policy elements..
Right-click the
MySTSProject tab, select Properties. Select the Run
category, and type the following in the Relative URL
field: /MySTSService?wsdl .
Run the Project (right-click the project and select Run).
The STS WSDL appears in the browser.
Check Building custom STS to build a custom STS to control the user attributes to be included in the SAML assertion.
To Secure the Example Service Application (STS)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of STS Issued Token is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Key (UA) , with the addition of creating and securing an STS.
To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans .
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet).
Expand CalculatorApplication | Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select STS Issued Token.
Click Configure. For
Issuer Address and Issuer Metadata Address, enter
http://localhost:8080/MySTSProject/MySTSService
. For Issuer Metadata, enter
http://localhost:8080/MySTSProject/MySTSService/mex
For Algorithm Suite, select Basic 128 bit. For Key Size, select 128 (the algorithm suite value of the service must match the algorithm suite value of the STS). Select OK to close the configuration dialog.
If you have configured Unlimited Strength Encryption as described in To Create a Third-Party STS , you can leave the key size at 256. Otherwise, you must set it to 128.
Select Use Development Defaults.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml
and select the Source page. This file contains the
security elements within wsp:Policy
tags.
Right-click the CalculatorApplication node and select Run. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.
To Secure the Example Web Service Client Application (STS)
This section demonstrates adding security to the CalculatorApplication's web service client. The service was secured using the security mechanism described in STS Issued Token .
To add security to the web service client, complete the following steps.
Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service .
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.
Drill down from CalculatorWSServletClient | Web Service References.
Right-click CalculatorWSService and select Edit Web Service Attributes, then select the Quality of Service tab.
Provide the client's
private key by pointing to an alias in the keystore.
To do this, click the Keystore button, click the Load
Aliases button, and select
xws-security-client from the Alias list.
Provide the service's
certificate by pointing to an alias in the client
truststore. To do this, click the Truststore button,,
click the Load Aliases button for the truststore and
select xws-security-server from the Alias
list.
In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
Expand CalculatorWSServletClient | Source Packages | META-INF.
Double-click
CalculatorWSService.xml to open it in the Source
window. Click the Source tab to view the code. Find
the sc:KeyStore and
sc:TrustStore elements. If these
elements contain parameters for
location and storepass ,
then just continue to the next section. If not, add
these attributes to this file. The following code
shows an example of how these elements should be
specified.
Example 12.17.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="xws-security-server"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks" storepass="changeit" alias="xws-security-client"/>
Expand the Security Token Service node to provide details for the STS to be used. When the Endpoint and the Metadata values are the same, you only need to enter the Endpoint value. For the Endpoint field, enter the following value: http://localhost:8080/MySTSProject/MySTSService. For WS Trust Version field, select 1.3 if STS endpoint uses ".NET 3.5 / Metro 1.3" version compatibility. Otherwise use the default WS Trust Version.
Click OK to close this dialog.
The service requires a
token to be issued from the STS at
http://localhost:8080/MySTSProject/MySTSService
, with WSDL file
http://localhost:8080/MySTSProject/MySTSService?wsdl
. To do this, follow these steps:
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.
Example 12.18.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="wssip"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks" storepass="changeit" alias="xws-security-client"/>
Enter the default user name and password.
If you followed the steps in Adding Users to GlassFish , this
will be User Name wsitUser and Password
changeit .
Click OK to close this dialog.
Compile and run this application by right-clicking the CalculatorWSServletClient project and selecting Run. The result of the add operation will display in a browser window.
Broker Trust STS example illustrates the interaction between client and server of different domains through STS's of corresponding domains. In this kind of scenarios, STS of different domains must have a trust relationship between them. Lets take client/STS2 are in domain A, and server/STS1 are in domain B. Here, STS1 is the remote STS on the server domain(B) and STS2 is the local STS on the client domain(B). There is a trust relationship between STS1 and STS2. Here are steps which client has to follow to comminicate with server.
Client wants to communicate with Server.
Server asks Client to get a token from STS1 to comminicate with it.
Now Client would like to communicate with remote STS (i.e. STS1).
STS1 asks Client to get a token from Client's local STS (i.e. STS2) to comminicate with it.
Now Client sends a request to local STS (i.e. STS2) asking for a token to communicate with STS1.
STS2 issues a token to Client, which Client uses to comminicate with STS1.
STS1 issues a token to Client, which Client uses to comminicate with Server.
Now Client comminicates with server using a token issued by STS1, which Server understands.
This section describes the following tasks:
To Create and Secure the First STS (BT)
To create and secure a Security Token Service(i.e. Remote STS) for this example, follow these steps.
Create a new project for the STS by selecting File | New Project.
Select Web, then Web Application, then Next.
Type
MySTS1Project for the Project Name, then click
Finish.
Right-click the
MySTS1Project node, select New, then select
Other.
Select Web Services from the Categories list.
Select Secure Token Service (STS) from the File Type(s) list, then click Next.
Type the name
MySTS1 for the Web Service Class Name.
Enter or select
org.me.my.sts1 in the Package field, then
click Finish. If prompted to reload the
catalog.xml file, click No.
The IDE takes a while to create the first STS.
When created, it appears under the project's Web
Services node as MySTS1Service .
The STS wizard creates an
implementation of the provider class. To view it,
expand Source Packages, then org.me.my.sts1.
Double-click MySTS1.java to open it in
the right pane.
In the Projects window, expand the MySTS1Service node, then expand the Web Services node. Right-click the MySTS1Service[IMySTS1Service_Port] node and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service if it's not already selected.
Verify that the Security Mechanism of "STS Issued Token" is selected.
Select the Configure button. For Algorithm Suite, verify that Basic128 bit is selected (so that it matches the value selected for the service.) Select OK to close the configuration dialog.
If not already selected, select Act as Secure Token Service (STS).
If you'd like to use an STS other than the default, click the STS Configure button, and click the Add button to add a different service provider. Click OK to close the STS Configuration dialog.
Click Configure. In the Issuer field, enter MySTS1. Click OK to close.
Click the Keystore button
to provide your keystore with the alias identifying
the service certificate and private key. To do this,
click the Load Aliases button, select
wssip , then click OK to close the
dialog.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Configuration Files |
xml-resources | web-services | MySTS1 | wsdl, then
double-click the file MySTS1Service.wsdl
. This file contains the
tc:STSConfiguration element within the
wsp:Policy elements..
Right-click the
MySTS1Project tab, select Properties. Select the Run
category, and type the following in the Relative URL
field: /MySTS1Service?wsdl .
Run the Project (right-click the project and select Run).
The STS WSDL appears in the browser.
To Create and Secure the Second STS (BT)
To create and secure a Security Token Service(i.e. local STS) for this example, follow these steps.
Create a new project for the 2nd STS by selecting File | New Project.
Select Web, then Web Application, then Next.
Type
MySTS2Project for the Project Name, then click
Finish.
Right-click the
MySTS2Project node, select New, then select
Other.
Select Web Services from the Categories list.
Select Secure Token Service (STS) from the File Type(s) list, then click Next.
Type the name
MySTS2 for the Web Service Class Name.
Enter or select
org.me.my.sts2 in the Package field, then
click Finish. If prompted to reload the
catalog.xml file, click No.
The IDE takes a while to create the first STS.
When created, it appears under the project's Web
Services node as MySTS2Service .
The STS wizard creates an
implementation of the provider class. To view it,
expand Source Packages, then org.me.my.sts2.
Double-click MySTS2.java to open it in
the right pane.
In the Projects window, expand the MySTS2Service node, then expand the Web Services node. Right-click the MySTS2Service[IMySTS2Service_Port] node and select Edit Web Service Attributes to configure the STS.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Select Secure Service if it's not already selected.
Verify that the Security Mechanism of Username Authentication with Symmetric Key is selected.
Select the Configure button. For Algorithm Suite, verify that Basic128 bit is selected (so that it matches the value selected for the service.) Select OK to close the configuration dialog.
If not already selected, select Act as Secure Token Service (STS).
If you'd like to use an STS other than the default, click the STS Configure button, and click the Add button to add a different service provider. Click OK to close the STS Configuration dialog.
Click Configure. In the Issuer field, enter MySTS2. Click OK to close.
Click the Keystore button
to provide your keystore with the alias identifying
the service certificate and private key. To do this,
click the Load Aliases button, select
wssip , then click OK to close the
dialog.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Configuration Files |
xml-resources | web-services | MySTS2 | wsdl, then
double-click the file MySTS2Service.wsdl
. This file contains the
tc:STSConfiguration element within the
wsp:Policy elements..
Right-click the
MySTS2Project tab, select Properties. Select the Run
category, and type the following in the Relative URL
field: /MySTS2Service?wsdl .
Run the Project (right-click the project and select Run).
The STS WSDL appears in the browser.
To Secure the Example Service Application (BT)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of STS Issued Token is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Key (UA), with the addition of creating and securing an STS.
To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans .
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet).
Expand CalculatorApplication | Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select STS Issued Token.
Click Configure. For
Issuer Address and Issuer Metadata Address, enter
http://localhost:8080/MySTS1Project/MySTS1Service
. For Issuer Metadata, enter
http://localhost:8080/MySTS1Project/MySTS1Service/mex
For Algorithm Suite, select Basic 128 bit. For Key Size, select 128 (the algorithm suite value of the service must match the algorithm suite value of the STS). Select OK to close the configuration dialog.
If you have configured Unlimited Strength Encryption as described in To Create a Third-Party STS , you can leave the key size at 256. Otherwise, you must set it to 128.
Select Use Development Defaults.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml
and select the Source page. This file contains the
security elements within wsp:Policy
tags.
Right-click the
CalculatorApplication node and select Properties.
Select the Run category, and type the following in the
Relative URL field:
/CalculatorWSService?wsdl .
Right-click the CalculatorApplication node and select Run. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.
To Secure the Example Web Service Client Application (BT)
This section demonstrates adding security to the CalculatorApplication's web service client. The service was secured using the security mechanism described in STS Issued Token .
To add security to the web service client, complete the following steps.
Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service .
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.
Drill down from CalculatorWSServletClient | Web Service References.
Right-click CalculatorWSService and select Edit Web Service Attributes, then select the Quality of Service tab.
Provide the client's
private key by pointing to an alias in the keystore.
To do this, click the Keystore button, click the Load
Aliases button, and select
xws-security-client from the Alias list.
Provide the service's
certificate by pointing to an alias in the client
truststore. To do this, click the Truststore button,,
click the Load Aliases button for the truststore and
select xws-security-server from the Alias
list.
In some instances, NetBeans will not detect that this client is a JSR-196 client, and thus will require that the keystore and truststore entries be manually configured. To do this, follow the steps in this section.
Expand CalculatorWSServletClient | Source Packages | META-INF.
Double-click
CalculatorWSService.xml to open it in the Source
window. Click the Source tab to view the code. Find
the sc:KeyStore and
sc:TrustStore elements. If these
elements contain parameters for
location and storepass ,
then just continue to the next section. If not, add
these attributes to this file. The following code
shows an example of how these elements should be
specified.
Example 12.19.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="xws-security-server"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks" storepass="changeit" alias="xws-security-client"/>
Click OK to close this dialog.
The service requires a
token to be issued from the first STS (i.e Remote STS)
at
http://localhost:8080/MySTS1Project/MySTS1Service
, with WSDL file
http://localhost:8080/MySTS1Project/MySTS1Service?wsdl.
To do this, follow these steps:
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.
Example 12.20.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="wssip"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks" storepass="changeit" alias="xws-security-client"/>
Expand the Security Token Service node to provide details for the second STS(i.e. local STS) to be used. When the Endpoint and the Metadata values are the same, you only need to enter the Endpoint value. For the Endpoint field, enter the following value: http://localhost:8080/MySTS2Project/MySTS2Service. For WS Trust Version field, select 1.3 if STS endpoint uses ".NET 3.5 / Metro 1.3" version compatibility. Otherwise use the default WS Trust Version.
Click OK to close this dialog.
The First STS(i.e. Remote
STS) requires a token to be issued from the second
STS(i.e. local STS) at
http://localhost:8080/MySTS2Project/MySTS2Service
, with WSDL file
http://localhost:8080/MySTS2Project/MySTS2Service?wsdl
. To do this, follow these steps:
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.
Example 12.21.
<sc:TrustStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\cacerts.jks" storepass="changeit" peeralias="wssip"/> <sc:KeyStore wspp:visibility="private" location="<GF_HOME>\glassfish\domains\domain1\config\keystore.jks" storepass="changeit" alias="xws-security-client"/>
Enter the default user name and password.
If you followed the steps in Adding Users to GlassFish , this
will be User Name wsitUser and Password
changeit .
Click OK to close this dialog.
Compile and run this application by right-clicking the CalculatorWSServletClient project and selecting Run. The result of the add operation will display in a browser window.
This example illustrates, how SecureConversation Token is used to interact with STS. To have a basic idea of SecureConversation, find this article : Secure Conversations for Web Services With Metro
This section describes the following tasks:
To Create and Secure the STS with SecureConversationToken (STS+SC).
Same as provided in To Create and Secure the STS (STS)
To Secure the Example Service Application (STS+SC)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, the security mechanism of STS Issued Token is used to secure the application. The steps are similar to the ones described in Example: Username Authentication with Symmetric Key (UA) , with the addition of creating and securing an STS.
To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans .
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet).
Expand CalculatorApplication | Web Services, then right-click the node for the web service, CalculatorWS, and select Edit Web Service Attributes.
Select the "Version Compatibility" to ".NET 3.5 / Metro 1.3" ( e.g. see Web Service Attributes Editor Page ) . It will use WS-SX version of all WS-* specifications.
Deselect the Reliable Messaging option if it is selected.
Select Secure Service.
From the drop-down list for Security Mechanism, select STS Issued Token.
Click Configure. For
Issuer Address and Issuer Metadata Address, enter
http://localhost:8080/MySTSProject/MySTSService
. For Issuer Metadata, enter
http://localhost:8080/MySTSProject/MySTSService/mex
Select the Configure button and do the following :
For Algorithm Suite, verify that Basic128 bit is selected (so that it matches the value selected for the service.)
Check the Establish Secure Session (Secure Conversation) check box to enable the secure conversaion feature
If you have configured Unlimited Strength Encryption as described in To Create a Third-Party STS , you can leave the key size at 256. Otherwise, you must set it to 128.
Select OK to close the configuration dialog.
Select Use Development Defaults.
Click OK.
A new file is added to the project. To view the
WSIT configuration file, expand Web Pages | WEB-INF,
then double-click the file
wsit-org.me.calculator.CalculatorWS.xml
and select the Source page. This file contains the
security elements within wsp:Policy
tags.
Right-click the CalculatorApplication node and select Run. This step compiles the application and deploys it onto GlassFish. A browser will open and display the WSDL file for the application.
To Secure the Example Web Service Client Application (STS+SC).
Same as provided in To Secure the Example Web Service Client Application (STS)
This section contains the steps for running a Kerberos Token Profile-based WS Security scenario. Kerberos support was added to Metro in 1.1 release. The Netbeans support for configuring a Kerberos Token based secure web service is available from Metro 1.3 and Netbeans 6.5.
For an article discussing using Kerberos with WSIT, go to Building Kerberos-Based Secure Services Using Metro. This article has a sample application, but does not use Netbeans IDE.
The section describes the following tasks:
To Set Up Your System for Kerberos Profile.
If your system is not already set up to use Kerberos, refer to the steps mentioned in Configuring Kerberos for GlassFish and Tomcat.
To Secure the Example Service Application (Kerb)
The following example application starts with the example provided in Developing with NetBeans and demonstrates adding security to both the web service and to the web service client.
For this example, a Kerberos token is used to secure the application. To add security to the service part of the example, follow these steps.
Create the CalculatorApplication example by following the steps described in the following sections of Developing with NetBeans.
Skip the section on adding Reliable Messaging.
Deploying and Testing a Web Service (first two steps only, do not run the project yet)
Expand CalculatorApplication | Web Services, then right-click the node for the web service (CalculatorWS) and select Edit Web Service Attributes.
Deselect Reliable Messaging if it is selected.
In the CalculatorWSPortBinding section, select Secure Service.
From the drop-down list for Security Mechanism, select Symmetric Binding with Kerberos Tokens.
Select Kerberos button, and specify the Login Module to be used for the service. For details on Login Module to specify refer Configuring Kerberos for GlassFish and Tomcat.
Click OK to close the
CalculatorWSService dialog.
Expand Web Pages | WEB-INF, then double-click
the file
wsit-org.me.calculator.CalculatorWS.xml
to open it in the edit window.The Binding level policy
looks like: (This section of code has been formatted
to fit the page)
Example 12.22.
<wsp:Policy wsu:Id="IFinancialService_policy">
<wsp:ExactlyOne>
<wsp:All>
<wsaws:UsingAddressing
xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
<sp:SymmetricBinding>
<wsp:Policy>
<sp:ProtectionToken>
<wsp:Policy>
<sp:KerberosToken
sp:IncludeToken="http://docs.oasis-open.org/
ws-sx/ws-securitypolicy/200702/IncludeToken/Once">
<wsp:Policy>
<sp:WssGssKerberosV5ApReqToken11/>
</wsp:Policy>
</sp:KerberosToken>
</wsp:Policy>
</sp:ProtectionToken>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:OnlySignEntireHeadersAndBody/>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128/>
</wsp:Policy>
</sp:AlgorithmSuite>
</wsp:Policy>
</sp:SymmetricBinding>
<sp:Wss11>
<wsp:Policy>
<sp:MustSupportRefKeyIdentifier/>
<sp:MustSupportRefIssuerSerial/>
<sp:MustSupportRefThumbprint/>
<sp:MustSupportRefEncryptedKey/>
</wsp:Policy>
</sp:Wss11>
<sc:KerberosConfig xmlns:
sc="http://schemas.sun.com/2006/03/wss/server"
loginModule="KerberosServer"/>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>Right-click the CalculatorApplication node and select Run. A browser will open and display the WSDL file for the application.
If the application doesn't build, expand
CalculatorApplication | Web Pages | WEB-INF, and
double-click web.xml to open it in the
right pane. Select the Security tab, and remove any
existing security constraints. Then run the project
again.
Follow the steps to secure the client application as described in To Secure the Example Web Service Client Application (Kerb).
To Secure the Example Web Service Client Application (Kerb)
This section demonstrates adding security to the web service client that references the web service created in the previous section. . This section also assumes that Kerberos environment has already been setup on the system. Refer to Configuring Kerberos for GlassFish and Tomcat for more details.
To add security to the client that references this web service, complete the following steps.
Create the client application by following the steps described in Creating a Client to Consume a WSIT-Enabled Web Service.
Whenever you make changes on the service, refresh the client so that the client will pick up the change. To refresh the client, right-click the node for the Web Service Reference for the client, and select Refresh Client.
Expand the node for the web service client application, CalculatorWSServletClient.
Expand the Web Service References node.
Right-click on CalculatorWSService, select Edit Web Service Attributes.
Expand the Web Service References node.
In the Security section of the Quality of Service tab, select Kerberos. Specify Login Module, Service Principal and check the box if credentials should be delegated.
Specify the Login Module to the one you created in login.conf file for the client in the section Configuring Kerberos for GlassFish and Tomcat, and the service principal for which the ticket needs to be obtained.
Kerberos support in Metro security supports credential delegation from client to service, such that the server can initiate other security contexts on behalf of the client. This feature is useful for single sign-on in a multi-tier environment. Select the checkbox for credential delegation.
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.
Right-click the CalculatorWSServletClient node and select Run. The result of the add operation will display in a browser window.
If your client is a Java SE client, you need to set the following system properties while running your client code:
Example 12.23.
-Djava.security.policy=${glassfish.home}/domains/domain1/config/server.policy
-Djava.security.auth.login.config=${glassfish.home}/domains/domain1/config/login.conf
If it is WebApp deployed on
glassfish, nothing else needs to be done.