Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide

Admin Console Tasks for Message Security

Most of the steps for setting up the Application Server for using message security can be accomplished using the Admin Console, the asadmin command-line tool, or by manually editing system files. In general, editing system files is discouraged due to the possibility of making unintended changes that prevent the Application Server from running properly, therefore, where possible, steps for configuring the Application Server using the Admin Console are shown first, with the asadmin tool command shown after. Steps for manually editing system files are shown only when there is no Admin Console or asadmin equivalent.

Support for message layer security is integrated into the Application Server and its client containers in the form of (pluggable) authentication modules. By default, message layer security is disabled on the Application Server. The following sections provide the details for enabling, creating, editing, and deleting message security configurations and providers.

ProcedureTo enable providers for message security

To enable message security for web services endpoints deployed in the Application Server, you must specify a 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 the Application Server. Information for enabling the providers used by clients is discussed in To enable message security for application clients.

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 the Application Server, you must ensure that any services invoked from endpoints deployed in the Application Server are compatibly configured for message layer security.

  1. In the Admin Console tree component, expand the Configurations node.

  2. Select the instance to configure:

    • To configure a particular instance, select the instance’s config node. For example, the default instance, server, select the server-config node.

    • To configure the default settings for all instances, select the default-config node.

  3. Expand the Security node.

  4. Expand the Message Security node.

  5. Select the SOAP node.

  6. Select the Message Security tab.

  7. On the Edit Message Security Configuration page, specify a provider to be used on the server side and a provider to be used on the client side for all applications for which a specific provider has not been bound.

    This is accomplished by modifying the following optional properties:

    • Default Provider – The identity of the server provider to be invoked for any application for which a specific server provider has not been bound.

      By default, no provider configuration is selected for the Application Server. To identify a server-side provider, select ServerProvider. Selecting the null option means that no message security provider will be invoked (by default) on the server side.

      You would generally select ServerProvider for this field.

    • Default Client Provider – The identity of the client provider to be invoked for any application for which a specific client provider has not been bound.

      By default, no provider configuration is selected for the Application Server. To identify a client-side provider, select ClientProvider. Selecting the null option means that no message security provider will be invoked (by default) on the client side.

      You would generally select null for this field. You would select ClientProvider if you wanted to enable a default provider and message protection policy to apply to the web services invocations originating from web services endpoints deployed on the Application Server.

  8. Click Save.

  9. If you enabled a client or server provider and you want to modify the message protection policies of the enabled providers, refer to To configure a message security provider for information on modifying the message security providers enabled in this step.

Equivalent asadmin commands

ProcedureTo configure a message security provider

Typically, a provider would be reconfigured to modify its message protection policies, although the provider type, implementation class, and provider-specific configuration properties may also be modified.

  1. In the Admin Console tree component, expand the Configurations node.

  2. Select the instance to configure:

    • To configure a particular instance, select the instance’s config node. For example, the default instance, server, select the server-config node.

    • To configure the default settings for all instances, select the default-config node.

  3. Expand the Security node.

  4. Expand the Message Security node.

  5. Select the SOAP node.

  6. Select the Providers tab.

  7. Select the message security provider to edit.

    ClientProvider and ServerProvider ship with the Application Server.

  8. In the Provider Config section of the Edit Provider Config page, the following properties are available for modification:

    • Provider Type – Select client, server, or client-server to establish whether the provider is to be used as a client authentication provider, a server authentication provider, or both (a client-server provider).

    • Class Name - Enter the Java implementation class of the provider. Client authentication providers must implement the com.sun.enterprise.security.jauth.ClientAuthModule interface. Server-side providers must implement the com.sun.enterprise.security.jauth.ServerAuthModule interface. A provider may implement both interfaces, but it must implement the interface corresponding to its provider type.

  9. In the Request Policy section of the Create a Provider Configuration page, enter the following optional values, if needed.

    These properties are optional, but if not specified, no authentication is applied to request messages.

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

    • Authentication Source– Select sender, content, or null (the blank option) to define a requirement for message-layer sender authentication (for example, username password), content authentication (for example, digital signature), or no authentication be applied to request messages. When null is specified, source authentication of the request is not required.

    • Authentication Recipient– Select beforeContent or afterContent to define a requirement for message-layer authentication of the receiver of the request message to its sender (by XML encryption). When the value is not specified it defaults to afterContent.

    For a description of the actions performed by the SOAP message security providers as a result of the following message protection policies see Actions of Request and Response Policy Configurations.

  10. In the Response Policy section of the Create a Provider Configuration page, enter the following optional properties, if needed.

    These properties are optional, but if not specified, no authentication is applied to response messages.

    The response policy defines the authentication policy requirements associated with 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.

    • Authentication Source – Select sender, content, or null (the blank option) to define a requirement for message-layer sender authentication (for example, username password) or content authentication (for example, digital signature) to be applied to response messages. When null is specified, source authentication of the response is not required.

    • Authentication Recipient – Select beforeContent or afterContent to define a requirement for message-layer authentication of the receiver of the response message to its sender (by XML encryption). When the value is not specified it defaults to afterContent.

    For a description of the actions performed by the SOAP message security providers as a result of the following message protection policies see Actions of Request and Response Policy Configurations.

  11. Add additional properties by clicking the Add Property button.

    The provider that is shipped with the Application Server supports the property listed below. If other providers are used, refer to their documentation for more information on properties and valid values.

    • server.config – The directory and file name of an XML file that contains the server configuration information. For example, domain-dir/config/wss-server-config.xml.

  12. Click Save.

Equivalent asadmin commands

To set the response policy, replace the word request in the following commands with response.

ProcedureCreating a Message Security Provider

To configure an existing provider, follow the steps in To configure a message security provider.

  1. In the Admin Console tree component, expand the Configurations node.

  2. Select the instance to configure:

    • To configure a particular instance, select the instance’s config node. For example, the default instance, server, select the server-config node.

    • To configure the default settings for all instances, select the default-config node.

  3. Expand the Security node.

  4. Expand the Message Security node.

  5. Select the SOAP node.

  6. Select the Providers tab.

  7. On the Provider Configuration page, click New.

  8. In the Provider Config section of the Create a Provider Configuration page, enter the following:

    • Default Provider – Check the box beside this field to make the new message security provider the provider to be invoked for any application for which a specific provider has not been bound. Whether the provider becomes the default client provider, the default server provider, or both will be based on the value selected for Provider Type.

    • Provider Type – Select client, server, or client-server to establish whether the provider is to be used as a client authentication provider, a server authentication provider, or both (a client-server provider).

    • Provider ID - Enter an identifier for this provider configuration. This name will appear in the Current Provider Configurations list.

    • Class Name - Enter the Java implementation class of the provider. Client authentication providers must implement the com.sun.enterprise.security.jauth.ClientAuthModule interface. Server-side providers must implement the com.sun.enterprise.security.jauth.ServerAuthModule interface. A provider may implement both interfaces, but it must implement the interface corresponding to its provider type.

  9. In the Request Policy section of the Create a Provider Configuration page, enter the following optional values, if needed.

    These properties are optional, but if not specified, no authentication is applied to request messages.

    • Authentication Source – Select sender, content, or null (the blank option) to define a requirement for message-layer sender authentication (for example, username password), content authentication (for example, digital signature), or no authentication be applied to request messages. When null is specified, source authentication of the request is not required.

    • Authentication Recipient – Select beforeContent or afterContent to define a requirement for message-layer authentication of the receiver of the request message to its sender (by XML encryption). When the value is not specified it defaults to afterContent.

    For a description of the actions performed by the SOAP message security providers as a result of the following message protection policies see Actions of Request and Response Policy Configurations.

  10. In the Response Policy section of the Create a Provider Configuration page, enter the following optional properties, if needed.

    These properties are optional, but if not specified, no authentication is applied to response messages.

    • Authentication Source – Select sender, content, or null (the blank option) to define a requirement for message-layer sender authentication (for example, username password) or content authentication (for example, digital signature) to be applied to response messages. When null is specified, source authentication of the response is not required.

    • Authentication Recipient – Select beforeContent or afterContent to define a requirement for message-layer authentication of the receiver of the response message to its sender (by XML encryption). When the value is not specified it defaults to afterContent.

    For a description of the actions performed by the SOAP message security providers as a result of the following message protection policies see Actions of Request and Response Policy Configurations.

  11. Add additional properties by clicking the Add Property button.

    The provider that is shipped with the Application Server supports the property listed below. If other providers are used, refer to their documentation for more information on properties and valid values.

    • server.config – The directory and file name of an XML file that contains the server configuration information. For example, domain-dir/config/wss-server-config.xml.

  12. Click OK to save this configuration, or click Cancel to quit without saving.

Equivalent asadmin command

create-message-security-provider

ProcedureTo delete a message security configuration

  1. In the Admin Console tree component, expand the Configurations node.

  2. Select the instance to configure:

    • To configure a particular instance, select the instance’s config node. For example, the default instance, server, select the server-config node.

    • To configure the default settings for all instances, select the default-config node.

  3. Expand the Security node.

  4. Select the Message Security node.

  5. Click in the checkbox to the left of the Message Security Configuration to be deleted.

  6. Click Delete.

ProcedureTo delete a message security provider

  1. In the Admin Console tree component, expand the Configurations node.

  2. Select the instance to configure:

    • To configure a particular instance, select the instance’s config node. For example, the default instance, server, select the server-config node.

    • To configure the default settings for all instances, select the default-config node.

  3. Expand the Security node.

  4. Expand the Message Security node.

  5. Select the SOAP node.

  6. Select the Providers page.

  7. Click in the checkbox to the left of the Provider Configuration to be deleted.

  8. Click Delete.

Equivalent asadmin command

delete-message-security-provider

ProcedureTo enable 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 case for the providers configured (but not enabled) when the Application Server is installed.

To enable message security for client applications, modify the Application Server specific configuration for the application client container.

  1. Stop any client applications that depend on the client container descriptor.

  2. In a text editor, open the Sun application client container descriptor, located in domain-dir/config/sun-acc.xml.

  3. Add the default-client-provider element to the file to enable the default client provider in the application client.

    The other code is provided to show where the code to enable message security for client applications should be located. The other code may differ slightly in your installation. Do not change it.


    <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"/>
          <response-policy/>
            <property name="security.config"
              value="C:/Sun/AppServer/lib/appclient/wss-client-config.xml"/>
        </provider-config>
      </message-security-config>
    </client-container>

    The message security provider configured in the client container will also require access to private keys and trusted certificates. This is accomplished by defining appropriate values for the following system properties in the application client startup script.

    -Djavax.net.ssl.keyStore
    -Djavax.net.ssl.trustStore

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 Application Server specific configuration for the application client container as described in To enable message security for application clients. In the application client configuration file, add the request-policy and response-policy elements as shown to set the request policy.

The other code is provided for reference. The other code may differ slightly in your installation. Do not change it.


<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="install-dir/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 Actions of Request and Response Policy Configurations.

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


<response-policy/>

Further Information