Installing the Java Security Service Module

Post Installation Tasks

This section covers tasks that you must perform after completing the installation.

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

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

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

To configure enrollment in demo mode, perform the following steps:

Open a command window and go to BEA_HOME/ales21-scm/bin.

Run the following script:

enrolltool demo
The Enrollment menu appears.

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)

Select the domain you want to use and press <ENTER>.

Enter the admin username and password. This is the username and password of the security administrator that is enrolling the SCM. This is administrator on the Administration Server, not the SSM.

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 Application, you must use the adminconfig SCM, which was configured for you when you installed the Administration Application.

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, 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 a Java Security Service Module

Configure a SSM with the security providers that you require for the Java 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 Java Security Service Module supports the following types of security providers:

Authentication provider
Authorization provider
Auditing provider
Credential mapping provider
Identity asserter
Role mapping provider

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

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.

Click Create a New Security Service Module Configuration. The Edit Security Service Module Configuration page displays.

In the Configuration ID text box, enter an identity for the SSM (for example, java_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.

Click the Providers tab and create the desired providers.

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

Click on the Binding tab and bind the Java SSM configuration to the SCM.

Creating an Instance of the Java Security Service Module

Before starting a Java Security Service Module (SSM), you must create a named instance of the SSM using the Instance Wizard.

To create an instance of the Java Security Service Module:

Start the Java Instance Wizard:

On Widows, click Start>Programs>BEA AquaLogic Enterprise Security>Security Service Module>Java Security Service Module>Create New Instance.

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

Note: If you are not using X-windows, the installer detects whether X-windows is available and, if it is not, switches to Console Mode automatically.

Note: use a console based installer.

In the Instance Name text box, enter the name to assign to this instance. The name must be unique for Java SSMs on this machine.

In the Authorization Engine Port text box, enter the port number for the Authorization and Role Mapping engine to use.

In the Configuration ID text box, enter the configuration identifier to use with this SSM instance.

From the Enterprise Domain drop-down box, select the domain to which the instance belongs.

Click Next.

In the Location of the Instance text box, enter the location for this instance. The default instance is located within the installation directory of the Security Service Module.

Click Next.

Click Done when the instance wizard completes.

Enrolling the Instance of the Security Service Module

You must have the Administration Application services 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:

Open a command window and go to the Security Service Module instance /adm directory: BEA_HOME/ales21-ssm/java-ssm/instance/instancename/adm, where instancename is the name you assigned to the instance when you created it.

Run the following script:

enroll demo

Enter the admin username and password. This is the username and password of the Security Administrator doing the enrollment.

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

Example: How to Run a Java SSM

AquaLogic Enterprise Server includes an example Java SSM client you can use for testing purposes. The example code and the instructions can be found under the BEA_HOME/ales21-admin/examples/JavaAPIExample folder. The example is present only if you have installed ALES 2.1 SP1 CP2. Instructions for running the Java SSM example are included in the README file.

Create and enroll a Java SSM instance named jssm, with properties matching those in BEA_HOME/ales21-admin/examples/JavaAPIExample/build.properties. See Creating an Instance of the Java Security Service Module and Enrolling the Instance of the Security Service Module.

Edit set-env.bat/.sh to include the correct BEA_HOME and JAVA_HOME system variables for your installation. Run set-env.bat/.sh to set the system variables. This step is necessary because the client build script is dependant on libraries and executables located under the BEA_HOME folder. The same is true for the compiled Java client.

Execute the ant dist config command. This script compiles the source code and creates the build folder. This folder contains all necessary runtime files.

Execute the ant load command. This action creates an SSM configuration and configures its providers, creates example resources and rules, then it attaches the SSM to the SCM. After this step has been successfully executed, you should be able to see the newly created SSM in the ALES Administration Console.

Start the Java SSM ARME before the client is launched. See Starting and Stopping Processes.

Run the run.bat/.sh script to start the Java SSM example client.

After you start the Java SSM example client, respond to the prompts that are displayed. Enter:

a user credential,
a resource, and
an action.

The example code attempts to authenticate the user using credentials you supplied as the input. Then it checks the privileges to perform the action against the resource.

Java SSM Example Code Structure

The code structure of the Java SSM example can be logically divided into the following steps:

Read the name of the policy domain that is set in the build/config/security.properties configuration file.

Initialize the Java SSM by:

creating an application configuration,

loading additional authority definitions, and

getting the SecurityRuntime instance.

Get the PolicyDomain instance by calling SecurityRuntime.getPolicyDomain(name).

Get the AuthenticationService instance by calling PolicyDomain.getService(ServiceType.AUTHENTICATION).

Get the AuthorizationService instance by calling PolicyDomain.getService(ServiceType.AUTHORIZATION).

Authenticate the user using the AuthenticationService and the provided username and password.

Create the RuntimeResource instance by supplying the resource name and the authority name.

Create the RuntimeAction instance by supplying the action name and the authority name.

Call isAccessAllowed method on the AuthorizationService.

For more information about how to develop secure Java applications using Java SSM, see Programming Security for Java Applications.

What's Next

You have completed the installation and configuration of the Java Security Service Module. Your Security Administrator can now configure your security services using the security providers for your Security Service Module, through the Administration Console.

Before you begin to configure security services, you should read the information on security configuration and administration in the Administration Console online help. Descriptions of how to configure the Service Control Manager, the Security Service Module, and the providers, and then deploy your changes are provided there.