test

Sun GlassFish Enterprise Server v3 Administration Guide

Chapter 13 Administering Message Security

This chapter provides information and procedures on configuring the message layer security for web services in the Sun GlassFishTM Enterprise Server environment.

Note –

Message security (JSR 196) is supported only in the Full Platform Profile of Enterprise Server, not in the Web Profile.

The following topics are addressed here:

Some of the material in this chapter assumes a basic understanding of security and web services concepts. For more information about security, see About System Security in Enterprise Server.

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About Message Security in Enterprise Server

Message security enables a server to perform end-to-end authentication of web service invocations and responses at the message layer. Security information is inserted into messages so that it travels through the networking layers and arrives with the intact message at the message destination(s). Message security differs from transport layer security in that message security can be used to decouple message protection from message transport so that messages remain protected after transmission.

Web services deployed on Enterprise Server are secured by binding SOAP layer message security providers and message protection policies to the containers in which the applications are deployed, or to web service endpoints served by the applications. SOAP layer message security functionality is configured in the client-side containers of Enterprise Server by binding SOAP layer message security providers and message protection policies to the client containers or to the portable service references declared by client applications.

Message-level security can be configured for the entire Enterprise Server or for specific applications or methods. Configuring message security at the application level is discussed in the Sun GlassFish Enterprise Server v3 Application Development Guide.

The following topics are addressed here:

Security Tokens and Security Mechanisms

WS-Security is a specification that provides a communications protocol for applying security to web services. The security mechanisms implement the specification. Web Services Interoperability Technologies (WSIT) implements WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through intermediary nodes before reaching their destination endpoint. WS-Security as provided by WSIT is in addition to existing transport-level security, which can still be used. The Simple Object Access Protocol (SOAP) layer message security providers installed with Enterprise Server can be used to employ username/password and X.509 certificate security tokens to authenticate and encrypt SOAP web services messages.

Authentication Providers

The authentication layer is the message layer on which authentication processing must be performed. Enterprise Server enforces web services message security at the SOAP layer. The types of authentication that are supported include the following:

Enterprise Server invokes authentication providers to process SOAP message layer security. The message security providers provide information such as the type of authentication that is required for the request and response messages. The following message security providers are included with Enterprise Server:

The default server provider is used to identify the server—side provider to be invoked for any application for which a specific server provider has not been bound.

Message Protection Policies

A request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature. The response policy defines the authentication policy requirements associated with response processing performed by the authentication provider.

Message protection policies are defined for request message processing and response message processing. The policies are expressed in terms of requirements for source and/or recipient authentication. The providers apply specific message security mechanisms to cause the message protection policies to be realized in the context of SOAP web services messages.

Request and response message protection policies are defined when a security provider is configured into a container. Application-specific message protection policies (at the granularity of the web service port or operation) can also be configured within the Sun-specific deployment descriptors of the application or application client. In any situation where message protection policies are defined, the request and response message protection policies of the client must be equivalent t) the request and response message protection policies of the server. For more information about defining application-specific message protection policies, see Chapter 5, Securing Applications, in Sun GlassFish Enterprise Server v3 Application Development Guide

Application-Specific Web Services Security

Application-specific web services security functionality is configured (at application assembly) by defining the message-security-binding elements in the Sun-specific deployment descriptors of the application. These message-security-binding elements are used to associate a specific security provider or message protection policy with a web service endpoint or service reference, and might be qualified so that they apply to a specific port or method of the corresponding endpoint or referenced service.

For information about defining application-specific message protection policies, see Chapter 5, Securing Applications, in Sun GlassFish Enterprise Server v3 Application Development Guide.

Message Security Administration

When Enterprise Server is installed, SOAP layer message security providers are configured in the client and server-side containers of Enterprise Server, where they are available for binding for use by the containers, or by individual applications or clients deployed in the containers. During installation, the default providers are configured with a simple message protection policy that, if bound to a container, or to an application or client in a container, would cause the source of the content in all request and response messages to be authenticated by XML digital signature.

Enterprise Server administrative interfaces can be used as follows:

Analogous administrative operations can be performed on the SOAP message layer security configuration of the application client container. If you want web services security to protect all web services applications deployed on Enterprise Server. See Enabling Message Security for Application Clients.

By default, message layer security is disabled on Enterprise Server. To configure message layer security for the Enterprise Server see Enabling Default Message Security Providers for Web Services.

In most cases, you must restart Enterprise Server after performing administrative tasks. This is especially true if you want the effects of the administrative change to be applied to applications that were already deployed on Enterprise Server at the time the operation was performed.

Message Security Tasks

The general implementation tasks for message security include some or all of the following:

  1. If you are using a version of the Java SDK prior to version 1.5.0, and using encryption technology, configuring a JCE provider

  2. If you are using a username token, verifying that a user database is configured for an appropriate realm

    When using a username/password token, an appropriate realm must be configured and a user database must be configured for the realm.

  3. Managing certificates and private keys, if necessary

  4. Enabling the Enterprise Server default providers

  5. Configuring new message security providers

Message Security Roles

In Enterprise Server, the administrator and the application deployer are expected to take primary responsibility for configuring message security. In some situations, the application developer might also contribute.

System Administrator

The system administrator is responsible for the following message security tasks:

Application Deployer

The application deployer is responsible for the following message security tasks:

Application Developer/Assembler

The application developer/assembler is responsible for the following message security tasks:

Sample Application for Web Services

Enterprise Server includes a sample application named xms. The xms application features a simple web service that is implemented by both a Java EE EJB endpoint and a Java servlet endpoint. Both endpoints share the same service endpoint interface. The service endpoint interface defines a single operation, sayHello, which takes a string argument, and returns a String composed by pre-pending Hello to the invocation argument.

The xms sample application is provided to demonstrate the use of Enterprise Server WS-Security functionality to secure an existing web services application. The instructions which accompany the sample describe how to enable the WS-Security functionality of Enterprise Server such that it is used to secure the xms application. The sample also demonstrates the binding of WS-Security functionality directly to the application as described in Application-Specific Web Services Security application.

For information about compiling, packaging, and running the xms sample application, Chapter 5, Securing Applications, in Sun GlassFish Enterprise Server v3 Application Development Guide.

The xms sample application is installed in the following directory: as-install/samples/webservices/security/ejb/apps/xms/

Enabling Default Message Security Providers for Web Services

By default, message security is disabled on Enterprise Server. Default message security providers have been created, but are not active until you enable them. After the providers have been enabled, message security is enabled.

The following topics are addressed here:

ProcedureTo Enable a Default Server Provider

To enable message security for web services endpoints deployed in Enterprise Server, you must specify a security provider to be used by default on the server side. If you enable a default provider for message security, you also need to enable providers to be used by clients of the web services deployed in Enterprise Server.

  1. Specify the default server provider by using the set(1) subcommand.

    Use the following syntax:


    asadmin  set --port admin-port 
server-config.security-service.message-security-config.SOAP.
default_provider=ServerProvider

  2. To apply your changes to applications that are already running, restart Enterprise Server.

    See To Restart a Domain.

ProcedureTo Enable a Default Client Provider

To enable message security for web service invocations originating from deployed endpoints, you must specify a default client provider. If you enabled a default client provider for Enterprise Server, you must ensure that any services invoked from endpoints deployed in Enterprise Server are compatibly configured for message layer security.

  1. Specify the default client provider by using the set(1) subcommand.

    Use the following syntax:


    asadmin  set --port admin-port 
server-config.security-service.message-security-config.SOAP.
default_client_provider=ClientProvider

  2. To apply your changes to applications that are already running, restart Enterprise Server.

    See To Restart a Domain.

Configuring Message Protection Policies

Message protection policies are defined for request message processing and response message processing. The policies are expressed in terms of requirements for source and/or recipient authentication. The providers apply specific message security mechanisms to cause the message protection policies to be realized in the context of SOAP web services messages.

The following topics are addressed here:

Message Protection Policy Mapping

The following table shows message protection policy configurations and the resulting message security operations performed by the WS-Security SOAP message security providers for that configuration.

Table 13–1 Message Protection Policy Mapping to WS-Security SOAP Operations

Message Protection Policy 

Resulting WS-Security SOAP message protection operations 

auth-source="sender"

The message contains a wsse:Security header that contains a wsse:UsernameToken (with password).

auth-source="content"

The content of the SOAP message Body is signed. The message contains a wsse:Security header that contains the message Body signature represented as a ds:Signature.

auth-source="sender"

auth-recipient="before-content"

OR 

auth-recipient="after-content"

The content of the SOAP message Body is encrypted and replaced with the resulting xend:EncryptedData. The message contains a wsse:Security header that contains a wsse:UsernameToken (with password) and an xenc:EncryptedKey. The xenc:EncryptedKey contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.

auth-source="content"

auth-recipient="before-content"

The content of the SOAP message Body is encrypted and replaced with the resulting xend:EncryptedData. The xenc:EncryptedData is signed. The message contains a wsse:Security header that contains an xenc:EncryptedKey and a ds:Signature. The xenc:EncryptedKey contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.

auth-source="content"

auth-recipient="after-content"

The content of the SOAP message Body is signed, then encrypted, and then replaced with the resulting xend:EncryptedData. The message contains a wsse:Security header that contains an xenc:EncryptedKey and a ds:Signature. The xenc:EncryptedKey contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.

auth-recipient="before-content"

OR 

auth-recipient="after-content"

The content of the SOAP message Body is encrypted and replaced with the resulting xend:EncryptedData. The message contains a wsse:Security header that contains an xenc:EncryptedKey. The xenc:EncryptedKey contains the key used to encrypt the SOAP message body. The key is encrypted in the public key of the recipient.

No policy specified. 

No security operations are performed by the modules. 

ProcedureTo Configure the Message Protection Policies for a Provider

Typically, you would not reconfigure a provider. However, if needed for your situation, you can modify a provider's message protection policies by changing provider type, implementation class, and provider-specific configuration properties. To understand the results of different combinations, see Table 13–1.

Use the set(1) subcommand to set the response policy, then replace the word request in the following commands with the word response.

  1. Add a request policy to the client and set the authentication source by using the set(1) subcommand.

    For example:


    asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ClientProvider.request-policy.auth_source=[sender | content]

  2. Add a request policy to the server and set the authentication source by using the set subcommand.

    For example:


    asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ServerProvider.request-policy.auth_source=[sender | content]

  3. Add a request policy to the client and set the authentication recipient by using the set subcommand:

    For example:


    asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ClientProvider.request-policy.auth_recipient=[before-content | after-content]

  4. Add a request policy to the server and set the authentication recipient by using the set subcommand:

    For example:


    asadmin> set server-config.security-service.message-security-config.SOAP.
provider-config.ServerProvider.request-policy.auth_recipient=[before-content | after-content]

Setting the Request and Response Policy for the Application Client Configuration

The request and response policies define the authentication policy requirements associated with request and response processing performed by the authentication provider. Policies are expressed in message sender order such that a requirement that encryption occur after content would mean that the message receiver would expect to decrypt the message before validating the signature.

To achieve message security, the request and response policies must be enabled on both the server and client. When configuring the policies on the client and server, make sure that the client policy matches the server policy for request/response protection at application-level message binding.

To set the request policy for the application client configuration, modify the Enterprise Server–specific configuration for the application client container as described in Enabling Message Security for Application Clients.

Example 13–1 Message Security Policy Setting for Application Clients

In the application client configuration file, the request-policy and response-policy elements are used to set the request policy, as shown in the following code snippet. (Additional code in the snippet is provided as illustration and might differ slightly in your installation. Do not change the additional code.)


<client-container>
  <target-server name="your-host" address="your-host"
      port="your-port"/>
  <log-service file="" level="WARNING"/>
  <message-security-config auth-layer="SOAP"
      default-client-provider="ClientProvider">
    <provider-config
        class-name="com.sun.enterprise.security.jauth.ClientAuthModule"
        provider-id="ClientProvider" provider-type="client">
      <request-policy auth-source="sender | content"
        auth-recipient="after-content | before-content"/>
      <response-policy auth-source="sender | content"
        auth-recipient="after-content | before-content"/>
       <property name="security.config"
           value="as-install/lib/appclient/wss-client-config.xml"/>
    </provider-config>
  </message-security-config>
</client-container>

Valid values for auth-source include sender and content. Valid values for auth-recipient include before-content and after-content. A table describing the results of various combinations of these values can be found in Configuring Message Protection Policies.

To not specify a request or response policy, leave the element blank, for example:


<response-policy/>

Administering Non-default Message Security Providers

The following topics are addressed here:

ProcedureTo Create a Message Security Provider

Use the create–message–security–provider subcommand in remote mode to create a new message provider for the security service. If the message layer does not exist, the message layer is created, and the provider is created under it.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create the message security provider by using the create-message-security-provider(1) subcommand.

    Information about properties for this subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 13–2 Creating a Message Security Provider

This example creates the new message security provider mySecurityProvider.


asadmin> create-message-security-provider 
--classname com.sun.enterprise.security.jauth.ClientAuthModule
--providertype client mySecurityProvider
Command create-message-security-provider executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create–message–security–provider at the command line.

ProcedureTo List Message Security Providers

Use the list–message–security–providers subcommand in remote mode to list the message providers for the security layer.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the message security providers by using the list-message-security-providers(1) subcommand.

Example 13–3 Listing Message Security Providers

This example lists the message security providers for a message layer.


asadmin> list-message-security-providers --layer SOAP
XWS_ClientProvider 
ClientProvider
XWS_ServerProvider
ServerProvider
Command list-message-security-providers executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list–message–security–providers at the command line.

ProcedureTo Update a Message Security Provider

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the message security providers by using the list-message-security-providers(1) subcommand.

  3. Modify the values for the specified message security provider by using the set(1) subcommand.

    The message security provider is identified by its dotted name.

ProcedureTo Delete a Message Security Provider

Use the delete-message-security-provider subcommand in remote mode to remove

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the message security providers by using the list-message-security-providers(1) subcommand.

  3. Delete the message security provider by using the delete-message-security-provider(1) subcommand.

Example 13–4 Deleting a Message Security Provider

This example deletes the myServerityProvider message security provider.


asadmin> delete-message-security-provider --layer SOAP myServerityProvider
Command delete-message-security-provider executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete–message–security–provider at the command line.

Enabling Message Security for Application Clients

The message protection policies of client providers must be configured such that they are equivalent to the message protection policies of the server-side providers they will be interacting with. This is already the situation for the providers configured (but not enabled) when Enterprise Server is installed.

To enable message security for client applications, modify the Enterprise Server specific configuration for the application client container. The process is analogous to the process in Configuring Message Protection Policies.

Additional Information About Message Security

Additional information associated with message security: