Skip navigation.
Downloads | Product Documentation | Support

Installing Web Server and Web Services Security Service Modules

# Post Installation Tasks

This section covers tasks that you must perform after completing the installation of the Web Server Security Service Module.

Note: Some of the procedures described here require basic knowledge of 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 Security Service Module and the Administration Server.

- Enrolling the Service Control Manager
- Configuring a Service Control Manager
- Configuring and Binding the Web Services Security Service Module
- Distributing the Security Configuration
- Creating an Instance of the Web Services Security Service Module
- Creating an Instance of the Web Server Security Service Module
- Enrolling the Instance of the Web Services Security Service Module
- Starting the Web Services SSM
- What's Next

# Enrolling the Service Control Manager

This section describes how to enroll the Service Control Manager (SCM). Each machine on which you install a Security Service Module (SSM) must have one (and only one) enrolled SCM.

Note: If you installed the SSM on the same machine as the Administration Application, you do not have to perform this task. You must use the `adminconfig` SCM, which was enrolled and configured for you when you installed the Administration Application.

To enroll the SCM, perform the following steps:

1. Open a command window and go to the Service Control Manager`\bin` directory (`BEA_HOME``\ales21-scm\bin`).
2. Run the following script:

`enrolltool demo`

where `demo` designates the demonstration digital certificate.

The Enrollment menu appears.

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

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.

Note: If you installed the SSM on the same machine as the Administration Application, you do not have to perform this task. You must use the `adminconfig` SCM, which was enrolled and configured for you when you installed the Administration Application.

Note: 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 Application Console Help and use the AquaLogic Enterprise Security Administration Console.

# Configuring and Binding the Web Services Security Service Module

You must configure a Web Services SSM with the necessary security providers. At a minimum, a Web Services SSM security configuration must include the following providers:

o ASI Adjudication provider

o Log4j Auditing provider

o Database Authentication provider

o ALES Identity Assertion provider

o ASI Authorization provider

o ALES Credential Mapping provider

o ASI Role Mapping provider

To configure these providers and bind the SSM 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 configuration identity for the SSM (for example, `webservice_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, refer to Table 4-1 and create each of the required providers as described there.

Table 4-1 Web Services Security Configuration

Security Provider | Configuration Settings
--- | ---
ASI Adjudication Provider | On the General tab, accept the default settings, and click Create.
Log4j Auditor | On the General tab, accept the default settings, and click Create. At runtime, the auditing messages are directed to the `secure_audit.log` located in this directory: `BEA_HOME``\ales21-ssm\webservice-ssm\instance\<instance_name>\log` Note: To change the auditing level, select the Details tab and change the Severity level and/or the context settings for each type of event.
Database Authentication Provider | On the General tab, name the provider, accept the default settings, and click Create. Select the Details tab, and set configuration setting as follows: Leave Identity Scope set to `asi`. Note: The Identity Scope is left as the default value of `ales` because `ales` is used later in the sample Web Server SSM policy configuration instructions provided in Configuring and Deploying Policy for the Web Server SSM. In a normal configuration you set the Identity Scope to whatever identity you decide to use when you design your resource policy. Enter the database username and password in the text boxes provided and click Apply. Fill in the JDBC Driver Class Name and JDBC Connection URL text boxes, and click Apply. For these values, use the same settings as the Database Authenticator for the `alesadmin` SSM that was pre-configured for the Administration Server. To view those settings, in the left pane, expand the `adminconfig` SCM, expand the `alesadmin` SSM, expand Authentication, select the Database Authenticator, and select the Details tab.
ALES Identity Assertion Provider | On the General tab, name the provider, accept the default settings, and click Create. Normally, you would select the Details tab, fill in detail settings, and click Apply. However, you will be directed to fill in the detail settings later in the sample Web Server SSM policy configuration instructions provided in Configuring and Deploying Policy for the Web Server SSM.
ASI Authorization Provider | On the General tab, accept the default settings, and click Create. On the Details tab, leave the Identity Directory set to `ales`, and click Apply. Note: The Identity Directory is not changed because `ales` is used later in the sample Web Server SSM policy configuration instructions provided in Configuring and Deploying Policy for the Web Server SSM. In a normal configuration you set the Identity Directory to whatever identity you decide to use when you design your resource policy.
ALES Credential Mapping Provider | On the General tab, name the provider, accept the default settings, and click Create. Normally, you would select the Details tab, fill in detail settings, and click Apply. However, you will be directed to fill in the detail settings later in the sample Web Server SSM policy configuration instructions provided in Configuring and Deploying Policy for the Web Server SSM.
ASI Role Mapping Provider | On the General tab, accept the default settings, and click Create. On the Details tab, leave the Identity Directory set to `ales`, and click Apply. Note: The Identity Directory is not changed because `ales` is used later in the sample Web Server SSM policy configuration instructions provided in Configuring and Deploying Policy for the Web Server SSM. In a normal configuration you set the Identity Directory to whatever identity you decide to use when you design your resource policy.

5. Click the SCM that you previously configured for this SSM. The Edit a Service Control Manager Configuration page displays.

Note: If you installed the SSM on the same machine as the Administration Application, click the adminconfig SCM.

6. Click the Bindings tab and click Bind to bind the new Web Services SSM configuration to the SCM.

# Distributing the Security Configuration

Using the Administration Console, distribute the security configuration to the Web Services SSM.

For information on how to distribute the security configuration, access the Administration Console Help, click Deployment in the left pane, and click Distributing Configuration. The distribution procedures appear in the right pane. Be sure to verify the results of the distribution.

Note: At this point, because you have not yet created an instance of the Web Services SSM and enrolled it with the SCM, you are only distributing the security configuration to the SCM. Your next task will be to create an instance of the Web Services SSM.

# Creating an Instance of the Web Services Security Service Module

Before you can use a Web Services Security Service Module (SSM), you must first use the Instance Wizard to create an instance of it.

Note: You can create more than one instance of Web Services SSM on a single machine, but each instance must run in a separate process.

To create an instance of a Web Services SSM, perform the following steps:

1. Start the Web Services Instance Wizard:

On Widows, make the following selection:

- Click Start>Programs>BEA AquaLogic Enterprise Security>Security Service Module>Web Service Security Service Module>Create New Instance.

On Unix, if you are using X-windows, go to `BEA_HOME``/ales21-ssm/webservice-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 Web Services SSMs on this machine.
3. In the Authorization Engine port text box, enter the port number to use for the Authorization and Role Mapping engine. The default port number is 8000.
4. In the Configuration ID text box, enter the configuration identifier to use with this SSM instance. Use the same Configuration ID that you entered on the General tab when you created the Security Service Module Configuration in the Administration Console as instructed in Configuring and Binding the Web Services Security Service Module. These identifiers must match. The Administration Application uses this identifier to distribute security configuration and policy information to this SSM instance.
5. From the Enterprise domain drop-down box, select the domain to which to assign this instance (for example, `asi)`, and click Next.
6. In the WebService port number text box, enter the port number, and click Next. The default port number is 9000.
7. In the Location text box, enter the directory location for this instance, and click Next. By default, the instance is located within the installation directory of the Web Services SSM.
8. Click Done when the instance wizard completes.

# Creating an Instance of the Web Server Security Service Module

Before you can use a Web Server Security Service Module (SSM), you must first use the Instance Wizard to create an instance of it.

Note: You can only create one instance of Web Server SSM on a single machine.

To create an instance of a Web Server SSM, perform the following steps:

1. Start the Web Server Instance Wizard:

On Widows, make the following selection:

- Click Start>Programs>BEA AquaLogic Enterprise Security>Security Service Module>IIS Server Security Service Module>Create New Instance.

On Unix, if you are using X-windows, go to `BEA_HOME``/ales21-ssm/apache-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 Web Server SSMs on this machine.
3. In the SSM WS port text box, enter the same port number that you entered for the WebService port number when you created the instance of the Web Services SSM, and click Next. The default port number is 9000.
4. In the SSM WS Config ID text box, enter the configuration identifier to use with this SSM instance. Use the same Configuration ID that you entered when you created an instance of the Web Services SSM. These identifiers must match.
5. From the Enterprise domain drop-down box, select the domain to which to assign this instance (for example, `asi)`, and click Next.
6. In the Location text box, enter the directory location for this instance, and click Next. By default, the instance is located within the installation directory of the Web Server SSM.
7. Click Done when the instance wizard completes.

Note: IMPORTANT: When you create an instance of the Apache Web Server SSM, you must also add the Apache user to the `asiusers` group on the machine running the Apache Web Server SSM; otherwise, the Administration Application will not have the permissions required to access the Apache Web Server SSM instance and deploy the security policy and the security configuration.

Note: When the InstanceWizard creates an instance of the IIS Web Server SSM, it adds the information listed in Table 4-2 to the following location in the Microsoft Windows Registry:

>     HKEY_LOCAL_MACHINE\SOFTWARE\BEA Systems\ALES\IIS Module\2.1

Table 4-2 Registry Configuration Data

Value Name | Type | Description/Setting
--- | --- | ---
`ALES_HTTP_SERVER` | String | The configuration directory of the Web Server SSM.
`ALES_LOG_LEVEL` | DWORD | By default, the log level is set to `2` (INFORMATIONAL).

# Enrolling the Instance of the Web Services Security Service Module

You must have the AquaLogic Enterprise Security Administration Application running prior to enrolling the Web Services Security Service Module (SSM).

To enroll the Web Services Security Service Module, perform the following steps:

1. Open a command window and go to the `\adm` directory for the instance of the SSM. For example, `BEA_HOME\ales21-ssm\webservice-ssm\instance\<``instancename``>\adm`, where `instancename` is the name you assigned to the SSM instance when you created it.
2. Run the following script:

`enroll demo`

where `demo` is the demonstration digital certificate.

Note: While you may use the demonstration digital certificate to enroll the SSM in a development environment, for security reasons you should never use it in a production environment.

3. Enter admin username and password. This is the username and password of the security administrator that is enrolling this SSM.
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.

# Starting the Web Services SSM

Before proceeding to What's Next, start the Web Service SSM.

To start the Web Service SSM, do the following:

- On Windows, perform the following steps:

1. Click Start>Programs>BEA AquaLogic Enterprise Security>Security Service Module>Web Service Security Service Module>instancename>Start ARME (console mode). The Start ARME command windows appears and indicates that the ARME started.
2. Click Start>Programs>BEA AquaLogic Enterprise Security>Security Service Module>Web Service Security Service Module>instancename>Start Web Service (console mode). The Start Web Service command windows appears and indicates that the Web Service started.

- On Unix, perform the following steps:

1. Open a command prompt, cd to `BEA_HOME/ales21-ssm/webservice-ssm/instance/<``instancename``>/bin` and enter `WLESarme.sh start`, where `<instancename>` is the name of the Web Services SSM.
2. Open another command prompt, cd to `BEA_HOME/ales21-ssm/webservice-ssm/instance/<``instancename``>/bin` and enter `WLESws.sh start`, where `<instancename>` is the name of the Web Services SSM.

# What's Next

You have completed the post-installation tasks for the Web Services and Web Server SSMs.

For additional configuration tasks, do one of the following:

- If you installed the Web Services SSM and a Web Server SSM (either the IIS Web Server SSM or the Apache Web Server SSM, go to Configuring the Web Server SSM and perform the configuration procedures provided there.
- If you installed the Web Services SSM only, go the Configuring the Web Services SSM and perform the configuration procedures provided there.