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

- Previous: About Message Security
- Next: Chapter 11 Transactions

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

- To enable providers for message security

- To configure a message security provider

- Creating a Message Security Provider

- To delete a message security configuration

- To delete a message security provider

- To enable message security for application clients

  In most cases, it will be necessary to restart the Application Server after performing the administrative operations listed above. This is especially the case if you want the effects of the administrative change to be applied to applications that were already deployed on the Application Server at the time the operation was performed.

## To 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

- To specify the default server provider:

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

- To specify the default client provider:

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

## To 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`.

- Add a request policy to the client and set the authentication source:

      asadmin  set --user  admin-user --port admin-port
      server-config.security-service.message-security-config.SOAP.
      provider-config.ClientProvider.request-policy.auth_source=
      sender | content

- Add a request policy to the server and set the authentication source:

      asadmin  set --user  admin-user --port admin-port
      server-config.security-service.message-security-config.SOAP.
      provider-config.ServerProvider.request-policy.auth_source=
      sender | content

- Add a request policy to the client and set the authentication recipient:

      asadmin  set --user  admin-user --port admin-port
      server-config.security-service.message-security-config.SOAP.
      provider-config.ClientProvider.request-policy.auth_recipient=
      before-content | after-content

- Add a request policy to the server and set the authentication recipient:

      asadmin  set --user  admin-user --port admin-port
      server-config.security-service.message-security-config.SOAP.
      provider-config.ServerProvider.request-policy.auth_recipient=
      before-content | after-content

## Creating 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`

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

## To 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`

## To 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

- The Java 2 Standard Edition discussion of security can be viewed from `http://java.sun.com/j2se/1.4.2/docs/guide/security/index.html`.

- The J2EE 1.4 Tutorial chapter titled Security can be viewed from `http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html`.

- The Administration Guide chapter titled Chapter 9, Configuring Security.

- The Developer’s Guide chapter titled Securing Applications.

- The Oasis Web Services Security: SOAP Message Security (WS-Security) specification, can be viewed from http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.

- The OASIS Web Services Security Username Token Profile 1.0, can be found at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf.

- The OASIS Web Services Security X.509 Certificate Token Profile 1.0, can be found at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf.

- The XML-Signature Syntax and Processing document can be viewed at `http://www.w3.org/TR/xmldsig-core/`.

- The XML Encryption Syntax and Processing document can be viewed at `http://www.w3.org/TR/xmlenc-core/`.

- Previous: About Message Security
- Next: Chapter 11 Transactions

- © 2010, Oracle Corporation and/or its affiliates