Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Chapter 1 Setting Up a Development Environment
- Next: Chapter 3 Assembling and Deploying Applications

# Chapter 2 Securing Applications

This chapter describes how to write secure J2EE applications, which contain components that perform user authentication and access authorization for servlets and EJB business logic. For information about administrative security for the server, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

This chapter contains the following sections:

- Security Goals

- Application Server Specific Security Features

- Container Security

- Realm Configuration

- JACC Support

- Pluggable Audit Module Support

- The server.policy File

- Configuring Message Security

- Programmatic Login

- User Authentication for Single Sign-on

- Defining Roles

# Security Goals

In an enterprise computing environment, there are many security risks. The goal of the Sun Java System Application Server is to provide highly secure, interoperable, and distributed component computing based on the J2EE security model. Security goals include:

- Full compliance with the J2EE security model (for more information, see the J2EE specification, v1.4 Chapter 3 Security).

- Full compliance with the EJB v2.1 security model (for more information, see the Enterprise JavaBean specification v2.1 Chapter 15 Security Management). This includes EJB role-based authorization.

- Full compliance with the Java Servlet v2.4 security model (for more information, see the Java Servlet specification, v2.4 Chapter 11 Security). This includes servlet role-based authorization.

- Support for single sign-on across all Application Server applications within a single security domain.

- Support for message security.

- Security support for ACC Clients.

- Support for several underlying authentication realms, such as simple file and LDAP. Certificate authentication is also supported for SSL client authentication. For Solaris, OS platform authentication is supported in addition to these.

- Support for declarative security through Application Server specific XML-based role mapping.

- Support for JACC (Java Authorization Contract for Containers) pluggable authorization as included in the J2EE 1.4 specification and defined by JSR-115.

# Application Server Specific Security Features

The Application Server supports the J2EE v1.4 security model, as well as the following features which are specific to the Application Server:

- Message security; see Configuring Message Security

- Single sign-on across all Application Server applications within a single security domain; see User Authentication for Single Sign-on

- Programmatic login; see Programmatic Login

- A GUI-based deploytool for building XML files containing the security information; see deploytool

# Container Security

The component containers are responsible for providing J2EE application security. There are two security forms provided by the container:

- Programmatic Security

- Declarative Security

## Programmatic Security

Programmatic security is when an EJB component or servlet uses method calls to the security API, as specified by the J2EE security model, to make business logic decisions based on the caller or remote user’s security role. Programmatic security should only be used when declarative security alone is insufficient to meet the application’s security model.

The J2EE specification, v1.4 defines programmatic security as consisting of two methods of the EJB `EJBContext` interface and two methods of the servlet `HttpServletRequest` interface. The Application Server supports these interfaces as specified in the specification.

For more information on programmatic security, see the following:

- Section 3.3.6, Programmatic Security, in the J2EE Specification, v1.4

- Programmatic Login

## Declarative Security

Declarative security means that the security mechanism for an application is declared and handled externally to the application. Deployment descriptors describe the J2EE application’s security structure, including security roles, access control, and authentication requirements.

The Application Server supports the deployment descriptors specified by J2EE v1.4 and has additional security elements included in its own deployment descriptors. Declarative security is the application deployer’s responsibility.

There are two levels of declarative security, as follows:

- Application Level Security

- Component Level Security

### Application Level Security

The application XML deployment descriptor (`application.xml`) contains authorization descriptors for all user roles for accessing the application’s servlets and EJB components. On the application level, all roles used by any application container must be listed in a `role-name` element in this file. The role names are scoped to the EJB XML deployment descriptors (`ejb-jar.xml` and `sun-ejb-jar.xml` files) and to the servlet XML deployment descriptors (`web.xml` and `sun-web.xml` files). The `sun-application.xml` file must also contain matching `security-role-mapping` elements for each `role-name` used by the application.

### Component Level Security

Component level security encompasses web components and EJB components.

A secure web container authenticates users and authorizes access to a servlet or JSP by using the security policy laid out in the servlet XML deployment descriptors (`web.xml` and `sun-web.xml` files).

The EJB container is responsible for authorizing access to a bean method by using the security policy laid out in the EJB XML deployment descriptors (`ejb-jar.xml` and `sun-ejb-jar.xml` files).

# Realm Configuration

This section covers the following topics:

- Supported Realms

- How to Configure a Realm

- How to Set a Realm for an Application or Module

- Creating a Custom Realm

## Supported Realms

The following realms are supported in the Application Server:

- `file` - Stores user information in a file. This is the default realm when you first install the Application Server.

- `ldap` - Stores user information in an LDAP database.

- `certificate` - Sets up the user identity in the Application Server security context, and populates it with user data obtained from cryptographically verified client certificates.

- `solaris` - Allows authentication using Solaris `username+password` data. This realm is only supported on Solaris 9.

For detailed information about configuring each of these realms, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

## How to Configure a Realm

You can configure a realm in one of these ways:

- In the Administration Console, open the Security component under the relevant configuration and go to the Realms page. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- Use the `asadmin create-auth-realm` command to configure realms on local servers. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

## How to Set a Realm for an Application or Module

The following deployment descriptor elements have optional `realm` or `realm-name` data subelements or attributes that override the domain’s default realm:

- `sun-application` element in `sun-application.xml`

- `web-app` element in `web.xml`

- `as-context` element in `sun-ejb-jar.xml`

- `client-container` element in `sun-acc.xml`

- `client-credential` element in `sun-acc.xml`

If modules within an application specify conflicting realms, these are ignored. If present, the realm defined in `sun-application.xml` is used, otherwise the domain’s default realm is used.

For example, a realm is specified in `sun-application.xml` as follows:

    <sun-application>
        ...
        <realm>ldap</realm>
    </sun-application>

For more information about the deployment descriptor files and elements, see Appendix A, Deployment Descriptor Files.

## Creating a Custom Realm

You can create a custom realm by providing a Java Authentication and Authorization Service (JAAS) login module and a realm implementation. Note that client-side JAAS login modules are not suitable for use with the Application Server. For more information about JAAS, refer to the JAAS specification for Java 2 SDK, v 1.4, available at `http://java.sun.com/products/jaas/`.

Custom realms must extend the `com.sun.appserv.security.``AppservPasswordLoginModule` class. This class extends `javax.security.auth.spi.``LoginModule`. Custom realms must not extend `LoginModule` directly.

Custom login modules must provide an implementation for one abstract method defined in `AppservPasswordLoginModule`:

    abstract protected void authenticateUser() throws LoginException

This method performs the actual authentication. The custom login module must not implement any of the other methods, such as `login()`, `logout()`, `abort()`, `commit()`, or `initialize()`. Default implementations are provided in `AppservPasswordLoginModule` which hook into the Application Server infrastructure.

The custom login module can access the following protected object fields, which it inherits from `AppservPasswordLoginModule`. These contain the user name and password of the user to be authenticated:

    protected String _username;
    protected String _password;

The `authenticateUser()` method must end with the following sequence:

    String[] grpList;
    // populate grpList with the set of groups to which
    // _username belongs in this realm, if any
    return commitUserAuthentication(_username, _password,
      _currentRealm, grpList);

Custom realms must also implement a `Realm` class which extends the `com.sun.appserv.security.AppservRealm` class.

Custom realms must implement the following methods:

    public void init(Properties props) throws BadRealmException,
    NoSuchRealmException

This method is invoked during server startup when the realm is initially loaded. The `props` argument contains the properties defined for this realm in `domain.xml`. The realm can do any initialization it needs in this method. If the method returns without throwing an exception, the Application Server assumes the realm is ready to service authentication requests. If an exception is thrown, the realm is disabled.

    public String getAuthType()

This method returns a descriptive string representing the type of authentication done by this realm.

    public abstract Enumeration getGroupNames(String username) throws
    InvalidOperationException, NoSuchUserException

This method returns an `Enumeration` (of `String` objects) enumerating the groups (if any) to which the given `username` belongs in this realm.

# JACC Support

JACC (Java Authorization Contract for Containers) is part of the J2EE 1.4 specification and defined by JSR-115. JACC defines an interface for pluggable authorization providers. This provides third parties with a mechanism to develop and plug in modules that are responsible for answering authorization decisions during J2EE application execution. The interfaces and rules used for developing JACC providers are defined in the JACC 1.0 specification.

The Application Server provides a simple file-based JACC-compliant authorization engine as a default JACC provider. To configure an alternate provider using the Administration Console, open the Security component under the relevant configuration, and select the JACC Providers component. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

# Pluggable Audit Module Support

You can create a custom audit module. This section covers the following topics:

- Configuring an Audit Module

- The AuditModule Class

## Configuring an Audit Module

To configure an audit module, you can perform one of the following tasks:

- To specify an audit module using the Administration Console, open the Security component under the relevant configuration, and select the Audit Modules component. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- You can use the ```asadmin create-audit-module` command to configure an audit module. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

## The AuditModule Class

You can create a custom audit module by implementing a class that extends `com.sun.appserv.security.AuditModule`. The `AuditModule` class provides default “no-op” implementations for each of the following methods, which your custom class can override.

    public void init(Properties props)

This method is invoked during server startup when the audit module is initially loaded. The `props` argument contains the properties defined for this module in `domain.xml`. The module can do any initialization it needs in this method. If the method returns without throwing an exception, the Application Server assumes the module realm is ready to service audit requests. If an exception is thrown the module is disabled.

    public void authentication(String user, String realm, boolean success)

This method is invoked when an authentication request has been processed by a realm for the given user. The `success` flag indicates whether the authorization was granted or denied.

    public void webInvocation(String user, HttpServletRequest req, String type,
    boolean success)

This method is invoked when a web container call has been processed by authorization. The `success` flag indicates whether the authorization was granted or denied. The `req` object is the standard `HttpServletRequest` object for this request. The `type` string is one of `hasUserDataPermission` or `hasResourcePermission` (see JSR-115).

    public void ejbInvocation(String user, String ejb, String method, boolean
    success)

This method is invoked when an EJB container call has been processed by authorization. The `success` flag indicates whether the authorization was granted or denied. The `ejb` and `method` strings describe the EJB component and its method that is being invoked.

# The server.policy File

Each Application Server domain has its own standard J2SE policy file, located in domain-dir`/config`. The file is named `server.policy`.

The Application Server is a J2EE 1.4 compliant application server. As such, it follows the requirements of the J2EE specification, including the presence of the security manager (the Java component that enforces the policy) and a limited permission set for J2EE application code.

This section covers the following topics:

- Default Permissions

- Changing Permissions for an Application

## Default Permissions

Internal server code is granted all permissions. These are covered by the `AllPermission` grant blocks to various parts of the server infrastructure code. Do not modify these entries.

Application permissions are granted in the default grant block. These permissions apply to all code not part of the internal server code listed previously. The Application Server does not distinguish between EJB and web module permissions. All code is granted the minimal set of web component permissions (which is a superset of the EJB minimal set).

A few permissions above the minimal set are also granted in the default `server.policy` file. These are necessary due to various internal dependencies of the server implementation. J2EE application developers must not rely on these additional permissions.

One additional permission is granted specifically for using connectors. If connectors are not used in a particular domain, you should remove this permission, because it is not otherwise necessary.

## Changing Permissions for an Application

The default policy for each domain limits the permissions of J2EE deployed applications to the minimal set of permissions required for these applications to operate correctly. If you develop applications that require more than this default set of permissions, you can edit the `server.policy` file to add the custom permissions that your applications need.

You should add the extra permissions only to the applications that require them, not to all applications deployed to a domain. Do not add extra permissions to the default set (the grant block with no codebase, which applies to all code). Instead, add a new grant block with a codebase specific to the application requiring the extra permissions, and only add the minimally necessary permissions in that block.

Note –

Do not add `java.security.AllPermission` to the `server.policy` file for application code. Doing so completely defeats the purpose of the security manager, yet you still get the performance overhead associated with it.

As noted in the J2EE specification, an application should provide documentation of the additional permissions it needs. If an application requires extra permissions but does not document the set it needs, contact the application author for details.

As a last resort, you can iteratively determine the permission set an application needs by observing `AccessControlException` occurrences in the server log. If this is not sufficient, you can add the `-Djava.security.debug=fail` JVM option to the domain. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide or the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Reference.

You can use the J2SE standard `policytool` or any text editor to edit the `server.policy` file. For more information, see:

http://java.sun.com/docs/books/tutorial/security1.2/tour2/index.html

For detailed information about the permissions you can set in the `server.policy` file, see:

http://java.sun.com/j2se/1.4/docs/guide/security/permissions.html

The Javadoc for the `Permission` class is at:

http://java.sun.com/j2se/1.4/docs/api/java/security/Permission.html

# Configuring Message Security

In message security, security information travels along with the web services message. WSS in the SOAP layer is the use of XML Encryption and XML Digital Signatures to secure SOAP messages. WSS profiles the use of various security tokens including X.509 certificates, SAML assertions, and username/password tokens to achieve this.

Message layer security differs from transport layer security (which is discussed in the Security chapter of the J2EE 1.4 Tutorial) in that message layer security can be used to decouple message protection from message transport so that messages remain protected after transmission, regardless of how many hops they travel on.

WSS is a security mechanism that is applied at the message-layer in order to secure web services. For the purposes of this document, when we discuss WSS, we are talking about security for web services as described by the Oasis Web Services Security (WSS) specification. Message security for the Application Server follows this specification, which can be viewed at the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

For more information about message security, see the following:

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

- The Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide chapter titled Configuring Message Security.

The following web services security topics are discussed in this section:

- Message Security Responsibilities

- Application-Specific Message Protection

- Understanding and Running the Example Application

- Monitoring Message Security

## Message Security Responsibilities

Message security responsibilities are assigned to the following:

- Application Developer

- Application Deployer

- System Administrator

### Application Developer

The application developer can implement message security, but is not responsible for doing so. Message security can be set up by the System Administrator so that all web services are secured, or set up by the Application Deployer when the Application Server provider configuration is insufficient.

The application developer is responsible for the following:

- Determining if an application-specific policy is necessary for an application. If so, ensure that policy is satisfied at application assembly, or communicate the requirement for application-specific message security to the Application Deployer, or take care of implementing the application-specific policy.

- Determining if message security is necessary at the Application Server level. If so, ensure that need is communicated to the System Administrator, or take care of implementing message security at the Application-Server level.

### Application Deployer

The application deployer is responsible for:

- Securing the application if it has not been appropriately secured by upstream roles (the developer or assembler) and only if an application-specific policy is appropriate for the application.

- Implementing application-specific security by adding the message security binding to the web service endpoint.

- Modifying Sun-specific deployment descriptors to add message binding information.

These security tasks are discussed in Application-Specific Message Protection. An example application using message security is discussed in Understanding and Running the Example Application.

### System Administrator

The system administrator is responsible for:

- Configuring message security providers on the Application Server.

- Managing user databases.

- Managing keystore and truststore files.

- Configuring a Java Cryptography Extension (JCE) provider if using Encryption and running a version of the Java SDK prior to version 1.5.0.

- Installing the samples server in order to work with the example message security applications.

A system administrator uses the Admin Console or the `asadmin` tool to manage server security settings and `keytool` to manage certificates. System administrator tasks are discussed in the Configuring Message Security chapter of the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

## Application-Specific Message Protection

When the Application Server provided configuration is insufficient for your security needs, and you want to override the default protection, you can apply application-specific message security to a web service.

Application-specific security is implemented by adding the message security binding to the web service endpoint, whether it is an EJB or servlet web service endpoint. Modify Sun-specific XML files to add the message binding information.

For more details on message security binding for EJB web services, servlet web services, and clients, see the XML file descriptions in Appendix A, Deployment Descriptor Files.

- For `sun-ejb-jar.xml`, see The sun-ejb-jar.xml File.

- For `sun-web.xml`, see The sun-web.xml File.

- For `sun-application-client.xml`, see The sun-application-client.xml file.

This section contains the following topics:

- Using a Signature to Enable Message Protection for All Methods

- Configuring Message Protection For a Specific Method Based on Digital Signatures

### Using a Signature to Enable Message Protection for All Methods

To enable message protection for all methods using digital signature, update the `message-security-binding` element for the EJB web service endpoint in the application’s `sun-ejb-jar.xml` file. In this file, add `request-protection` and `response-protection` elements, which are analogous to the `request-policy` and `response-policy` elements discussed in the Configuring Message Security chapter of the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide. In order to apply the same protection mechanisms for all methods, leave the method-name element blank. Configuring Message Protection For a Specific Method Based on Digital Signatures discusses listing specific methods or using wildcard characters.

This section uses the sample application discussed in Understanding and Running the Example Application to apply application-level message security in order to show only the differences necessary for protecting web services using various mechanisms.

#### To enable message protection for all methods using digital signature

1. In a text editor, open the application’s `sun-ejb-jar.xml` file.

   For the `xms` example, this file is located in the directory install-dir `/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf`.

2. Modify the `sun-ejb-jar.xml` file by adding the `message-security-binding` element as shown:

       <sun-ejb-jar>
         <enterprise-beans>
           <unique-id>1</unique-id>
           <ejb>
             <ejb-name>HelloWorld</ejb-name>
             <jndi-name>HelloWorld</jndi-name>
             <webservice-endpoint>
               <port-component-name>HelloIF</port-component-name>
               <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
               <message-security-binding auth-layer="SOAP">
                 <message-security>
                   <request-protection auth-source="content" />
                   <response-protection auth-source="content"/>
                 </message-security>
               </message-security-binding>
             </webservice-endpoint>
           </ejb>
         </enterprise-beans>
       </sun-ejb-jar>

3. Compile, deploy, and run the application as described in To Run the Sample Application.

### Configuring Message Protection For a Specific Method Based on Digital Signatures

To enable message protection for a specific method, or for a set of methods that can be identified using a wildcard value, follow these steps. As in the example discussed in Using a Signature to Enable Message Protection for All Methods, to enable message protection for a specific method, update the `message-security-binding` element for the EJB web service endpoint in the application’s `sun-ejb-jar.xml` file. To this file, add `request-protection` and `response-protection` elements, which are analogous to the `request-policy` and `response-policy` elements discussed in the Configuring Message Security chapter of the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide. The Administration Guide includes a table listing the set and order of security operations for different request and response policy configurations.

This section uses the sample application discussed in Understanding and Running the Example Application to apply application-level message security in order to show only the differences necessary for protecting web services using various mechanisms.

#### To enable message protection for a particular method or set of methods using digital signature

1. In a text editor, open the application’s `sun-ejb-jar.xml` file.

   For the `xms` example, this file is located in the directory install-dir`/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf`.

2. Modify the `sun-ejb-jar.xml` file by adding the `message-security-binding` element as shown:

       <sun-ejb-jar>
         <enterprise-beans>
         <unique-id>1</unique-id>
           <ejb>
             <ejb-name>HelloWorld</ejb-name>
             <jndi-name>HelloWorld</jndi-name>
             <webservice-endpoint>
               <port-component-name>HelloIF</port-component-name>
               <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
               <message-security-binding auth-layer="SOAP">
                 <message-security>
                   <message>
                     <java-method>
                       <method-name>ejbCreate</method-name>
                     </java-method>
                   </message>
                   <message>
                     <java-method>
                       <method-name>sayHello</method-name>
                     </java-method>
                   </message>
                   <request-protection auth-source="content" />
                   <response-protection auth-source="content"/>
                 </message-security>
               </message-security-binding>
             </webservice-endpoint>
           </ejb>
         </enterprise-beans>
       </sun-ejb-jar>

3. Compile, deploy, and run the application as described in To Run the Sample Application.

## Understanding and Running the Example Application

This section discusses the WSS sample application, `xms`, which is located in the directory install-dir`/samples/webservices/security/ejb/apps/xms/`. This directory and this sample application is installed on your system only if you have selected to install the samples server when you installed the Application Server. If you have not installed the samples, see To Set Up the Sample Application.

The objective of this sample application is to demonstrate how a web service can be secured with WSS. The web service in the `xms` example is a simple web service implemented using a J2EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a service endpoint interface is defined with one operation, `sayHello`, which takes a string then sends a response with `Hello` prefixed to the given string. You can view the WSDL file for the service endpoint interface at install-dir`/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl`.

In this application, the client lookups the service using the JNDI name `java:comp/env/service/HelloWorld` and gets the port information using a static stub to invoke the operation using a given name. For the name Duke, the client gets the response `Hello Duke!`

This example shows how to use message security for web services at the Application Server level and at the application level. The WSS message security mechanisms implement message-level authentication (for example, XML digital signature and encryption) of SOAP web services invocations using the X.509 and username/password profiles of the OASIS WS-Security standard, which can be viewed from the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

This section includes the following topics:

- To Set Up the Sample Application

- To Run the Sample Application

### To Set Up the Sample Application

##### Before You Begin

The example application is located in the directory install-dir`/samples/webservices/security/ejb/apps/xms/`. For ease of reference throughout the rest of this section, this directory is referred to as simply app-dir`/xms/`.

In order to have access to this sample application, you must have installed the `samples` server during installation of the Application Server. To check to see if the samples are installed, browse to the directory install-dir`/samples/webservices/security/ejb/apps/xms/`. If this directory exists, you do not need to follow the steps in the following section. If this directory does not exist, the `samples` server is not installed, and must be installed for access to the sample application discussed here.

1. Start the installation for the Application Server.

2. Click Next on the Welcome page.

3. Click Yes on the Software License Agreement page. Click Next.

4. Click Next to accept the installation directory, or change it to match the location where the Application Server is currently installed.

5. Select Continue to install to the same directory.

   You want to do this because you want the `samples/` directory to be a subdirectory of the Application Server directory, install-dir`/samples/`.

6. Reenter the Admin User Name and Password. Click Next.

   You are on the page where you select to install just the samples.

7. Deselect everything except Create Samples Server. Click Next.

8. Click Install Now to install the samples.

9. Click Finish to complete the installation.

### To Run the Sample Application

1. Make sure that the Application Server is running.

   Message security providers are set up when the `asant` targets are run, so you don’t need to configure these on the Application Server prior to running this example.

2. If you are not running HTTP on the default port of 8080, change the WSDL file for the example to reflect the change, and change the `common.properties` file to reflect the change as well.

   The WSDL file for this example is located at install-dir`/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl`. The port number is in the following section:

       <service name="HelloWorld">
         <port name="HelloIFPort" binding="tns:HelloIFBinding">
           <soap:address location="http://localhost:8080/service/HelloWorld"/>
         </port>
       </service>

   Verify that the properties in the install-dir`/samples/common.properties` file are set properly for your installation and environment. If you need more description of this file, refer to the Configuration section for the web services security applications at install-dir`/samples/webservices/security/docs/common.html#Logging`.

3. Change to the install-dir`/samples/webservices/security/ejb/apps/xms/` directory.

4. Run the following `asant` targets to compile, deploy, and run the example application:

   1. To compile samples:

      `asant`

   2. To deploy samples:

      `asant deploy`

   3. To run samples:

      `asant run`

   If the sample has compiled and deployed properly, you see the following response on your screen after the application has run:

   `run:[echo] Running the xms program:[exec] Established message level security : Hello Duke!`

5. To undeploy the sample, run the following `asant` target:

       asant undeploy

   All of the web services security examples use the same web service name (`HelloWorld`) and web service ports in order to show only the differences necessary for protecting web services using various mechanisms. Make sure to undeploy an application when you have completed running it, or you receive an `Already in Use` error and deployment failures when you try to deploy another web services example application.

## Monitoring Message Security

To view SOAP messages containing security elements in the `server.log` file, set the parameter `dumpMessages=true` in the file domain-dir`/config/wss-server-config.xml`, and then restart the server.

The section of the `wss-server-config.xml` file that needs to be modified to enable this is as shown below:

    <xwss:SecurityConfiguration
        xmlns:xwss="http://com.sun.xml.wss.configuration"
        useTimestamps="true"
        dumpMessages="true">

After you have enabled SOAP messages in the `server.log` file, you can verify if the username-password token is enabled by checking the domain-dir`/logs/server.log` file for the tag `<wsse:UsernamePassword>`. The following selection of code is similar to what you might see in the `server.log` file, with the `UsernameToken` tag.

    <?xml version="1.0" encoding="UTF-8"?>
    <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:ns0="http://tax.org/wsdl"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" >
    <env:Header>
      <wsse:Security   xmlns:wsse="http://docs.oasis-open.org/wss/2004/
        01/oasis-200401-wss-wssecurity-secext-1.0.xsd" env:mustUnderstand="1">
        <wsse:UsernameToken>
          <wsse:Username>j2ee</wsse:Username>
          <wsse:Password Type="http://docs.oasis-open.org/wss/2004/
          01/oasis-200401-wss-username-token-profile-1.0#PasswordText">j2ee
          </wsse:Password>
        </wsse:UsernameToken>
        <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/
          01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
          <wsu:Created>2004-08-22T09:07:58Z</wsu:Created>
        </wsu:Timestamp>
        </wsse:Security>
          </env:Header>
          <env:Body>
            <ns0:getStateTax>
            <double_1 xsi:type="xsd:double">85000.0</double_1>
            <double_2 xsi:type="xsd:double">5000.0</double_2>
            </ns0:getStateTax>
          </env:Body>
    </env:Envelope>

# Programmatic Login

Programmatic login allows a deployed J2EE application to invoke a login method. If the login is successful, a `SecurityContext` is established as if the client had authenticated using any of the conventional J2EE mechanisms.

Programmatic login is useful for an application that has special needs which cannot be accommodated by any of the J2EE standard authentication mechanisms.

Note –

Programmatic login is specific to the Application Server and not portable to other application servers.

This section contains the following topics:

- Precautions

- Granting Programmatic Login Permission

- The ProgrammaticLogin Class

## Precautions

The Application Server is not involved in how the login information (`user`, `password`) is obtained by the deployed application. Programmatic login places the burden on the application developer with respect to assuring that the resulting system meets their security requirements. If the application code reads the authentication information across the network, it is up to the application to determine whether to trust the user.

Programmatic login allows the application developer to bypass the application server-supported authentication mechanisms and feed authentication data directly to the security service. While flexible, this capability should not be used without some understanding of security issues.

Since this mechanism bypasses the container-managed authentication process and sequence, the application developer must be very careful in making sure that authentication is established before accessing any restricted resources or methods. It is also the application developer’s responsibility to verify the status of the login attempt and to alter the behavior of the application accordingly.

The programmatic login state does not necessarily persist in sessions or participate in single sign-on.

Lazy authentication is not supported for programmatic login. If an access check is reached and the deployed application has not properly authenticated via the programmatic login method, access is denied immediately and the application might fail if not properly coded to account for this occurrence.

## Granting Programmatic Login Permission

The `ProgrammaticLoginPermission` permission is required to invoke the programmatic login mechanism for an application. This permission is not granted by default to deployed applications because this is not a standard J2EE mechanism.

To grant the required permission to the application, add the following to the domain-dir`/config/``server.policy` file:

    grant codeBase "file:jar-file-path" {
         permission com.sun.appserv.security.ProgrammaticLoginPermission
         "login";
     };

The jar-file-path is the path to the application’s JAR file.

For more information about the `server.policy` file, see The server.policy File

## The ProgrammaticLogin Class

The `com.sun.appserv.security.ProgrammaticLogin` class enables a user to perform login programmatically. This class has four `login` methods, two for servlets or JSP files and two for EJB components.

The login methods for servlets or JSP files have the following signatures:

    public java.lang.Boolean login(String user, String password,
    javax.servlet.http.HttpServletRequest request,
    javax.servlet.http.HttpServletResponse response)

    public java.lang.Boolean login(String user, String password,
    String realm, javax.servlet.http.HttpServletRequest request,
    javax.servlet.http.HttpServletResponse response, boolean errors)
    throws java.lang.Exception

The login methods for EJB components have the following signatures:

    public java.lang.Boolean login(String user, String password)

    public java.lang.Boolean login(String user, String password,
    String realm, boolean errors) throws java.lang.Exception

All of these`login` methods:

- Perform the authentication

- Return `true` if login succeeded, `false` if login failed

The login occurs on the `realm` specified unless it is null, in which case the domain’s default realm is used. The methods with no `realm` parameter use the domain’s default realm.

If the `errors` flag is set to `true`, any exceptions encountered during the logout are propagated to the caller. If set to `false`, exceptions are thrown.

The logout methods for servlets or JSP files have the following signatures:

    public java.lang.Boolean logout(HttpServletRequest request,
    HttpServletResponse response)

    public java.lang.Boolean logout(HttpServletRequest request,
    HttpServletResponse response, boolean errors)
    throws java.lang.Exception

The logout methods for EJB components have the following signatures:

    public java.lang.Boolean logout()

    public java.lang.Boolean logout(boolean errors)
    throws java.lang.Exception

All of these`logout` methods return `true` if logout succeeded, `false` if logout failed.

If the `errors` flag is set to `true`, any exceptions encountered during the logout are propagated to the caller. If set to `false`, exceptions are thrown.

# User Authentication for Single Sign-on

The single sign-on feature of the Application Server allows multiple web applications deployed to the same virtual server to share the user authentication state. With single sign-on enabled, users who log in to one web application become implicitly logged into other web applications on the same virtual server that require the same authentication information. Otherwise, users would have to log in separately to each web application whose protected resources they tried to access.

An example application using the single sign-on scenario could be a consolidated airline booking service that searches all airlines and provides links to different airline web sites. Once the user signs on to the consolidated booking service, the user information can be used by each individual airline site without requiring another sign-on.

Single sign-on operates according to the following rules:

- Single sign-on applies to web applications configured for the same realm and virtual server. The realm is defined by the `realm-name` element in the `web.xml` file. For information about virtual servers, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

- As long as users access only unprotected resources in any of the web applications on a virtual server, they are not challenged to authenticate themselves.

- As soon as a user accesses a protected resource in any web application associated with a virtual server, the user is challenged to authenticate himself or herself, using the login method defined for the web application currently being accessed.

- Once authenticated, the roles associated with this user are used for access control decisions across all associated web applications, without challenging the user to authenticate to each application individually.

- When the user logs out of one web application (for example, by invalidating the corresponding session), the user’s sessions in all web applications are invalidated. Any subsequent attempt to access a protected resource in any application requires the user to authenticate again.

The single sign-on feature utilizes HTTP cookies to transmit a token that associates each request with the saved user identity, so it can only be used in client environments that support cookies.

To configure single sign-on, set the following properties in the `virtual-server` element of the `domain.xml` file:

- `sso-enabled` - If `false`, single sign-on is disabled for this virtual server, and users must authenticate separately to every application on the virtual server. The default is `true`.

- `sso-max-inactive-seconds` - Specifies the time after which a user’s single sign-on record becomes eligible for purging if no client activity is received. Since single sign-on applies across several applications on the same virtual server, access to any of the applications keeps the single sign-on record active. The default value is 5 minutes (`300` seconds). Higher values provide longer single sign-on persistence for the users at the expense of more memory use on the server.

- `sso-reap-interval-seconds` - Specifies the interval between purges of expired single sign-on records. The default value is `60`.

Here is an example configuration with all default values:

    <virtual-server id="server" ... >
         ...
        <property name="sso-enabled" value="true"/>
         <property name="sso-max-inactive-seconds" value="450"/>
         <property name="sso-reap-interval-seconds" value="80"/>
     </virtual-server>

# Defining Roles

You define roles in the J2EE deployment descriptor file, `web.xml`, and the corresponding role mappings in the Application Server deployment descriptor file, `sun-application.xml` (or `sun-web.xml` for individually deployed web modules).

For more information regarding `web.xml` elements, see Chapter 13, “Deployment Descriptor,” of the Java Servlet Specification, v2.4. For more information regarding `sun-web.xml` and `sun-application.xml` elements, see Appendix A, Deployment Descriptor Files.

Each `security-role-mapping` element in the `sun-application.xml` or `sun-web.xml` file maps a role name permitted by the web application to principals and groups. For example, a `sun-web.xml` file for an individually deployed web module might contain the following:

    <sun-web-app>
        <security-role-mapping>
            <role-name>manager</role-name>
            <principal-name>jgarcia</principal-name>
            <principal-name>mwebster</principal-name>
            <group-name>team-leads</group-name>
        </security-role-mapping>
        <security-role-mapping>
            <role-name>administrator</role-name>
            <principal-name>dsmith</principal-name>
        </security-role-mapping>
    </sun-web-app>

Note that the `role-name` in this example must match the `role-name` in the `security-role` element of the corresponding `web.xml` file.

Note that for J2EE applications (EAR files), all security role mappings for the application modules must be specified in the `sun-application.xml` file. For individually deployed web modules, the roles are always specified in the `sun-web.xml` file. A role can be mapped to either specific principals or to groups (or both). The principal or group names used must be valid principals or groups in the current default realm.

- Previous: Chapter 1 Setting Up a Development Environment
- Next: Chapter 3 Assembling and Deploying Applications

- © 2010, Oracle Corporation and/or its affiliates