Skip navigation.
Downloads | Product Documentation | Support

Administration Application Guide

# Security Configuration

# Overview

This topic describes how to use security providers to implement your security policies and how to configure these providers. Before you can configure providers, you must install the Security Service Module, instantiate the providers for that module, and then assign a Security Service Module configuration. You must also configure the Service Control Manager. For a step-by-step description of the process, see Security Configuration.

# Security Configuration

You must follow these steps to initialize a new Security Service Module and configure your providers.

1. Configuring a Service Control Manager
2. Configuring a Security Service Module
3. Binding a Security Service Module to a Service Control Manager
4. Configuring Security Providers
5. Distributing Configuration

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Understanding the Service Control Manager

The Service Control Manager is an essential component for remote administration of the BEA WebLogic Enterprise Security services. The Administration Application uses the Service Control Manager to distribute Security Service Module configurations throughout the enterprise-to all modules embedded in applications, application servers, and web servers.

To facilitate the management of a potentially large number of distributed Security Service Modules, the Administration Application uses a provisioning mechanism to deploy configuration data to each server containing a Service Control Manager, which in turn passes that configuration data to each module it controls. The Administration Application can deploy configurations to many different machines, but each machine has only one Service Control Manager. When you start each module, the module passes its Configuration ID to the Service Control Manager instance running on the same machine, and thereafter, the Service Control Manager assumes management of the module.

The Service Control Manager receives and stores configuration updates, both full and incremental, initiated by the Administration Application. Each module receives its initial configuration data from the Service Control Manager instance running on the same machine. When a configuration change relevant to a module is made by the Administration Application, it is provisioned to the Service Control Manager through the Policy Distributor. The provisioning mechanism ensures that only the configuration data absolutely required by a Service Control Manager is provisioned to that module. Likewise, the Service Control Manager ensures that only the configuration data absolutely required by a managed module is made available to that module. For a description of the BEA WebLogic Enterprise Security architecture, see the Introduction to WebLogic Enterprise Security.

## Configuring a Service Control Manager

A Service Control Manager maintains the configuration data that each Security Service Module retrieves. It receives this information from the Administration Application whenever you distribute the configuration changes.

Before you begin, the Service Control Manager you want to initialize must be installed, and you must know the Configuration Name and Configuration ID used when it was installed. If you specify this incorrectly in the console, the Service Control Manager will not be able to receive any configuration data.

To configure a Service Control Manager:

1. Open the Security Configuration folder.
2. Open the Service Control Managers folder, and click Service Control Manager.

The Service Control Managers page displays the General tab, containing the name of each Service Control Manager configuration available.

3. Do one of the following:

- To create a new one, click Configure a new Service Control Manager, enter a name for the configuration, and then click Create.

The Name you assign must match the name of the Service Control Manager that you entered during the installation of a Security Service Module. The Administration Application distributes the configuration changes to Service Control Manager for all Security Service Module configurations that are bound to that specific Service Control Manager. If there is a mismatch in the names of the Service Control Manager or if there is a mismatch in the Configuration IDs, then the Service Control Manager will not receive the configuration changes for the Security Service Module.

Note: You must bind each Security Service Module configuration to a Service Control Manager configuration before you can distribute it.

- To bind the Service Control Manager to a Security Service Module, click the Binding tab and select the Configuration Name.

The Service Control Managers page displays the name of the Service Control Manager configuration in the configuration table. Additionally, the name of the new Service Control Manager is added as a folder under the Service Control Managers folder in the navigation pane.

Note: You must distribute the configuration before it becomes available to the Security Service Module. For instructions on distribution configuration, see Distributing Configuration.

## Understanding the Security Service Module

BEA WebLogic Enterprise Security supports a variety of Security Service Modules that you integrate with the security framework and provision as needed. You may instantiate and configure as many modules as you need to secure the enterprise, and manage them directly through a central Administration Application. The distributed nature of the architecture allows you to configure, manage and distribute configuration and policy throughout the enterprise.

BEA WebLogic Enterprise Security provides the following types of Security Service Modules:

- WebLogic Server 8.1 Security Service Module
- Internet Information Services (IIS) Web Server Security Service Module
- Apache Web Server Security Service Module
- Web Services Security Service Module
- Java Security Service Module

Configuration data for each module is maintained within each machine and handled by a Service Control Manager. One additional benefit of this architecture is that even if the Administration Server goes down (either for maintenance or failure), there is no impact on the applications or security services provided by those modules. For a complete description of the BEA WebLogic Enterprise Security architecture, see the see the Introduction to WebLogic Enterprise Security.

## Configuring a Security Service Module

Before you can use a new Security Service Module, you must first initialize it through the Administration Console. Initialization of a Security Service Module involves:

- Defining the set of providers used by the Security Service Module
- Binding the Security Service Module configuration to a Service Control Manager configuration
- Distributing the configuration data to all Security Service Modules with the name to which the Security Service Module configuration is bound.

After you initialize the module and distribute the configuration, the Security Service Module can be started and the providers initialized with the specified configuration. You can have multiple Security Service Modules managed by a single Service Control Manager.

Note: Before you begin, the module you want to initialize must be installed and you must know the Configuration ID and Configuration Name used when the module was installed. If you enter this information incorrectly in the console, the Security Service Module will not receive any configuration data or may receive the incorrect configuration. For a description of the BEA WebLogic Enterprise Security architecture, see the Introduction to WebLogic Enterprise Security.

To initialize a Security Service Module:

1. Open the Security Configuration folder.
2. Click Unbound Configurations.

The Unbound Security Service Module Configurations pages appears.

3. Click Create a new Security Service Module Configuration.

The Create a Security Service Module Configuration page appears.

4. On the General tab, in the Configuration ID text box, enter the identifier that was entered when this module was installed.
5. In the Description text box, enter a description for the Security Service Module configuration.
6. Click Create.

The Edit Security Service Module Configuration page displays the Configuration ID and Description you entered and a new Security Service Module configuration appears under the Unbound Configurations folder in the navigation pane.

7. Click the Providers tab.

The Providers page displays six tabs, one for each type of provider available for configuration. Table 9-1 lists the name of each provider along with a description of each one.

Table 9-1 Security Providers

Provider Type | Provider Name | Description
--- | --- | ---
Adjudicators | ASI Adjudication Provider | Provides an authorization decision based on results from one or more authorization providers.
Auditors | Log4j Audit Channel Provider | Processes audit event data and stores it using the Apache Log4j logging libraries.
| Resource Deployment Audit Provider | Publishes WebLogic resources to the Administration Application.
Authenticators and Identity Asserters | WebLogic Authentication Provider | Supports authentication through an embedded LDAP Directory for WebLogic Server.
| ALES Identity Asserter Provider | Supports web server authentication and Web single sign-on between web server Security Service Modules (SSMs) and also between web server SSMs and WebLogic Server 8.1 SSMs. Use this provider in conjunction with the ALES Credential Mapping provider.
| Database Authentication Provider | Supports authentication using a relational database.
| SAML Identity Assertion Provider | Supports identity assertion through Security Assertion Markup Language v1.0.
| Open LDAP Authentication Provider | Supports authentication based on Open LDAP.
| Active Directory Authentication Provider | Supports authentication based on Microsoft Active Directory.
| Windows NT Authentication Provider | Supports Microsoft Windows NT authentication.
| Netscape iPlanet Authentication Provider | Supports authentication based on the iPlanet LDAP.
| Novell Authentication Provider | Supports authentication based on Novell LDAP
| Single Pass Negotiate Identity Asserter | The Single Pass Negotiate Identity Assertion provider supports identity assertion using HTTP authentication tokens from the SPNEGO protocol. The provider supports the identity assertion using the Kerberos tokens contained within the SPNEGO token.
| X.509 Identity Assertion Provider | Supports identity assertion through an X.509 digital certificate, supporting ASN.1 encoding and decoding.
Authorizers | WebLogic Authorization Provider | Provides enforcement of authorization for the security policy in WebLogic Server. The Authorization Provider returns an access decision that determines which resources are protected and if a particular user is allowed access to a resource.
| ASI Authorization Provider | Provides enforcement of authorization for the security policy with which it is used. The ASI Authorization Provider returns an access decision that determines which resources are protected and if a particular user is allowed access to a resource.
Credential Mappers | WebLogic Credential Mapping Provider | Provides authentication credentials for a user (username and password) for single sign-on use into another application or resource.
| ALES Credential Mapping Provider | Provides authentication credentials for a user (a ALES authentication assertion) for passing to another web server application. Use this provider in conjunction with the ALES Identity Assertion provider.
| SAML Credential Mapping Provider | Provides authentication credentials for a user (a SAML authentication assertion) for passing to another application.
Role Mappers | ASI Role Mapping Provider | Provides assignment to roles based on the security policy with which it is used. The ASI Role Mapping provider returns a set or roles granted to a user on a protected resource.
| WebLogic Role Mapping Provider | Provides assignment to roles based on the security policy defined for use with WebLogic Server 8.1. The WebLogic Role Mapping Provider returns a set or roles granted to a user on a protected resource.

Note: If the current security configuration does not meet your requirements, you can change the configuration properties (as permitted) for each provider. Or, you can create a new provider as described in Developing Security Providers for BEA WebLogic Enterprise Security.

1. Configure each provider according to your needs.

Note: You may configure the desired providers now or do it later. If you are using WebLogic Enterprise Security with the WebLogic Portal product, you must use a WebLogic Role Mapping provider with a WebLogic Authorization provider for authorization.

For general information on how to configure a provider, see Configuring Security Providers.

2. Bind the service module to a Service Control Manager configuration as described in Binding a Security Service Module to a Service Control Manager.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Binding a Security Service Module to a Service Control Manager

Before you can use a Security Service Module, you must bind it to a Service Control Manager. You may have multiple modules of the same type or different types bound to the same Service Control Manager. Each module can have its own configuration with different providers and provider settings. To bind a configuration:

1. Open the Security Configuration folder.
2. Open the Service Control Managers folder, and click Service Control Manager.

The Service Control Manager page displays the name of each Service Control Manager Configuration available for binding.

3. From the Service Control Manager Configuration table, select the Service Control Manager to which you want to bind the Security Service Module.

The Edit a Service Control Manager Configuration page appears.

4. Click the Binding tab.
5. From the drop-down menu, select the Security Service Module, and then click Bind.

The Security Service Module configuration is added to the Configuration Name table.

## Unbinding a Security Service Module from a Service Control Manager

You can change the configuration of a Security Service Module, for example, if you want to change the configuration or Service Control Manager to which the module is bound. To unbind a Security Service Module from the Service Control Manager:

1. Open the Security Configuration folder.
2. Open the Service Control Managers folder, and click Service Control Manager.
3. Select the Service Control Manager from which to unbind the Security Service Module.

The Edit a Service Control Manager Configuration page appears.

4. Click the Binding tab.
5. Select the configuration to unbind, and then click the Unbind icon .

## Configuring Security Providers

When you configure a security provider, you assign values to the configuration properties for each provider. Each provider has at least two tabs: General and Details. The General tab displays the name of the provider, a description of what the provider is used for, and the version number. The Detail tab displays additional attributes that you can configure. Depending on the security provider you are configuring, there may be additional attributes available. Attributes vary depending on the provider you are configuring. Not all attributes are configurable.

Note: If you are using WebLogic Enterprise Security with the WebLogic Portal product, you must use a WebLogic Role Mapping provider with a WebLogic Authorization provider for authorization. For information on configuring the WebLogic providers, see Configuring a WebLogic Server Security Service Module.

- Configuring an Authentication Provider
- Configuring an ALES Identity Assertion Provider
- Configuring a SAML Identity Assertion Provider
- Configuring an X.509 Identity Assertion Provider
- Configuring a Single Pass Negotiate Identity Asserter
- Configuring an ASI Authorization Provider
- Configuring an ASI Role Mapping Provider
- Configuring an ASI Adjudication Provider
- Configuring an ALES Credential Mapping Provider
- Configuring a Database Credential Mapper
- Configuring a SAML Credential Mapping Provider
- Configuring a Log4j Audit Channel Provider
- Configuring a Resource Deployment Audit Provider

## Configuring an Authentication Provider

An Authentication Provider allows BEA WebLogic Enterprise Security to establish trust by validating a user. There must be at least one Authentication Provider in a Security Service Module configuration if it is required to perform authentication. The LDAP authentication providers are designed to access external LDAP stores.

The following authentication provider support is available: Open LDAP, Netscape iPlanet, Microsoft Active Directory and Novell NDS stores. You can also authenticate against a database or other kinds of repository, using the Database Authentication Provider or Microsoft Windows NT authentication.

Identity assertion involves establishing the client identity using client-supplied tokens that may exist outside of the request. Thus, the function of an identity assertion provider is to validate and map a token to a username by which a user can be validated. You can configure multiple identity assertion providers, but you only need one if you want to authenticate users. An identity assertion provider is used in conjunction with an authentication provider and, in the case of the ALES Identity Assertion provider, in conjunction with the ALES Credential Mapping provider.

The order in which the authentication providers are configured is the order in which each authentication provider is called. Therefore, the order in which the authentication and identity assertion providers are configured can affect the outcome of the authentication process. When one or more authentication providers are configured, the authentication provider tabs display key information about each one and allow you to control their order. Click the appropriate link to configure an Authentication Provider and an Identity Assertion Provider. If custom Authentication or Identity Assertion providers are available, you may be able to configure them as well. The ordering of the authentication providers can be changed at any time. For more information, see Changing the Order of Authentication Providers.

Note: The WebLogic Enterprise Security AuthenticationService API has identity assertion functionality to translate WebLogic subjects into `AuthenticIdentity` objects for enhanced compatibility with WebLogic Servers. You may use this functionality or provide a custom identity assertion provider to handle the assertion of WebLogic subjects. For more information on this topic, see the Programming Security for Java Applications and the Javadocs for the AuthenticationService API and the methods it supports.

To configure Authentication providers, see the following links:

- Configuring an Active Directory Authentication Provider
- Configuring a Novell LDAP Authentication Provider
- Configuring an iPlanet LDAP Authentication Provider
- Configuring a Windows NT Authentication Provider
- Configuring an Open LDAP Authentication Provider
- Configuring a Database Authentication Provider
- Configuring an ALES Identity Assertion Provider
- Configuring a SAML Identity Assertion Provider
- Configuring a Single Pass Negotiate Identity Asserter
- Configuring an X.509 Identity Assertion Provider
- Configuring the WebLogic Authentication Provider

## Changing the Order of Authentication Providers

The way you configure multiple authentication providers can affect the overall outcome of the authentication process, which is especially important for multi-part authentication. Authentication providers are called in the order in which they are configured. The Authentication providers table lists the providers in the order they were configured. The setting of the Authentication provider Control Flag attribute effects the outcome of the authentication process. For more information, see Setting the JAAS Control Flag.

To change the ordering of authentication providers:

1. Open the Security Configuration folder.
2. Open the Service Control Managers folder containing the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.
4. Open the Authentication folder, and click Authentication.

The Authentication page appears.

5. Click Re-order the Configured Authentication Providers.

The Edit Authentication Provider Order page appears.

6. Select the Authentication provider from the list of configured Authentication providers.
7. Use the arrow buttons to move the Authentication provider up or down in the list.
8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Setting the JAAS Control Flag

If a policy domain has multiple authentication providers configured, the Control Flag attribute (located on the General tab for the Edit Authenticator page) determines the user authentication requirements for each configured authentication provider. Additionally, the order in which the authentication providers are configured in the Administration Console is the order in which the authentication providers are called. You can change the order of the authentication providers at any time.

The values for the Control Flag attribute are:

- `REQUIRED`—The Authentication provider is always called and the user must always pass its authentication test.
- `REQUISITE`—If the user passes the authentication test of this Authentication provider, other providers are executed but can fail (except for authentication providers with the JAAS Control Flag set to `REQUIRED`).
- `SUFFICIENT`—If the user passes the authentication test of the Authentication provider, no other Authentication providers are executed (except Authentication providers with the JAAS Control Flag set to `REQUIRED`) because the user was sufficiently authenticated.
- `OPTIONAL`—The user is allowed to pass or fail the authentication test of this Authentication provider. However, if all Authentication providers configured in a security realm have the JAAS Control Flag set to `OPTIONAL`, the user must pass the authentication test of at least one of the configured providers.

Note: If you define multiple authentication providers, to boot the server, the user from which the server is booted must be defined as a user in all the authentication providers that have the Control Flag attribute set to `REQUISITE` or `REQUIRED`. For more information, see Changing the Order of Authentication Providers.

## Configuring an Open LDAP Authentication Provider

To configure an Open LDAP Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a New Open LDAP Authenticator.
- To change an existing provider, select the Open LDAP Authentication provider to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are using multiple authentication providers, define a value for the Control Flag attribute on the General tab.

7. Click the OpenLDAP tab and edit the settings as needed.
8. Click the Users tab and edit the settings as needed.
9. Click the Groups tab and edit the settings as needed.
10. Click the Membership tab and edit the settings as needed.
11. Click the Details tab and define any additional attributes.
12. Optionally, click the Failover tab and edit the settings as needed.
13. On each tab you change, click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Windows NT Authentication Provider

To configure the Windows NT Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new NT Authenticator.
- To change an existing provider, select the NT Authentication provider to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define any additional attributes.
8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring an Active Directory Authentication Provider

To configure for an Active Directory Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Active Directory Authenticator.
- To change an existing provider, select the Active Directory Authentication provider to configure.

6. If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
7. If you are using multiple authentication providers, define a value for the Control Flag attribute on the General tab. For more information, Setting the JAAS Control Flag.
8. Click the Active Directory tab and edit the settings as needed.
9. Click the Users tab and edit the settings as needed.
10. Click the Groups tab and edit the settings as needed.
11. Click the Membership tab and edit the settings as needed.
12. Click the Details tab and define any additional attributes.
13. Click the Failover tab and edit the settings as needed.
14. On each tab you change, click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring an iPlanet LDAP Authentication Provider

To configure a Netscape iPlanet LDAP Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new iPlanet Authenticator.
- To change an existing provider, select the iPlanet LDAP provider to configure.

6. If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.

If you are using multiple authentication providers, define a value for the Control Flag attribute on the General tab. For more information, Setting the JAAS Control Flag.

7. Click the iPlanet LDAP tab and edit the settings as needed.
8. Click the Users tab and edit the settings as needed.
9. Click the Groups tab and edit the settings as needed.
10. Click the Membership tab and edit the settings as needed.
11. Click the Details tab and define any additional attributes.
12. Click the Failover tab and edit the settings as needed.

For additional information on configuring failover for the LDAP provider, see Configuring Failover for LDAP Authentication Providers.

13. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring Failover for LDAP Authentication Providers

You can configure any of the LDAP providers with multiple LDAP servers and enable failover if one LDAP server is not available. To configure failover of the LDAP servers configured for an LDAP Authentication provider, perform the following steps:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication folder, click Authentication, and select the LDAP Authenticator you want to configure.
5. Click the Failover tab.
6. Check the Automatic Failover Enabled option to enable failover.
7. In the Backup Host text box, enter the name or IP address of the backup LDAP server. For example:

>     directory.knowledge.com:1050 people.catalog.com 199.254.1.2

8. In the Backup Port text box, enter the port number on which the backup LDAP server is listening.
9. To enable a secure connection when connecting to the backup LDAP server, check Backup SSL Enabled.
10. In the Backup Principal text box, enter the distinguished name (DN) of the LDAP user that is used by WebLogic Server to connect to the backup LDAP server.
11. In the Backup Credential and Confirm Backup Credential text boxes, enter the credential (generally a password) used to authenticate the backup LDAP user that is defined in the Principal attribute.
12. In the Primary Retry Interval text box, enter the length of the interval, in seconds, that the backup LDAP server uses before retrying the primary LDAP server.

This option specifies the number of seconds to delay when making concurrent attempts to connect to multiple servers.

13. Click Apply.
14. Click Details.
15. Set the Connection Timeout attribute.

Specify the maximum number of seconds to wait for the connection to the LDAP server to be established. If the attribute is set to 0, there is no maximum time limit and WebLogic Server waits until the TCP/IP layer times out to return a connection failure. This attribute may be set to a value over 60 seconds depending upon the configuration of TCP/IP.

16. Click Apply.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

Refer to Table 9-2 and Table 9-3 for two examples that describe what can occur when the LDAP attributes are set for LDAP failover. In the first example, WebLogic Server attempts to connect to `directory.knowledge.com`. After 10 seconds, the connect attempt times out and WebLogic Server attempts to connect to the next host specified in the Host attribute (`people.catalog.com`). WebLogic Server then uses `people.catalog.com` as the LDAP Server for this connection.

####

Table 9-2 Example 1: LDAP Attributes and Failover

LDAP Attribute | Value
--- | ---
Host | `directory.knowledge.com:1050` `people.catalog.com 199.254.1.2` The LDAP servers are working as follows: `directory.knowledge.com:1050` is down `people.catalog.com is up` `199.254.1.2` is up
Parallel Connect Delay | 0
Connect Timeout | 10

In the following example, WebLogic Server attempts to connect to `directory.knowledge.com`. After 1 second, the connect attempt times out and WebLogic Server tries to connect to the next host specified in the Host attribute (`people.catalog.com`) and `directory.knowledge.com` in parallel. If the connection to `people.catalog.com` succeeds, WebLogic Server uses `people.catalog.com` as the LDAP Server for this connection. WebLogic Server cancels the connection to `directory.knowledge.com` after the connection to `people.catalog.com` succeeds.

####

Table 9-3 Example 2: LDAP Attributes and Failover

LDAP Attribute | Value
Host | `directory.knowledge.com:1050 people.catalog.com 199.254.1.2` The LDAP servers are working as follows: `directory.knowledge.com:1050` is down `people.catalog.com` is up `199.254.1.2` is up
Parallel Connect Delay | 1
Connect Timeout | 10

## Configuring a Novell LDAP Authentication Provider

To configure a Novell LDAP Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Novell Authenticator.
- To change an existing provider, select the Novell Authentication provider to configure.

6. If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
7. If you are using multiple authentication providers, define a value for the Control Flag attribute on the General tab. For more information, Setting the JAAS Control Flag.
8. Click the Novell LDAP tab and edit the settings as needed.
9. Click the Users tab and edit the settings as needed.
10. Click the Groups tab and edit the settings as needed.
11. Click the Membership tab and edit the settings as needed.
12. Click the Details tab and define any additional attributes.
13. Click the Failover tab and edit the settings as needed.

For additional information on configuring failover for the LDAP provider, see Configuring Failover for LDAP Authentication Providers.

14. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring Failover for the Database Authentication Provider

If you have an authentication backup database store, you can configure the Failover tab to enable the failover capability. Database replication procedures are provided to create a replica of the metadirectory (both primary and backup). For additional information, see Failover and System Reliability.

To configure a Database Authentication provider for failover:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the provider you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Select the Database Authentication provider to configure.
6. Click the Failover tab.
7. Check Enable Automatic Failover.

A check in the attribute Enable Automatic Failover enables the failover capability. When enabled, the provider connects to backup database when the primary database is unavailable.

8. In the Primary Retry Interval text box, enter the value is in seconds to wait before checking the primary pool (for the purpose of failing back to the original source).

The provider retries the primary database connection to the primary database when the period of time as set in Primary Retry Interval is reached.

9. In the Backup Database URL text box, type the name of the URL assigned to the backup database when you configured the backup metadirectory.

The backup database must be of the same type as the primary (Oracle or Sybase), because the backup connection uses the same database JDBC driver. The backup connection is specified by the Backup Database URL.

10. In the Backup Database User Name text box, type the user name required to access the backup metadirectory.

In many case, the Backup Database User Name is the same as user name for the primary database. If it is different, you or your DBA need to make sure that this user has read access to the tables specified in the three SQL queries on the Details tab.

11. In the Backup Database Password and Confirm Backup Database Password text boxes, type the password required to access the backup metadirectory.
12. In the Backup Database Properties text box, enter any `NAME=VALUE` properties to use when obtaining the JDBC connection to the backup database.
13. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Database Authentication Provider

You can configure a Database Authentication provider by configuring a database, including the policy database as the source of the authentication data.

To configure a Database Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Managers folder that contains the Security Service Module whose provider you want to configure or change, and click Service Control Manager.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Database Authenticator.
- To change an existing provider, select the Database Authentication provider to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. The Control Flag attribute determines the order of execution. If you are using multiple authentication providers, define a value for the Control Flag attribute on the General tab. For more information, see Setting the JAAS Control Flag.
8. Click the Details tab and define any additional attributes.

For both Oracle or Sybase, set the `DatabaseUserLogin` and `DatabaseUserPassword` configuration attributes to a valid database login for your database with read access to the tables that involves the authentication process.

The JDBC configuration is different depending on which database your system is configured to use and which type of JDBC driver you want to configure. For details on the Oracle setup, see Oracle Database Configuration. For details on the Sybase setup, see Sybase Database Configuration.

9. Optionally, to configure database failover, click the Failover tab and define any additional attributes.

For additional information, see Configuring Failover for the Database Authentication Provider.

10. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Oracle Database Configuration

To configure Oracle, you must know the hostname of the database server, the port number and Oracle SID to which to connect. Each Oracle service is identified by a global database ID or SID. An Oracle system identifier or SID is a unique identifier for a database or a unique identifier for a node within an Oracle Parallel Server Database. From the client perspective, the database service names is the Local Net Service Name For the Security Service Module to use Oracle OCI client, the Oracle client (OCI library) must be installed and configured in the same machine as the security Service Module.

The following setting is the default value for an Oracle configuration:

>     JDBCDriverClassName = oracle.jdbc.driver.OracleDriver

Oracle Thin Client (Type IV)

>     JDBCConnectionUrl = jdbc:oracle:thin:@<namehostname or IP address>:<port>:<sid>

Oracle OCI Client (Type II)

>     JDBCConnectionUrl = jdbc:oracle:oci8:@<database service name>

Note: For best performance, BEA recommends you use the native (Type II) database driver configuration. For more information on database connection configuration, please refer to the documentation specific to your database.

## Sybase Database Configuration

To configure Sybase, you must know the hostname of the database server and the port number to which to connect. The following setting is the default value for a Sybase configuration. If the <`database name`> is not specified, the default database for `DatabaseUserLogin` is used:

>     JDBCDriverClassName = com.sybase.jdbc2.jdbc.SybDriver

Sybase Thin Client (Type IV)

>     JDBCConnectionUrl = jdbc:sybase:Tds:<hostname or IP address>:<port>

or

>     JDBCConnectionUrl = jdbc:sybase:Tds:<hostname or IP address>:<port>/<database name>

The `JDBC Connection Properties` allows you to configure additional properties specific to your database server. These include SSL connection properties or other parameters as specified in your database documentation. You must enter parameters as a comma-delimited list of `NAME=VALUE` pairs.

Use the default values`` for the `ConnectionPoolCapacity` and `ConnectionPoolTimeout` configuration attributes or set them to meet your own requirements. You may want to increase the `ConnectionPoolCapacity` value to equal the number of threads running in your server.

The `VerifyUserForIdentityAssertion` attribute is not required unless you are using identity assertions and want to validate those users in the database.

The `AddGroupsFromIdentityAssertion` attribute enables that the groups obtained from identity assertion provider be added to the authenticated user.

The `AddGroupsFromLocalDBMS` attribute enables that the groups retrieved from this authentication database using the `SQLQueryToRetrieveGroups` be added to the authenticated user.

## Specifying SQL Query Strings and Provider Extensions

Configure your SQL query strings to correspond to the database schema for your authentication tables. The user and group name format and password hashing algorithm require the provider extension class be consistent with the query. For additional information, see Provider Extensions.

Metadirectory Configuration

If you want to configure the provider to authenticate against the metadirectory, use the following settings:

Note: For the SQL query strings, prefix each table reference with the schema owner. If the login id used defaults to the correct schema owner, then this attribute is optional.

SQL Query to Verify User `(SQLQueryToVerifyUser)`

>     select userid from <schema owner>.adminuser where status = 'A' and userid = ?

SQL Query to Retrieve Password `(SQLQueryToRetrievePassword)`

>     select password from <schema owner>.adminuser where status = 'A' and userid = ?

SQL Query to Retrieve Groups `(SQLQueryToRetrieveGroups)`

>     SELECT r.qualified FROM <schema owner>.subject_curr r, <schema owner>.sgrpmemberexp_curr rm, <schema owner>.subject_curr m WHERE m.qualified = ? AND m.id = rm.member_id AND rm.sgrp_id = r.id AND r.subj_type = 'R'

Each query takes single input parameter. The question mark (?) is the place holder for an input parameter and it takes the formatted user name. In the metadirectory, the formatted user name contains a qualifier prefix, the `IdentityScope`, and the user id.

The `IdentityScope` attribute is required and must specify the correct directory containing the users you want to authenticate. Directory is a scoping term in the metadirectory. You cannot authenticate through multiple directories using a single Database Authentication provider; you can specify one and only one directory for this provider.

Note: When using the Database Authentication Provider with the ASI Authorization and ASI Role Mapping providers, the `IdentityScope` must match the `IdentityDirectory` set in the ASI Authorization and ASI Role Mapping providers.

The user password is stored in the metadirectory by hashing the clear text using SHA1 hashing algorithm. Together, with the specific user and group name format, you need to specify:

>     com.bea.security.providers.authentication.dbms.DefaultDBMSPluginImpl

as the value for the `AuthenticationPluginClass` attribute.

You can set the `GroupMembershipSearching` attribute to `limited` or `unlimited` and `MaxGroupMembershipSearchLevel` to any number. These two attributes have no effect on the metadirectory, because the `SQLQueryToRetrieveGroups` retrieves all groups of all levels for the authenticated user.

Other Database Stores

When configuring other database stores, you are required to implement your own authentication plug-in class, since the password in your store may be hashed differently, or the password may be in clear text and user/group name is not formatted the same way. The `IdentityScope` attribute is optional and only required if using a database authentication plug-in that recognizes scope. It is very easy to implement your own plug-in class. For additional information, see Provider Extensions.

Note: When using the Database Authentication Provider with the ASI Authorization and ASI Role Mapping providers, the `IdentityScope` must match the `IdentityDirectory` set in the ASI Authorization and ASI Role Mapping providers.

The `AuthenticationPluginClass` attribute should be set to the Java class name for your plug-in implementation. The `IdentityScope` attribute should be set to the value that your plug-in understands.

The authentication provider uses compiled JDBC statements based on the specified SQL query strings. All three query strings are populated with the authenticating user identifier at runtime. To specify where in the string to populate the id, use the question mark (?) symbol. Here is a sample SQL query:

>     SELECT password FROM Principals WHERE principal = ?

SQL queries for the Database Authentication Provider only accept a single input parameter, where the question mark (?) place holder is for the encrypted password. This parameter is the formatted user name performed in your plug-in implementation class. A query requiring multiple input parameters or no input parameters results in a runtime error and users are not authenticated. Your database administrator can assist you in determining the correct SQL syntax for your database.

Each query should return only one column of data in the `SELECT` statement. `SQLQueryToVerifyUser` returns a matching user name, `SQLQueryToRetrievePassword` returns a password, and `SQLQueryToRetrieveGroups` returns formatted groups. After their retrieval, the group names are un-formatted in your plug-in implementation class before they are associated with the authenticated user.

If your database store supports hierarchical (or recursive) groups, you can set attributes `GroupMembershipSearching` and `MaxGroupMembershipSearchLevel` to the values of your choice. When recursive group searching is enabled, the formatted group is used as the input parameter in `SQLQueryToRetrieveGroups` to retrieve formatted groups of next level.

If the authentication plug-in is specified, the `SQLQueryToRetrievePassword` query string is optional. If this string is left blank, the plug-in must handle the retrieval of user's password. See "Provider Extensions" in the BEA WebLogic Enterprise Security Administration Guide, for more information on plug-in configuration.

## Configuring an ALES Identity Assertion Provider

The ALES Identity Assertion provider is used in Web Server Security Service Modules (SSMs) and WebLogic 8.1 SSMs for authentication and Web single sign-on (SSO). You use this provider in conjunction with the ALES Credential Mapping provider. If you configure one, you must also configure the other.

To configure an ALES Identity Assertion provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new ALES Identity Asserter.
- To change an existing provider, select the ALES Identity Asserter to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and configure the attributes. The certificate and keystore attributes are required. If you are configuring this provider for an IIS or Apache Web Server Security Service Module (SSM), the setting of the Base64 Decoding Required attribute has no effect, so the setting does not matter. However, if you are using this provider with a WebLogic Server 8.1 SSM to support web single sign-on with Web Server SSMs, leave the Base64 Decoding Required attribute set to unchecked, which is the default setting.
8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a SAML Identity Assertion Provider

To configure a SAML Identity Assertion provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new SAML Identity Asserter.
- To change an existing provider, select the SAML Identity Asserter to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

The following types of SAML Assertions are supported:

`SAML.Challenge`—The token is a Challenge token that has implemented the `com.bea.security.internal.SAMLChallenge` interface.

`SAML.Assertion`—SAML Assertion that contains the full CertPath. Same as `SAML.Assertion.Certpath`.

7. Click the Details tab and define any additional attributes.
8. Verify the setting of the Base64 Decoding Required attribute.

If the authentication type in a web application is set to `CLIENT-CERT`, the web application container in WebLogic Server performs identity assertion on values from request headers and cookies. If the header name or cookie name matches the active token type for the configured Identity Assertion provider, the value is passed to the provider.

The Base64 Decoding Required attribute determines whether the request header value or cookie value must be decoded using Base64 before sending it to the Identity Assertion provider. The setting is enabled by default for purposes of backward compatibility, however, for most Identity Assertion providers, you can disable this attribute.

9. Configure the required keystore attributes.
10. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Single Pass Negotiate Identity Asserter

The Single Pass Negotiate Identity Assertion provider supports identity assertion using HTTP authentication tokens from the SPNEGO protocol. The provider supports the identity assertion using the Kerberos tokens contained within the SPNEGO token.

To configure a Single Pass Negotiate Identity Assertion provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Single Pass Negotiate Identity Asserter.
- To change an existing provider, select the Single Pass Negotiate Identity Asserter to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. For Active Types, check to ensure that `Authorization` is already set in the Active Types Chosen list box.

Note: For compatibility, the `SPNEGO.AtnAssertion` active type is also listed in the Chosen list box, however, it is no longer used.

8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring an X.509 Identity Assertion Provider

To configure an X.509 Identity Assertion provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication Providers folder, and click Authentication.

The Authentication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new X.509 Identity Asserter.
- To change an existing provider, select the X.509 Identity Asserter to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. In the `User Name Mapper Class Name` attribute, define the name of the Java class that maps X.509 digital certificates and X.501 distinguished names to WebLogic Enterprise Security user names. Additional configuration is available on the Details tab.
8. In the `Trusted Client Principals` attribute define the list of client principals that can use CSIv2 identity assertion. You can use an asterisk (`*`) to specify all client principals.
9. Define the active token type for the X.509 Identity Assertion provider. The list of token types supported by the Identity Assertion provider is displayed in the Available list box. To define the active token type for the X.509 Identity Assertion provider:

1. In the Available list box, select the desired token type.
2. Click the right arrow to move token type to the Chosen list box.

10. Click Apply to save your changes.
11. Click the Details tab and define any additional attributes.
12. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring an ALES Credential Mapping Provider

The ALES Credential Mapping provider is used in conjunction with the ALES Identity Assertion provider. If you configure one, you must also configure the other.

To configure an ALES Credential Mapping provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Credential Mapping folder, and click Credential Mapping.

The Credential Mapping page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new ALES Credential Mapper.
- To change an existing provider, select the ALES Credential Mapper to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define the certificate and keystore attributes.
8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Database Credential Mapper

The Database Credential Mapper uses a two-way cipher secured by a pass-phrase or shared secret. By using a shared secret rather than an asymmetric key like 3DES (which requires a keystore), the provider configuration is self-contained and requires no external files. Another by-product of this mechanism is that you can encrypt your own passwords, by-passing the Administration Console, provided you know the shared secret and use the same JCE packaging as BEA WebLogic Enterprise Security.

The standard JCE Password-Based encryption algorithm `PBEWithMD5AndDES` is used. This creates a secret key from a salt, an iteration, and a pass-phrase/shared secret. In conjunction with the `CIPHER` of the same name, this method encrypts the password in the database preventing any party who does no know the shared secret to decrypt it.

The salt is eight bytes that are randomly generated. The iteration is a random value from 1 to 32:

>     [8 byte salt in clear][1 byte iteration ][encrypted bytes]                                            \ 8 bytes of salt + password bytes \

The salt is prepended to the password to be encrypted and the whole value is ciphered. The resulting bytes are prepended with the original salt and iteration count in clear text and base64 encoding is applied. The tag {`PBEWithMD5AndDES`} is prepended to the resulting string to indicate the cipher and key algorithm.

The resulting value:

>     {PBEWithMD5AndDES}Iz3zvlXFirq2ohr2fkrdrQbase64encodedAAAA=

To configure the Database Credential Mapping provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the provider you want to configure.

4. Open the Credential Mapping folder, and click Credential Mapping.

The Credential Mapping page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Database Credential Mapper.
- To change an existing provider, select the Database Credential Mapper to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define any additional attributes.

These attributes specify the types of credentials this provider is allowed to retrieve. If the `ALLOWED TYPE` attribute on the Details tab is set to a value of asterisk (*), then the provider attempts to serve all types of credentials using the query to limit the credentials returned.

8. Optionally, to configure failover, click the Failover tab and define additional attributes. See Configuring Failover for the Database Credential Mapper Provider for details on how to configure these attributes.
9. To define a query, click the Administration tab and perform the following tasks:

1. Configure the database to which to connect.

Note: You must have database administrator privileges to configure the database attributes.

2. Configure your queries.

These queries are executed within the administration application only. They are used to count, list, retrieve, modify and add credential mappings. The queries operate in conjunction with the configured database connection and do not use the connection pool configured for the provider. You can select the credentials to retrieve, by either username (Select By Ident) or group (Select By Ident Group).

Count Record Query

List Records Query

Retrieve Record Query

Delete Record Query

Save Record Query

Save Record With Password Query

Add Record Query

1. After you have located the user you want to map, you can map the credentials. To map credentials, click Edit Mappings. To add a new Mapping, click Add a new mapping, and define the attributes as needed.
2. Click Save and then click Close Editor.

10. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring Failover for the Database Credential Mapper Provider

If you have an backup database store, you can configure the Failover tab to enable this feature. To configure failover:

1. Click the Failover tab.
2. Check `EnableAutomaticFailover` to enable the failover capability.

When enabled, the provider connects to the backup database when the primary database is unavailable.

3. Set the `FailoverThreshold` value.

The Failure Threshold defines the number of database errors that must occur sequentially on a connection pool before that pool is considered failed.

4. Set the `PrimaryRetryInterval` value.

The provider retries the connection to the primary database when the period of time as set in `PrimaryRetryInterval` is reached.

5. Specify the attributes `BackupDatabaseUserName` and `BackupDatabasePassword`. These are the username and password of the database administrator of the backup database. In many case, the `BackupDatabaseUserName` is the same as user name in the primary database. If it is different, you or your DBA need to make sure that this user have read access to the tables specified in the three SQL queries specified in the Details tab.
6. Specify `BackupDatabaseProperties` with necessary properties. These properties are used to get the JDBC connection to the backup database. These properties are entered as `NAME=VALUE`.
7. Enter the `BackupDatabaseURL`. This is the JDBC URL to use to connect to the backup database. The backup database should be from the same database vendor, as the backup connection uses the same database JDBC driver.
8. Enter the `BackupConnectionPoolMin`. This represents the minimum number of connections to allow in the backup connection pool.
9. Enter the `BackupConnectionPoolMax`. This represents the maximum number of connections to allow in the backup connection pool.
10. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a SAML Credential Mapping Provider

To configure the SAML Credential Mapping provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Credential Mapping folder, and click Credential Mapping.

The Credential Mapping page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new SAML Credential Mapper.
- To change an existing provider, select the SAML Credential Mapper to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define any additional attributes.
8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring an ASI Authorization Provider

The ASI Authorization provider works in conjunction with the ASI Role Mapping provider. You must configure both providers using the same values for each attribute. You can include any number of custom ASI Authorization and ASI Role Mapping providers within one Security Service Module.

To configure an ASI Authorization provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authorization folder, and click Authorization.

The Authorization page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new ASI Authorization Provider.
- To change an existing provider, select the ASI Authorization provider to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define any additional attributes.
8. If you have configured a metadirectory, click the Metadirectory tab and define the metadirectory store. The metadirectory is required if you are writing policies that use delegation or user attributes. In addtion to completing the fields required by the Metadirectory tab, you must configure the password used by the metadirectory to log into the policy database. For instructions on how to configure this password, see Using the asipasswd Utility to Configure the Metadirectory Password.
9. For improved performance, click the Performance tab and define any additional attributes.
10. If you are using a resource converter, attribute retriever, or attribute converter plug-in, click the Advanced tab and define the additional attributes. For a description of the attributes defined using the Advanced tab, see the in-line help text for the Advanced tab in the Administration Console. If you are using an ASI Role Mapping provider with this ASI Authorization provider, the values you enter on this tab must be the same as those you enter on the corresponding ASI Role Mapping provider Advanced tab. For instructions on how to implement Java-based plug-ins, refer to Using Java-Based Plug-ins.
11. Click the Binding tab, select the resources to protect, and then click Bind.

Use this tab to bind resources to this provider. An ASI Authorization provider and an ASI Role Mapping provider for a Security Service Module only contain a subset of the overall policy. Binding applications to the provider determines that subset of policy. Applications not bound to the provider cannot be queried by the Security Service Module. A resource can be bound to only one Security Service Module, one ASI Authorization provider, and one ASI Role Mapper provider. The resources you bind must be the same for both providers.

Note: To unbind an ASI Authorization Provider from a Security Service Module, select the module to unbind, click the Binding tab, and then click the Unbind icon.

12. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

### Using the asipasswd Utility to Configure the Metadirectory Password

If you configure an ASI Authorization provider in a Security Service Module to use a metadirectory for user information, you must configure the login password used by the metadirectory to log into the policy database. To configure the password you must configure two files:

- `password.xml`—This file contains the encrypted database login password.
- `password.key`—The is contains the key used decrypt the database login password

You use the `asipasswd` utility configure these files.

To run the `asipassword` utility, perform the following steps:

1. Open a command window, go to `BEA_HOME\wles42-wls-ssm\instance\``instancename``\adm`, and enter the following command:

>     asipassword.bat username ..\ssl\password.xml ..\ssl\password.key

where:

instancename is the name of the instance of the Security Service Module.

`username` is the policy database login username.

2. When prompted, enter and confirm the policy database login password.

## Configuring an ASI Adjudication Provider

When multiple authorization providers are configured, each one may return a different answer to the "is access allowed" question for a given resource. This answer may be `PERMIT`, `DENY`, or `ABSTAIN`. Determining what to do if multiple authorization providers do not agree on the answer is the primary function of the ASI Adjudication provider. Adjudication providers resolve authorization conflicts by weighing each authorization provider's answer and returning a final decision.

The Adjudication provider behaves as follows:

- If all Authorization Providers return `PERMIT`, then `PERMIT`.
- If any Authorization Providers return `DENY`, then `DENY`.
- If `PERMIT` Authorization Providers return `ABSTAIN` and others return `PERMIT`, then `PERMIT` if unanimous permit is not required; otherwise `DENY`.

To configure an Adjudication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the Security Service Module whose providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Adjudication folder, and click Adjudication.

The Adjudication page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new ASI Adjudicator.
- To change an existing provider, select the ASI Adjudication provider to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If there is an Adjudication provider configured, click Replace with a new ASI Adjudicator. The Edit ASI Adjudicator page appears.

7. If desired, change the name of the provider.
8. Optionally, set the Require Unanimous Permit attribute.

The Require Unanimous Permit attribute determines how the ASI Adjudication provider handles a combination of `PERMIT` and `ABSTAIN` votes from the configured Authorization providers.

If the attribute is enabled, all Authorization providers must vote `PERMIT` in order for the Adjudication provider to vote true. By default, the Require Unanimous Permit attribute is enabled.

If the attribute is disabled, `ABSTAIN` votes are counted as `PERMIT` votes. To disable the Require Unanimous Permit attribute, click the check box.

Note: There are no attributes on the Details tab.

9. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring an ASI Role Mapping Provider

The ASI Role Mapping provider is used in conjunction with the ASI Authorization provider. You must configure both providers using the same values for each attribute.

You can include any number of custom ASI Authorization and ASI Role Mapping providers within one Security Service Module. See Configuring an ASI Authorization Provider for further details.

To configure an ASI Role Mapping provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the provider you want to configure.

4. Open the Role Mapping folder, and click Role Mapping.

The Role Mapping page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new ASI Role Mapper Provider.
- To change an existing provider, select the ASI Role Mapping provider to configure.

6. Do one of the following:

- If you are adding a new provider, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing provider, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define additional attributes. The values you enter here must be the same as those you entered for the corresponding ASI Authorization provider.
8. For improved performance, click the Performance tab and define additional attributes.
9. If you are using a resource converter, attribute retriever, or attribute converter plug-in, click the Advanced tab and define the additional attributes. For a description of the attributes defined using the Advanced tab, see the online help for the Advanced tab in the Administration Console Help. The values you enter on this tab must be the same as those you enter on the corresponding ASI Authorization provider Advanced tab. For instructions on how to implement Java-based plug-ins, refer to Using Java-Based Plug-ins.
10. Click the Bindings tab and select the resources to protect, and then click Bind.

Use this tab to bind resources to this provider. An ASI Authorization provider and an ASI Role Mapper provider for a Security Service Module only contain a subset of the overall policy. Binding applications to the provider determines that subset of policy. Applications not bound to the provider cannot be queried by the Security Service Module. A resource can be bound to only one Security Service Module, one ASI Authorization provider, and one ASI Role Mapper provider. The resources you bind must be the same for both providers.

11. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Resource Deployment Audit Provider

Warning: Using a Resource Deployment Audit provider affects the performance of Administration Console even if only a few events are logged. It also affects the performance of the Security Service Module.

To configure the Resource Deployment Audit Provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Auditing folder, and click Auditing.

The Auditing page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Resource Deployment Auditor.
- To change an existing provider, select the Resource Deployment Auditor to configure.

6. Do one of the following:

- If you are adding a new auditor, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing auditor, edit the settings on the General tab as needed, and then click Apply.

7. If you are using a resource converter or attribute converter plug-in, click the Details tab and define the additional attributes. For a description of the attributes defined using the Details tab, see the online help for the Advanced tab in the Administration Console Help. For instructions on how to implement a Java-based plug-in, refer to Using Java-Based Plug-ins.
8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Log4j Audit Channel Provider

The Log4j Audit Channel provider allows you to set the severity level at which auditing is initiated for the current Security Service Module. The output can be directed to an Output Stream, a java.io.Writer, a remote log4j server, a remote Unix Syslog daemon, or even a NT Event logger among many other output targets. Refer to the Apache Log4j documentation for detailed information on configuring Log4j.

Warning: Using an auditing provider affects the performance of Administration Console even if only a few events are logged. It also affects the performance of the Security Service Module.

To configure the Log4j Audit Channel provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the providers you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Auditing folder, and click Auditing.

The Auditing page appears.

5. Do one of the following:

- To configure a new provider, click Configure a new Log4j Auditor.
- To change an existing provider, select the Log4j Audit provider to configure.

6. Do one of the following:

- If you are adding a new auditor, on the General tab, assign a name for the provider, and then click Create.
- If you are changing an existing auditor, edit the settings on the General tab as needed, and then click Apply.

7. Click the Details tab and define any additional attributes.

Use this tab to configure the severity level at which auditing is initiated by the Log4j Audit Channel provider and to define what events are audited for the current Security Service Module. For a description of the attributes defined using the Details tab, see the online help for the Details tab in the Administration Console Help. For instructions on how to implement custom audit plug-ins, refer to Custom Audit Plug-ins. For additional information on audit events see What is an AuditEvent? and What Events are Audited?.

8. Click the Advanced tab and define any additional custom Log4j configuration attributes. For a description of the attributes defined using the Advanced tab, see the online help for the Advanced tab in the Administration Console Help. For instructions on how to implement custom audit plug-ins, refer to Custom Audit Plug-ins.
9. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a Custom Security Provider

If the default security configuration does not meet your requirements, you can change the configuration properties (as permitted) for each provider. Or, you can create a new provider as described in Developing Security Providers for BEA WebLogic Enterprise Security.

To configure a custom security provider:

1. Write a custom security provider.
2. Put the JAR file and any libraries used by the provider into the `WLES_HOME/lib/providers` directory on both the Administration Server and on the machine on which the Security Service Module is installed.
3. Start the Administration Console.
4. Open the Security Configuration folder, and click Security Control Managers.

The Service Control Manager page displays a list of folders representing each Service Control Manager configuration within your Administration Application.

5. Open the Security Service Module folder that contains the providers you want to configure or change, and click the folder name.

The Edit a Security Service Module Configuration page appears.

6. Open the folder for the provider you want to configure.

For example, expand the Authentication node to configure a custom Authentication provider.

7. Click the link representing the provider you want to configure.
8. Define values for the attributes on the each tab you have created.
9. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Deleting a Security Provider

To delete a security provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to delete.
3. Open the Security Service Module folder that contains the providers you want to delete and click the provider type name.
4. Open the folder that contains the security provider you want to delete, and click the provider type name, for example: Authentication.

The configured providers are displayed in a table.

5. Select the provider to delete, and then click the Trash Can icon.

A confirmation message appears.

6. Click Yes.
7. To confirm that the provider is deleted, expand the provider node that previously contained the deleted provider.

## Configuring a WebLogic Server Security Service Module

Before you can use the WebLogic Server v8.1 Security Service Module, you must configure the Security Service Module and the associated WebLogic Security Providers through the Administration Console. To configure a WebLogic Server v8.1 Security Service Module, perform the following tasks:

- Configuring a Service Control Manager
- Configuring a Security Service Module
- Configuring the WebLogic Security Providers
- Binding a Security Service Module to a Service Control Manager
- Distributing Configuration

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring the WebLogic Security Providers

This procedure shows how to create the initial configuration for use with the WebLogic Server v8.1 Security Service Module. Configuring these providers ensures the WebLogic Server v8.1 Security Service Module starts properly. After you configure the WebLogic security providers, if desired, you can replace them with the BEA WebLogic Enterprise Security providers described in Table 9-1.

To create an initial WebLogic Server v8.1 Security Service Module configuration:

1. Open the Security Configuration folder.
2. Open the Unbound Configurations folder, and click on Unbound Configurations.

The Unbound Security Service Module Configurations pages appears.

3. Click Create a new Security Service Module Configuration.

The Edit Security Service Module Configuration page appears.

4. On the General tab, in the Configuration ID text box, enter the identifier that was entered when this module was installed.
5. In the Description text box, enter a description for the service module configuration.
6. Click Create.

The Edit Security Service Module Configuration page displays and the new Security Service Module configuration appears under the Unbound Configurations folder in the navigation pane.

7. Click the Providers tab.

The Providers page displays six tabs, one for each type of provider available for configuration. Table 9-4 lists the name of each WebLogic provider you can configure along with a description of each one.

Table 9-4 WebLogic Security Providers

Provider Name | Description
--- | ---
WebLogic Authentication Provider | Supports Embedded LDAP authentication. For information on configuring a WebLogic Authentication Provider, see Configuring the WebLogic Authentication Provider.
WebLogic Authorization Provider | Provides enforcement of authorization for the security policy with which it is used. The Authorization Provider returns an access decision that determines which resources are protected and if a particular user is allowed access to a resource. For information on configuring a WebLogic Authorization Provider, see Configuring the WebLogic Authorization Provider.
WebLogic Role Mapping Provider | Provides assignment to roles based on the security policy with which it is used. The WebLogic Role Mapping Provider returns a set or roles granted to a user on a protected resource. For information on configuring a WebLogic Role Mapping Provider, see Configuring a WebLogic Role Mapping Provider.
WebLogic Credential Mapping Provider | Provides authentication credentials for a username and password. For information on configuring a WebLogic Credential Mapping Provider, see Configuring the WebLogic Credential Mapping Provider.

8. To configure each security provider listed in Table 9-4, refer to the following topics:

- Configuring the WebLogic Authentication Provider
- Configuring the WebLogic Authorization Provider
- Configuring a WebLogic Role Mapping Provider
- Configuring the WebLogic Credential Mapping Provider

## Configuring the WebLogic Authentication Provider

The WebLogic Authentication provider is case insensitive and you must ensure that all user names are unique. The WebLogic Authentication provider allows you to edit, list, and manage users and group membership. User and group membership information for the WebLogic Authentication provider is stored in an embedded LDAP server.

To configure the WebLogic Authentication provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authentication folder, and click on Authentication.

The Authentication page appears.

5. Do one of the following:

- If you are adding a new provider, click Configure a New WebLogic Authenticator, assign a name for the provider, and then click Create.
- To change an existing provider, select the WebLogic Authentication provider to configure.

6. If you are using multiple authentication providers, define a value for the Control Flag attribute on the General tab. For more information, Setting the JAAS Control Flag.
7. Optionally, set the Minimum Password Length to specify the minimum number of characters required in a password processed by this WebLogic Authentication provider.

This password is the password used to define users in the embedded LDAP server used by the WebLogic Authentication provider to store user and group information.

8. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring the WebLogic Authorization Provider

To configure the WebLogic Authorization provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Authorization folder, and click Authorization.

The Authorization page appears.

5. Do one of the following:

- If you are adding a new provider, click Configure a New WebLogic Authorizer, assign a name for the provider, and then click Create.
- To change an existing provider, select the WebLogic Authorization provider to configure.

By default, the provider stores security policies that are created while deploying a Web application or an Enterprise JavaBean (EJB). To disable this feature, clear the Policy Deployment Enabled check box.

6. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring a WebLogic Role Mapping Provider

The WebLogic Role Mapping provider can be used in conjunction with the WebLogic Authorization provider or an ASI Authorization provider.

Note: If you are using WebLogic Enterprise Security with the WebLogic Portal product, you must use a WebLogic Role Mapping provider with a WebLogic Authorization provider for authorization.

To configure WebLogic Role Mapping provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose providers you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the provider you want to configure.

4. Open the Role Mapping folder, and click Role Mapping.
5. Do one of the following:

To configure a new provider, click Configure a new WebLogic Role Mapper, assign a name for the provider, and then click Create.

To change an existing provider, select the WebLogic Role Mapping provider to configure.

6. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.

## Configuring the WebLogic Credential Mapping Provider

To configure the WebLogic Credential Mapping provider:

1. Open the Security Configuration folder.
2. Open the Service Control Manager folder that contains the Security Service Module whose provider you want to configure or change.
3. Open the Security Service Module folder that contains the provider you want to configure or change.

Note: If you have not bound the Security Service Module, open the Unbound Configuration folder that contains the providers you want to configure.

4. Open the Credential Mapping folder.
5. Do one of the following:

- To configure a new provider, click Configure a New WebLogic Credential Mapper, assign a name for the provider, and then click Create.
- To change an existing provider, select the WebLogic Credential Mapper to configure.

The Credential Mapping Deployment Enabled attribute specifies whether or not this Credential Mapping provider imports credential maps from a `weblogic-ra.xml` deployment descriptor file. To support the Credential Mapping Deployment Enabled attribute, the provider must implement the `DeployableCredentialProvider` SSPI. By default, the WebLogic Credential Mapping provider has this attribute enabled. The credential mapping information is stored in the embedded LDAP server.

6. Click Apply to save your changes.

Note: Changes made to a provider do not take effect until after it is explicitly deployed and the associated Security Service Module is restarted.