Sun Java logo     Previous      Contents      Next     

Sun logo
Sun Java System Application Server Enterprise Edition 8 2004Q4 XML and Web Services Security Guide 

Securing Web Services

This section shows the following examples of configurations with message security for Web services.

Securing a Web Service Using Username-Password Tokens

Username token verification specifies a process for sending UserName tokens along with the message. The receiver can validate the identity of the sender by validating the password.

To enable username-password token message security, follow the steps outlined in this section. Before you start, make sure you have enabled the default providers as described in Enable the Default Providers for the Application Server and Enable Default Client Provider in the Application Client.

To secure a Web service using username-password tokens, follow these steps:

  1. Set the request policy on the Application Server following one of these methods:
  2. Set the request policy in the application client configuration file following the steps described in Setting the Request Policy for the Application Client Configuration (Username Token).
  3. Deploy the Web service as you would any Web service.
  4. Create a user in the realm to which you have deployed this application. You can use the default file realm or create a custom realm to use for WSS applications. Steps for creating realms and adding users are described in Configuring a User Database for Username Tokens.
  5. Access the Web service’s application client using the user name and password created in the previous step.

Using the Admin Console to Add a Request Policy (Username Token)

Add a request policy and a response policy with the authenticate source set to sender on the server side. To do this, follow these steps:

  1. Start the Application Server.
  2. Start the Admin Console by entering the following URL in a browser window:
  1. In the Admin Console tree component, expand the Configurations node.
  2. Select the instance you want 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 for that node.
  7. In the Provider Id column, select ClientProvider (or the provider you’ve enabled to be the client provider if using other than the default).
  8. In the Request Policy section of the Edit Provider Config page, select sender from the Authenticate Source list.
  9. Click Save.
  10. Select the SOAP node.
  11. Select the Providers tab for that node.
  12. In the Provider Id column, select ServerProvider (or the provider you’ve enabled to be the client provider if using other than the default).
  13. In the Request Policy section of the Edit Provider Config page, select sender from the Authenticate Source list.
  14. Click Save.

Using the asadmin tool to Add a Request Policy (Username Token)

Add a request policy with the authenticate source set to sender on the server side. To do this using the asadmin tool, use these commands. The first command adds a request policy to the client, the second command adds a request policy to the server.

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

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

Setting the Request Policy for the Application Client Configuration (Username Token)

To set the request policy for the application client configuration, modify the file install_dir/domains/domain_dir/config/sun-acc.xml. This file contains the Sun Java System Application Server-specific configuration for the application client container.

  1. Stop the Application Server.
  2. In a text editor, open the Sun application client container descriptor, sun-acc.xml, which is located in the directory install_dir/domains/domain_dir/config/.
  3. Add the text in bold 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 code that is not in bold may differ slightly in your installation, do not change the text that is not in bold.

    4. <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.xml.wss.provider.ClientSecurityAuthModule"       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>

  4. Restart the Application Server.

Securing a Web Service Using Digital Signature Tokens

XML Digital Signature is used to authenticate the source of the signed content. The content is signed, so the signer can attest to some content. Those who receive the content can tell if it was changed after the signer attested to it.

To enable the Digital Signature token for message security, follow the steps outlined in this section.

To secure a Web service using digital signature tokens, follow these steps:

  1. Set the request policy on the Application Server following one of these methods:
  2. Set the request policy in the application client configuration file following the steps described inSetting the Request and Response Policy for the Application Client Configuration (Signature).
  3. Deploy the Web service as you would any Web service.
  4. If you have not already done so, set the keystore and truststore environment variables as described in Setting Keystore and Truststore Variables (Signature).
  5. Access the Web service’s application client using the keystore and truststore properties specified in the previous step.

Using the Admin Console to Add a Request Policy (Signature)

Add a request policy and a response policy with the authenticate source set to content on the server side. To do this, follow these steps:

  1. Start the Application Server.
  2. Start the Admin Console by entering the following URL in a browser window:
  1. In the Admin Console tree component, expand the Configurations node.
  2. Select the instance you want 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 for that node.
  7. In the Provider Id column, select ClientProvider (or the provider you’ve enabled to be the client provider if using other than the default).
  8. In the Request Policy section of the Edit Provider Config page, select content from the Authenticate Source list.
  9. Click Save.
  10. Select the SOAP node.
  11. Select the Providers tab for that node.
  12. In the Provider Id column, select ServerProvider (or the provider you’ve enabled to be the client provider if using other than the default).
  13. In the Request Policy section of the Edit Provider Config page, select content from the Authenticate Source list.
  14. Click Save.

Using the asadmin tool to Add a Request Policy (Signature)

Add a request policy with the authenticate source set to content on the server side. To do this using the asadmin tool, use these commands. The first command adds a request policy to the client, the second command adds a request policy to the server.

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

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

Setting the Request and Response Policy for the Application Client Configuration (Signature)

To set the request and the response policy for the application client configuration, modify the file install_dir/domains/domain_dir/config/sun-acc.xml. This file contains the Sun Java System Application Server-specific configuration for the application client container.

  1. Stop the Application Server.
  2. In a text editor, open the Sun application client container descriptor, sun-acc.xml, which is located in the directory install_dir/domains/domain_dir/config/.
  3. Add the text in bold 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 code that is not in bold may differ slightly in your installation, do not change the text that is not in bold.

    4. <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.xml.wss.provider.ClientSecurityAuthModule"       provider-id="ClientProvider" provider-type="client">
          <request-policy auth-source="content"/>
          <response-policy auth-source=”content”/>
           <property name="security.config"       value="C:/Sun/AppServer/lib/appclient/wss-client-config.xml"/>
        </provider-config>
      </message-security-config>
    </client-container>

  4. Restart the Application Server.

Setting Keystore and Truststore Variables (Signature)

If you are using the default keystore and truststore files that are shipped with the Application Server, check to make sure the JVM options that point to these files are set properly. If you want to learn more about keystore and truststore files, or use other keystore or truststore files, you can do that following the steps outlined in Setting Up the Keystore and TrustStore Files in the Application Server.

In the Enterprise Edition, you can use Network Security Services (NSS) to manage keystore and truststore files. For more information on NSS, go to http://www.mozilla.org/projects/security/pki/nss/. The tools for managing security include the following:

If you use NSS for managing keystore and truststore files, you would modify the property com.sun.appserv.nss.db in place of the javax.net.ssl.keyStore and javax.net.ssl.trustStore properties mentioned in the steps below. For more information on using certutil, pk12util, and other NSS security tools, see NSS Security Tools at http://www.mozilla.org/projects/security/pki/nss/.

To use the default keystore and truststore files, follow these steps before accessing the application client.

  1. Start the Application Server.
  2. Start the Admin Console by entering the following URL in a browser window:
  1. In the Admin Console tree, expand Configurations.
  2. Expand the server-config (Admin Config) node.
  3. Select the JVM Settings node.
  4. Click the JVM Options tab.
  5. On the JVM Options page, add, verify, or modify the following values in the Value field to reflect the location of the default certificate files:

    6. -Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/
    keystore.jks
    -Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/
    cacerts.jks

  6. Click Save.
  7. Restart the Application Server if Restart Required displays in the console.

In the default certificates, the configuration uses the nickname s1as as the alias. You can change the certificates without changing the alias, and you can change the alias without changing the certificates. If you change the alias or the name or location of the keystore and truststore files, make sure you follow the steps in Setting Up the Keystore and TrustStore Files in the Application Server.

Securing a Web Service Using XML Encryption

In the Application Server, XML Encryption is implemented following the process defined in the XML Encryption and Processing document, viewable from the following URL:

http://www.w3.org/TR/xmlenc-core/

The document referenced above specifies a process for encrypting data and representing the result in XML. The data may be arbitrary data (including an XML document), an XML element, or XML element content. The result of encrypting data is an XML Encryption element which contains or references the cipher data. Web services can be doubly secured by encrypting the SOAP body before or after signing the body.

To enable the encryption in message security, follow the steps outlined in this section. Before you start, make sure you have enabled the default providers as described in Enable the Default Providers for the Application Server and Enable Default Client Provider in the Application Client.

Note: By default, J2SE 1.4.2 does not implement the RSA encryption algorithms. You need to add a third party JCE provider (such as Bouncy Castle) to use encryption, or use J2SE 1.50 or higher for your JDK. For more information on adding a JCE provider, read Configuring a JCE Provider.

To secure a Web service using XML encryption, follow these steps:

  1. Set the request policy on the Application Server following one of these methods:
  2. Set the request policy in the application client configuration file following the steps described inSetting the Request Policy for the Application Client Configuration (Encryption).
  3. Deploy the Web service as you would any Web service.
  4. If you have not already done so, set the keystore and truststore environment variables as described in Setting Keystore and Truststore Variables (Encryption).
  5. Access the Web service’s application client using the keystore and truststore properties specified in the previous step.

Using the Admin Console to Add a Request Policy (Encryption)

Encryption is accomplished by setting a recipient authentication policy of before-content or after-content. To specify a recipient authentication policy on the server-side, add a request policy and a response policy with the authenticate recipient set to one of these choices. To do this, follow these steps:

  1. Start the Application Server.
  2. Start the Admin Console by entering the following URL in a browser window:
  1. In the Admin Console tree component, expand the Configurations node.
  2. Select the instance you want 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 for that node.
  7. In the Provider Id column, select ClientProvider (or the provider you’ve enabled to be the client provider if using other than the default).
  8. In the Request Policy section of the Edit Provider Config page, select content from the Authenticate Source list.
  9. In the Request Policy section of the Edit Provider Config page, select before-content from the Authenticate Recipient list to enable encryption before signing, or select after-content to enable encryption after signing.
  10. Click Save.
  11. Select the SOAP node.
  12. Select the Providers tab for that node.
  13. In the Provider Id column, select ServerProvider (or the provider you’ve enabled to be the client provider if using other than the default).
  14. In the Request Policy section of the Edit Provider Config page, select content from the Authenticate Source list.
  15. In the Request Policy section of the Edit Provider Config page, select before-content from the Authenticate Recipient list to enable encryption before signing, or select after-content to enable encryption after signing.
  16. Click Save.

Using the asadmin tool to Add a Request Policy (Encryption)

Add a request policy with the authenticate source set to content on the server side. To do this using the asadmin tool, use these commands.

This set of commands adds a request policy to the client. Change before_content to after_content to add encryption after signing.

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

This set of commands adds a request policy to the server. Change before_content to after_content to add encryption after signing.

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

Setting the Request Policy for the Application Client Configuration (Encryption)

To set the request policy for the application client configuration, modify the file install_dir/domains/domain_dir/config/sun-acc.xml. This file contains the Sun Java System Application Server-specific configuration for the application client container.

  1. Stop the Application Server.
  2. In a text editor, open the Sun application client container descriptor, sun-acc.xml, which is located in the directory install_dir/domains/domain_dir/config/.
  3. Add the text in bold to the file to enable the default client provider in the application client. Use after_content in place of before_content to add encryption after signing. The other code is provided to show where the code to enable message security for client applications should be located. The code that is not in bold may differ slightly in your installation, do not change the text that is not in bold.

    4. <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.xml.wss.provider.ClientSecurityAuthModule"       provider-id="ClientProvider" provider-type="client">
            auth-recipient=before-content/>
          <response-policy auth-source=”content”/>
           <property name="security.config"       value="C:/Sun/AppServer/lib/appclient/wss-client-config.xml"/>
        </provider-config>
      </message-security-config>
    </client-container>

  4. Restart the Application Server.

Setting Keystore and Truststore Variables (Encryption)

If you are using the default keystore and truststore files that are shipped with the Application Server, check to make sure the JVM options that point to these files are set properly. If you want to use other keystore or truststore files, you can do that following the steps outlined in Setting Up the Keystore and TrustStore Files in the Application Server.

In the Enterprise Edition, you can use Network Security Services (NSS) to manage keystore and truststore files. For more information on NSS, go to http://www.mozilla.org/projects/security/pki/nss/. The tools for managing security include the following:

If you use NSS for managing keystore and truststore files, you would modify the property com.sun.appserv.nss.db in place of the javax.net.ssl.keyStore and javax.net.ssl.trustStore properties mentioned in the steps below. For more information on using certutil, pk12util, and other NSS security tools, see NSS Security Tools at http://www.mozilla.org/projects/security/pki/nss/.

If you have not already completed this steop, follow these steps to use the default keystore and truststore files before accessing the application client.

  1. Start the Application Server.
  2. Start the Admin Console by entering the following URL in a browser window:
  1. In the Admin Console tree, expand Configurations.
  2. Expand the server-config (Admin Config) node.
  3. Select the JVM Settings node.
  4. Click the JVM Options tab.
  5. On the JVM Options page, add or modify the following values in the Value field to reflect the location of the default certificate files:

    6. -Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/
    keystore.jks
    -Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/
    cacerts.jks

  6. Click Save.
  7. Restart the Application Server if Restart Required displays in the console.

In the default certificates, the configuration uses the nickname s1as as the alias. If you are using certificates other than the default certificates, make sure you follow the steps in Setting Up the Keystore and TrustStore Files in the Application Server.



Previous      Contents      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.