Skip navigation.
Downloads | Product Documentation | Support

Installing WebLogic Server v8.1 Security Service Module

# Post Installation Tasks

This section describes each task you must perform after you install the product software and discusses other considerations.

Note: If you want to use the WebLogic Server 8.1 Security Service Module to integrate AquaLogic Enterprise Security with WebLogic Portal server and portal applications, skip this section and go to Integrating with WebLogic Portal.

Note: Some of the procedures described here require basic knowledge of both WebLogic Server and AquaLogic Enterprise Security products. If you need assistance with any task, see the Administration Console online help or the Administration and Deployment Guide for more details. It is assumed that you know the location of the products you have installed, including the WebLogic Server, the Security Service Module, and the Administration Server.

- Enrolling the Service Control Manager
- Configuring a Service Control Manager
- Configuring and Binding a WebLogic 8.1 Server Security Service Module
- Creating an Instance of the WebLogic 8.1 Security Service Module
- Enrolling the Instance of the Security Service Module
- Location of the WebLogic Server Domain
- Modifying the startWebLogic File
- Defining Security Properties
- Starting and Stopping Processes
- Additional Post-Installation Considerations
- Protecting a Cluster of WebLogic Servers
- What's Next?

# Enrolling the Service Control Manager

This section describes how to enroll the Service Control Manager. Each machine on which you install a Security Service Module must have one (and only one) enrolled Service Control Manager. You only need to follow this procedure if you installed the Security Service Module on a machine other than the one that contains the Administration Server.

Note: While you can use the demonstration digital certificate to enroll in a development environment, you should never use it in a production environment.

To enroll the Service Control Manager, perform the following steps:

1. Open a command window and go to the Service Control Manager `/bin` directory, for example:

>     BEA_HOME/ales21-scm/bin

Where:

`BEA_HOME` is the directory where your BEA products are installed.

`ales21-scm` is the directory where you installed the Service Control Manager.

2. Run the following script:

`enrolltool demo`

The Enrollment menu appears.

3. Type: 5 and press <`ENTER`>, and do one of the following:

- If the domain you to which you want to enroll the SSM is listed, go to step 4.
- If the domain you want to use is not listed, type: 3, press <`ENTER`> to register the domain, enter the following information, Type: 5 and press `<ENTER>` again:

>     Enter Enterprise Domain Name :> (For example: asi)
>     Enter Primary Admin URL :> (For example: https://adminmachine:7010/asi)
>     Secondary Admin URL :> (This value is optional. Same format as primary URL)
>     SCM name :> (For example: ssmmachinename_ssm)
>     SCM port :> (Default: 7010)

4. Select the domain you want to use and press `<ENTER>`.
5. Enter the admin username and password. This is the username and password of the security administrator that is enrolling the SCM.
6. Enter and confirm the following passwords:

- Private key password—Protects the identity of the Service Control Manager you are creating
- identity.jks password—Protects the `ssl\identity.jks` keystore. This keystore contains the identities for all the components you are enrolling.
- peer.jks password—Protects the `ssl\peer.jks` keystore. This keystore contains the certificates of components with which this Security Service Module can communicate.
- trust.jks password—Protects the `ssl\trust.jks` keystore. This keystore contains the AquaLogic Enterprise Security CA certificate used for enrollment.

# Configuring a Service Control Manager

You configure a Service Control Manager (SCM) for each of the machines on which you have installed one of more Security Service Modules (SSM). Each machine must have one (and only one) configured Service Control Manager. For example, if you install an SSM on the same machine as the Administration Server, you must use the `adminconfig` SCM, which was configured for you when you installed the Administration Server.

Note: When you use the Instance Wizard to create an instance of a SSM on a machine, you link the instance to a SCM by name. When you install multiple SSMs of different types (Web Server or Web Services, WebLogic Server 8.1, and Java) on the same machine, they all must use the same SCM.

To configure a SCM, see the Administration Server Console Help and use the AquaLogic Enterprise Security Administration Console.

# Configuring and Binding a WebLogic 8.1 Server Security Service Module

Configure a SSM with the security providers that you require for the WebLogic Server 8.1 SSM and bind it to the SCM. You have the option of configuring either the default security providers that ship with the product or custom security providers, which you develop or purchase from third-party security vendors. The WebLogic Server 8.1 SSM supports the following types of security providers:

- Authentication provider
- Authorization provider
- Auditing provider
- Credential mapping provider
- Identity asserter
- Principal validator
- Role mapping provider

To configure these providers and bind the configuration to the SCM, perform the following steps:

1. In the Administration Console, expand the Security Configuration node in the left pane, and click Unbound Configurations. The Unbound Security Service Module Configurations page displays.
2. Click Create a New Security Service Module Configuration. The Edit Security Service Module Configuration page displays.
3. In the Configuration ID text box, enter an identity for the SSM (for example, `weblogic81_ssm`) and click Create.

Note: Later, when you use the Instance Wizard to create an instance of the SSM to which this security configuration will be applied, you will use the Configuration ID to link the SSM instance to this security configuration.

4. Click the Providers tab and create the desired providers.
5. Click on the SCM that you previously configured for this SSM. The Edit a Service Control Manager Configuration page displays.
6. Click on the Binding tab and bind the WebLogic 8.1 SSM configuration to the SCM.

# Creating an Instance of the WebLogic 8.1 Security Service Module

Before starting a WebLogic Server Security Service Module, you must first create an instance of the Security Service Module using the Instance Wizard. You can create any number of instances of the Security Service Module. You must then enroll each instance that you want to use. Each instance has its own set of providers.

To create an instance of a Security Service Module:

1. Start the Instance Wizard:

- On Widows, click Start>Programs>BEA AquaLogic Enterprise Security>WebLogic Server 8.1 Security Service Module>Create New Instance.

On Unix, if you are using X-windows, go to `BEA_HOME``/ales21-ssm/wls-ssm/adm` and enter: `instancewizard.sh.`

Note: If you are not using X-windows, use a console based installer.

2. In the Instance Name text box, enter the name to assign to this instance. The name must be unique for WebLogic Server SSMs on this machine.
3. In the Authorization Engine port text box, enter the port number for the Authorization and Role Mapping engine to use.
4. In the Configuration ID text box, enter the configuration identifier to use with this instance. The Configuration ID was specified when you configured your module, as described in Configuring and Binding a WebLogic 8.1 Server Security Service Module.
5. From the Enterprise Domain drop-down box, select the domain to which this instance belongs.
6. Click Next.
7. In the Location text box, enter the location for this instance. The default instance is located within the installation directory of the Security Service Module.
8. Click Next.
9. Click Done when the instance wizard completes.

# Enrolling the Instance of the Security Service Module

You must have the Administration Server running prior to enrolling the Security Service Module.

Note: While you can use the demonstration digital certificate in a development environment, you should never use it in a production environment.

To enroll the Security Service Module:

1. Open a command window and go to the Security Service Module instance `/adm` directory: `BEA_HOME/ales21-ssm/wls-ssm/instance/``instancename``/adm`, where `instancename` is the name you assigned to the instance when you created it.
2. Run the following script:

`enroll demo`

3. Enter the `admin` username and password. This is the username and password of the Security Administrator doing the enrollment (if you used the default values and have not yet changed them, the default username is `system` and the password is `weblogic`).
4. Enter and confirm the following passwords:

- Private key password—This password protects the identity of the Security Service Module that you are creating.
- identity.jks password—This password protects the `ssl\identity.jks` keystore. This keystore contains the identities for all the components you are enrolling.
- peer.jks password—This password protects the `ssl\peer.jks` keystore. This keystore contains the certificates of components with which this Security Service Module can communicate.
- trust.jks password—This password protects the `ssl\trust.jks` keystore. This keystore contains the AquaLogic Enterprise Security CA certificate used for enrollment.

# Location of the WebLogic Server Domain

For the purposes of the example presented here, this document assumes that the WebLogic Server domain is in the following location:

>     BEA_HOME/user_projects/domains/mydomain

However, your domain can be in any location you desire. If you want to create a domain, you can use the WebLogic Server Configuration Wizard to create a domain or create it manually. The domain includes a `startWebLogic` file, which you are instructed to modify in Modifying the startWebLogic File.

# Modifying the startWebLogic File

The WebLogic startup script does the following:

- Sets environment variables.
- Invokes the java weblogic.Server command, which starts a JVM that is configured to run a WebLogic Server instance.

Before you can start a WebLogic Server that uses BEA AquaLogic Enterprise Security, you must edit the `startWebLogic` file that is located in the WebLogic Server domain directory, for example:

>     BEA_HOME/user_projects/domains/mydomain

>     where:

`user_projects` is the directory where your WebLogic Server user projects are located.

`domains` is the directory where your WebLogic Server domain instances are located.

`mydomain` is the name of the WebLogic Server domain instance you are using.

See Listing 4-1 for an example of a modified `startWebLogic.cmd` file. To edit the `startWebLogic` file, do the following:

1. Before the `CLASSPATH` is set, add a call to the `set-wls-env` script file in your the `bin` directory for your instance. For example:

>     BEA_HOME/ales21-ssm/wls-ssm/instance/wls81ssm/bin

>     Where:

ales21-ssm is the directory where you installed the Security Service Module.

instance is the directory where all instances are stored.

`wls81ssm` is the name of the Security Service Module instance you created earlier.

2. For example, if you created an instance called `myInstance`, the call looks like this:

On Windows:

>     call "C:\bea\ales21-ssm\wls-ssm\instance\myInstance\bin\set-wls-env.bat"

On Unix:

>     . "/bea/ales21-ssm/wls-ssm/instance/myInstance/bin/set-wls-env.sh"

3. Add the following line to the `CLASSPATH`:

On Windows:

>     %WLES_PRE_CLASSPATH% and %WLES_POST_CLASSPATH%

On Unix:

>     ${WLES_PRE_CLASSPATH} and ${WLES_POST_CLASSPATH}

4. On Windows, add quotes to `%JAVA_HOME%\bin\java` in the `weblogic.Server` command.

>     "%JAVA_HOME%\bin\java"

5. Add the following line to the `weblogic.Server` command.

On Windows:

>     %WLES_JAVA_OPTIONS%

On Unix:

>     ${WLES_JAVA_OPTIONS}

Listing 4-1 Modifying the startWebLogic.cmd File for Windows

>     ...

>     set SERVER_NAME=myserver

>     call "C:\BEA_HOME\ales21-ssm\wls-ssm\instance\myInstance\bin\set-wls-env.bat"

>     set CLASSPATH=%WLES_PRE_CLASSPATH%;%WEBLOGIC_CLASSPATH%;
>     %POINTBASE_CLASSPATH%;%JAVA_HOME%\jre\lib\rt.jar;
>     %WL_HOME%\server\lib\webservices.jar;%CLASSPATH%;
>     %WLES_POST_CLASSPATH%

>     @REM Call WebLogic Server
>     echo .
>     echo CLASSPATH=%CLASSPATH%
>     echo .
>     echo PATH=%PATH%
>     echo .

>     echo ***************************************************
>     echo *  To start WebLogic Server, use a username and   *
>     echo *  password assigned to an admin-level user.  For *
>     echo *  server administration, use the WebLogic Server *
>     echo *  console at http:\\[hostname]:[port]\console    *
>     echo ***************************************************

>     "%JAVA_HOME%\bin\java" %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% %WLES_JAVA_OPTIONS%
>     -Dweblogic.Name=%SERVER_NAME%
>     -Dweblogic.ProductionModeEnabled=%PRODUCTION_MODE%
>     -Djava.security.policy="%WL_HOME%\server\lib\weblogic.policy" weblogic.Server

>     ENDLOCAL

# Defining Security Properties

You can use the `security.properties` file to set the necessary security properties. To set the security properties, create a `security.properties` file and put it in the WebLogic Server domain directory; for example:

>     BEA_HOME/user_projects/domains/mydomain

Include the information shown in Listing 4-2 in the `security.properties` file, where:

`wles.realm` is the value of the Configuration ID entered for Security Service Module using the Administration Console (see the Console Help).

`wles.default.realm` must be set to the same value as `wles.realm`.

Note: The `security.properties` file is not required if you add these parameters to Java Options.

Listing 4-2 Security.properties File

>     wles.realm=ConfigurationID
>     wles.default.realm=ConfigurationID

# Starting and Stopping Processes

After you install the Security Service Module, create the instance, and enroll it, you must start the necessary processes by running the appropriate batch or shell scripts. Before you start these processes, make sure that the Administration Server and all of its services are running.

For each machine, you must start the following processes:

- One Service Control Manager
- One Authorization and Role Mapping Engine (ARME) for each Security Service Module instance.

For instructions on how to start and stop the required processes, see Starting and Stopping Processes for Security Service Modules in the Administration and Deployment Guide.

# Additional Post-Installation Considerations

When using the Database Authentication provider, ASI Authorization provider and ASI Role Mapping provider, refer to the following sections for important information:

- Setting the Boot Login for WebLogic Server
- Creating a WebLogic Boot Policy
- Creating a WebLogic Console Policy
- Protecting Resources

## Setting the Boot Login for WebLogic Server

The WebLogic Server uses the login information contained in the `boot.properties` file to start the server. This file contains a `username` and `password` that must match a username and password in the configured authentication policy. The `boot.properties` file is located in the WebLogic Server domain directory on the machine on which the Security Service Module is installed, for example:

>     BEA_HOME/user_projects/domains/mydomain

If you used a username of `system` and a password of `weblogic`, then modify WebLogic Server `boot.properties` in the domain as follows:

`user = system`

`password = weblogic`

The next time you start the WebLogic Server, the username and password you specified are encrypted.

## Creating a WebLogic Boot Policy

Before you can use the ASI Authorization provider with the WebLogic Server, you need to configure a boot policy, and then distribute it to the WebLogic Server 8.1 Security Service Module. If you need instructions on how to perform any of these tasks, see the Console Help for details. You may also want to refer to the Policy Managers Guide for information on how the policy language is constructed and how it appears in the console.

To configure and distribute a boot policy, perform the following tasks:

- Creating the User Identity
- Creating Resources for WebLogic Server
- Grant Server Resource to Admin Role
- Grant Admin Role to WebLogic User/Group
- Binding the Resource to the ASI Authorization Provider
- Distributing the Policies to the Security Service Module

### Creating the User Identity

To create the user identity named `alesusers`, perform these steps:

1. Using the Administration Console, create an Identity directory called `alesusers`.

1. Open the Identity folder and click Identity.
2. Click New, in the Name text box, enter `alesusers`, and then click OK.

2. Within this directory, create a user named `system` and set the password for system to `weblogic`. Replace `system` and `weblogic` with the values used in `boot.properties` file.

1. Click Users, click New, enter `system`, and click OK.
2. Click Edit, click Set Password, enter the `weblogic`, and click OK.
3. Click OK.

### Creating Resources for WebLogic Server

To create resources for the defined user, `alesusers`, create the following resources below the resource called `policy`:

`wlsserver` as a bound application node.

`wlsserver/shared` as virtual

`wlsserver/shared/svr`

1. Click Resources and then click New.
2. In the Name box, type `wlsserver`, select Binding from the Type drop-down menu, and then click OK.
3. Select `wlsserver` and click Configure.
4. From the Type drop-down menu, select Binding Application, check Distribution Point, and then click OK.
5. Select `wlsserver`, click New, enter `shared` in the name box, and then click OK.
6. Select `shared`, click Configure, check Allow Virtual Resources, and then click OK.
7. Select `shared`, click New, enter `svr` in the name box, and then click OK.

### Grant Server Resource to Admin Role

Create the following policy:

>     grant(any, //app/policy/wlsserver/shared/svr, //role/Admin) if true;

1. Expand the Policy node in the left pane, and click Authorization Policies.
2. In the Authorization Policies page, click New.
3. In the Create Authorization Policy dialog page, select the Privileges tab, select `any` in the Select Privileges from Group list box, and then click Add.
4. Select the Resources tab, expand the `wlsserver` and `shared` nodes in the Child Resources list box, select svr, and then click Add.
5. Select the Policy Subjects tab, select `Admin` from the Roles List list box, click Add, and click OK.

### Grant Admin Role to WebLogic User/Group

Create the following role mapping policy:

>     grant(//role/Admin, //app/policy/wlsserver, //user/alesusers/system/)
>        if true;

1. Click Role Mapping Policies.
2. In the Role Mapping Policies page, click New.
3. In the Create Role Mapping Policy dialog page, select the Roles tab, select Admin from the Available Roles list box, and click Add.
4. Select the Resources tab, select `wlsserver` in the Child Resources list box, and click Add.
5. Select the Policy Subjects tab, select Users from the Select Policy Subjects From: drop-down menu, change the directory to `alesusers`, select `system` from the list box, click Add, and click OK.

### Binding the Resource to the ASI Authorization Provider

To bind the resource `//app/policy/wlsserver` to the ASI Authorization provider for this Security Service Module, perform the following steps:

1. Open the Security Configuration and Security Control Manager folders.
2. Open the Security Service Module folder and click Authorization.
3. The Authorization page appears.
4. Click Create a new ASI Authorization Provider.
5. The Edit ASI Authorization Provider page appears.
6. Enter a name for the provider in the Name text box, and then click Create.
7. Click the Details tab, set the Identity Directory to `alesusers`, set the Application Directory Parent to `//app/policy/wlsserver`.
8. Click Apply.
9. Click the Bindings tab and select the resource you want to bind to the provider from the Bind drop-down menu, and then click Bind.

### Distributing the Policies to the Security Service Module

Distribute the policies to the WebLogic Server v8.1 Security Service Module.

For information on how to distribute policies, see the Administration Console help system. Be sure to verify the results of the distribution.

## Creating a WebLogic Console Policy

Before you can login into the WebLogic Server Administration Console, you need to configure a console policy and then distribute it to the WebLogic Server 8.1 Security Service Module. This is needed if you want to access the WebLogic Server Administration Console.

To configure and distribute a WebLogic Server Administration Console policy, do the following on the AquaLogic Enterprise Security Administration Console:

1. Create the following resource:

>     //app/policy/wlsserver/console.

1. Click Resources. The Resources page appears.
2. Select `wlsserver`, click New, enter `console` in the name box, and then click OK.
3. Select `console`, click Configure, check Allow Virtual Resources, and then click OK.

2. Create the following authorization policy:

`grant(any, //app/policy/wlsserver/console, //role/Admin) if true;`

1. Click Authorization Policies.
2. In the Authorization Policies page, click New.
3. In the Create Authorization Policy dialog page, select the Privileges tab, click `any` in the Select Privileges from Group list box, and then click Add.
4. Select the Resources tab, expand `wlsserver` in the Child Resources list box, select `console`, and then click Add.
5. Select the Policy Subjects tab, select `Admin` from the Roles List list box, click Add, and then click OK.

3. Distribute the policy to the WebLogic Server 8.1 Security Service Module. For information on how to distribute policy, see the Administration Console's help system. Be sure to verify the results of the distribution.

## Protecting Resources

When you secure an EJB using a WebLogic Server 8.1 Security Service Module, you must follow these steps if you want to use the AquaLogic Enterprise Security providers instead of the default WebLogic providers.

1. Modify the EJB deployment descriptor (`ejb-jar.xml`) so that the assembly-descriptor does not have any method-permissions set to unchecked or excluded.

If either of these settings is present in the deployment descriptor, then the EJB container enforces them rather than calling into the security subsystem.

2. Set the following system property to true, indicating that the EJB container delegates other security checks to the security subsystem.

>     weblogic.security.fullyDelegateAuthorization=true

3. Add this line to the `WLES_JAVA_OPTIONS` in the `set-wls-env.sh` script.

# Protecting a Cluster of WebLogic Servers

If you want to protect a cluster of WebLogic Servers using AquaLogic Enterprise Security, you must make some addition changes to the security configuration and resource configuration. For information on how to protect cluster of WebLogic Servers, see the following topics:

Security Configuration

Resource Configuration

Policy Configuration

## Security Configuration

Figure 4-1 shows a Security Service Module configuration named `myrealm`, located under a Service Control Manager named `adminconfig` in the AquaLogic Enterprise Security Administration Console. Your actual Security Service Module configuration will vary from this example based on the needs of your WebLogic domain.

Figure 4-1 Service Control Manager Configuration

Figure 4-2 shows a configuration for a cluster of four WebLogic Servers: one administration server (`adm`) and three managed servers (`svr1`, `svr2`, `svr3`), with one Security Service Module instance for each server. The Service Control Manager on both machines must use the same Configuration Name (`adminconfig`). Each Security Service Module must have a unique Instance Name and Port number per machine, but always shares a common Configuration ID (`myrealm`) across all machines. Thus, each server uses the same security provider configuration and receives the same policy.

Figure 4-2 WebLogic Server Clusters

## Resource Configuration

You must also create the following two resources shown in Figure 4-3, setting them both to virtual.

The `myrealm/wl_management_internal1` resource is accessed on the cluster's administration server by the WebLogic Admin Console to view WebLogic Server related log files.

The `myrealm/wl_management_internal2` resource is accessed on the cluster's administration server by a managed server during bootstrap and file distribution operations.

The `myrealm/bea_wls_internal` is accessed when one managed server is synchronizing with another managed server.

The `myrealm/wl_management_internal1`, `myrealm/wl_management_internal2` and `myrealm/bea_wls_internal` resources must be configured to allow virtual resources.

Figure 4-3 Resources for Managing WebLogic Server Clusters

## Policy Configuration

You must create the policy listed in Table 4-1. Also, ensure that there is a role policy that maps the `Everyone` role to the group `allusers` in your identity directory.

Table 4-1 Policy Configuration

Privileges | Resources | Policy Subjects | Conditions
--- | --- | --- | ---
`any` | `myrealm/bea_wls_internal` | `role/Everyone` | none
`any` | `myrealm/wl_management_internal1, myrealm/wl_management_internal2` | `role/Everyone` | none

# What's Next?

You have completed the installation and configuration of the WebLogic Server 8.1 Security Service Module. Your Security Administrator can now configure additional security services using the security providers for your Security Service Module, through the AquaLogic Enterprise Security Administration Console. If you configured the providers as part of the post install, you can now make changes to your configuration using the console.

Before you continue to configure security services, read the information on security configuration in the Administration Console help. This section provides additional information on how to configure the Service Control Manager, the Security Service Module, and the providers, and then deploy your changes.