Managing WebLogic Security

Configuring Security Providers

The following sections describe how to configure the security providers supplied by WebLogic Server and custom security providers.

Note: Only the Realm Adapter Auditing, Adjudication, and Authorization providers are available when you are using Compatibility Security. For information about those providers, see Using Compatibility Security.

When Do I Need to Configure a Security Provider?

By default, most configuration work for WebLogic security providers is done. However, the following circumstances require you to configure attributes on a security provider:

Before using the WebLogic Identity Assertion provider, define the active token type. See Configuring a WebLogic Identity Assertion Provider.
To map tokens to a user in a security realm, configure the user name mapper in the WebLogic Identity Assertion provider. See Configuring a User Name Mapper.
To use auditing in the default (active) security realm, configure either the WebLogic Auditing provider or a custom Auditing provider. See Configuring a WebLogic Auditing Provider or Configuring a Custom Security Provider.
To use an LDAP server other than the embedded LDAP server, configure one of the LDAP Authentication providers. The LDAP authentication provider can be used instead of or in addition to the WebLogic Authentication provider. See Configuring an LDAP Authentication Provider.
To use existing users and groups stored in an 6.x security realm (for example, the 6.x Windows NT, UNIX, RDBMS security realms or 6.x custom security realms) in myrealm, configure the Realm Adapter Authentication provider. The Realm Adapter Authentication provider can be used instead of or in addition to the WebLogic Authentication provider. See Configuring a Realm Adapter Authentication Provider.

Note: There are no equivalents to the 6.x Windows NT, UNIX, RDBMS security realms in this release of WebLogic Server. Therefore, BEA recommends using the Realm Adapter Authentication provider to access the users and groups stored in these security realms.

When creating a new security realm, configure security providers for that new realm. When using the default realm (myrealm), the WebLogic Adjudication, Authentication, Identity Assertion, Authorization, Credential Mapping, and Role Mapping providers are already configured. See Creating a New Security Realm.
When adding a custom security provider to a security realm or replacing one of the WebLogic security providers with a custom security provider, configure attributes for the custom security provider. When writing a custom security provider, you can implement attributes that are configurable through the WebLogic Server Administration Console. However, those attributes are implementation-specific and are not addressed in this manual. See Writing Console Extensions for Custom Security Providers in Developing Security Providers for WebLogic Server.

The remainder of this section describes the attributes that can be set for each security provider.

Configuring a WebLogic Adjudication Provider

When multiple Authorization providers are configured in a security realm, each 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 Adjudication provider. Adjudication providers resolve authorization conflicts by weighting each Authorization provider's answer and returning a final decision.

Each security realm requires an Adjudication provider. You can use either a WebLogic Adjudication provider or a custom Adjudication provider in a security realm. This section describes how to configure a WebLogic Adjudication provider. For information about configuring a custom security provider (including a custom Adjudication provider), see Configuring a Custom Security Provider.

To configure a WebLogic Adjudication provider:

In the left pane of the WebLogic Server Administration Console, expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm.)

Expand the Providers node.

Click Adjudicators.

The Adjudicators table displays the name of the default Adjudication provider for the realm that is being configured.

Click the Configure a new Default Adjudicator... link.

When working in an existing security realm, click the Replace with a new Default Adjudicator... link.

Optionally, on the General tab, set the Require Unanimous Permit attribute.

The Require Unanimous Permit attribute determines how the WebLogic 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 checkbox.

Click Apply to save your changes.

Reboot WebLogic Server.

Configuring a WebLogic Auditing Provider

Auditing is the process whereby information about operating requests and the outcome of those requests are collected, stored, and distributed for the purposes of non-repudiation. In other words, Auditing providers produce an electronic trail of computer activity. Configuring an Auditing provider is optional. The default security realm (myrealm) does not have an Auditing provider configured.

Note: A Common Criteria certified configuration must have the WebLogic Auditing provider enabled. For information about the configuration of BEA WebLogic Server certified through the Common Criteria evaluation and validation process, see the product listing in the Validated Products section of the National Information Assurance Partnership Web site at http://niap.nist.gov/ . Information about the configuration of a product in evaluation is not publicly available. Such information is publicly available for validated products only.

You can use either a WebLogic Auditing provider or a custom Auditing provider in a security realm. This topic describes how to configure a WebLogic Auditing provider. For information about configuring a custom security provider (including a custom Auditing provider), see Configuring a Custom Security Provider.

Warning: Using an Auditing provider affects the performance of WebLogic Server even if only a few events are logged.

To configure the WebLogic Auditing provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers node.

Click Auditors.

The Auditors table displays the name of the default Auditor for the realm that is being configured.

Click the Configure a new Default Auditor... link.

Click Create.

Click the Details tab.

Choose the severity level appropriate for your WebLogic Server deployment.

The Auditing provider audits a particular security event based on the event level specified in the Severity attribute. Auditing can be initiated when the following levels of security events occur:

INFORMATION
WARNING
ERROR
SUCCESS
FAILURE

Specify how many minutes to wait before creating a new DefaultAuditRecorder.log file in the Rotation Minutes attribute. At the specified time, the audit file is closed and a new one is created. A backup file named DefaultAuditRecorder.YYYYMMDDHHMM.log (for example,DefaultAuditRecorder.200405130110.log ) is created in the same directory.

Click Apply.

Reboot WebLogic Server.

All auditing information recorded by the WebLogic Auditing provider is saved in WL_HOME\yourdomain\yourserver\DefaultAuditRecorder.log by default. Although, an Auditing provider is configured per security realm, each server writes auditing data to its own log file in the server directory. You can specify a new directory location for the DefaultAuditRecorder.log file on the command line with the following Java startup option:

-Dweblogic.security.audit.auditLogDir=c:\foo

The new file location will be c:\foo\yourserver\DefaultAuditRecorder.log.

For more information, see "weblogic.Server Command-Line Reference."

The WebLogic Auditing provider logs the following events:

Table 3-1 WebLogic Auditing Provider Events

Audit Event	Indicates...
AUTHENTICATE	Simple authentication (username and password) occurred.
ASSERTIDENTITY	Perimeter authentication (based on tokens) occurred.
USERLOCKED	A user account is locked because of invalid login attempts.
USERUNLOCKED	The lock on a user account is cleared.
USERLOCKOUTEXPIRED	The lock on a user account expired.
ISAUTHORIZED	An authorization attempt occurred.
ROLEEVENT	A getRoles event occurred.
ROLEDEPLOY	A deployRole event occurred.
ROLEUNDEPLOY	An undeployRole event occurred.
POLICYDEPLOY	A deployPolicy event occurred.
POLICYUNDEPLOY	An undeployPolicy event occurred.
AuditCreateConfigurationEvent	A user has created a resource in the domain. Requires you to enable the domain to emit configuration Audit Events. See Configuration Auditing in the Administration Console Online Help.
AuditSetAttributeConfigurationEvent	A user has modified the setting of a resource in the domain. Requires you to enable the domain to emit configuration Audit Events. See Configuration Auditing in the Administration Console Online Help.
AuditInvokeConfigurationEvent	A user has invoked an operation on a resource in the domain. Requires you to enable the domain to emit configuration Audit Events. See Configuration Auditing in the Administration Console Online Help.
AuditDeleteConfigurationEvent	A user has deleted a resource in the domain. Requires you to enable the domain to emit configuration Audit Events. See Configuration Auditing in the Administration Console Online Help.

Choosing an Authentication Provider

Authentication is the process whereby the identity of users or system processes are proved or verified. Authentication also involves remembering, transporting, and making identity information available to various components of a system when that information is needed.

The WebLogic Server security architecture supports: certificate-based authentication directly with WebLogic Server; HTTP certificate-based authentication proxied through an external Web server; perimeter-based authentication (Web server, firewall, VPN); and authentication based on multiple security token types and protocols.

Authentication is performed by an Authentication provider. WebLogic Server offers the following types of Authentication providers:

The WebLogic Authentication provider accesses user and group information in the embedded LDAP server.
LDAP Authentication providers access external LDAP stores. WebLogic Server provides LDAP Authentication providers which access Open LDAP, Netscape iPlanet, Microsoft Active Directory and Novell NDS stores. An LDAP Authentication provider can also be used to access other LDAP stores. However, you must choose a pre-defined LDAP provider and customize it. See Accessing Other LDAP Servers.
The Realm Adapter Authentication provider accesses user and group information stored in 6.x security realms.
The MedRec Authentication provider implements authentication for the MedRec sample application. This Authentication provider can only be used with the MedRec sample application and should be removed from production domains. See the "Security Known Problems" section in the WebLogic Server Release Notes.
The WebLogic Identity Assertion provider validates X.509 and IIOP-CSIv2 tokens and can use a user name mapper to map that token to a user in a WebLogic Server security realm.

In addition, you can use:

Custom Authentication providers, which offer different types of authentication technologies.
Custom Identity Assertion providers, which support different types of tokens.

Note: The WebLogic Server Administration Console refers to the WebLogic Authentication provider as the Default Authenticator and the WebLogic Identity Assertion provider as the Default Identity Asserter.

Each security realm must have one at least one Authentication provider configured. The WebLogic Security Framework is designed to support multiple Authentication providers (and thus multiple LoginModules) for multipart authentication. Therefore, you can use multiple Authentication providers as well as multiple types of Authentication providers in a security realm. For example, if you want to use both a retina-scan and a username/password-based form of authentication to access a system, you configure two Authentication providers.

The way you configure multiple Authentication providers can affect the overall outcome of the authentication process. Use the JAAS Control Flag attribute to set up login dependencies between Authentication providers and allow single-sign on between providers. See Setting the JAAS Control Flag Attribute.

Authentication providers are called in the order in which they are configured. Therefore, use caution when configuring Authentication providers. Use the Reorder the Configured Authentication Providers link to modify the configuraiton of the Authentication providers. See Changing the Order of Authentication Providers.

Configuring an Authentication Provider: Main Steps

To configure an Authentication provider:

In the left pane of the WebLogic Server Administration Console, expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

Choose an Authentication and/or Identity Assertion provider.

Configure a new iPlanet Authenticator...
Configure a new Realm Adapter Authenticator...
Configure a new Active Directory Authenticator...
Configure a new Default Authenticator...
Configure a new Default Identity Asserter...
Configure a new OpenLDAP Authenticator...
Configure a new Novell Authenticator...

Go to the appropriate sections to configure an Authentication and/or Identity Assertion provider.

Repeat these steps to configure additional Authentication and/or Identity Assertion providers.

If you are configuring multiple Authentication providers, set the JAAS control flag. See Setting the JAAS Control Flag Attribute.

After you finish configuring Authentication and/or Identity Assertion providers, reboot WebLogic Server.

Setting the JAAS Control Flag Attribute

When you configure multiple Authentication providers, use the JAAS Control Flag attribute on the Authenticator-->General tab to control how the Authentication providers are used in the login sequence.

The definitions for the JAAS Control Flag values are as follows:

REQUIRED—The Authentication provider is always called, and the user must always pass its authentication test.
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.
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).
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 one of the configured providers.

When additional Authentication providers are added to an existing security realm, by default the Control Flag attribute is set to OPTIONAL. If necessary, change the setting of the Control Flag so that the Authentication provider works properly in the authentication sequence.

Note: The WebLogic Server Administration Console actually sets the JAAS Control Flag to OPTIONAL when creating a security provider. MBeans for the security providers actually default to REQUIRED.

Configuring an LDAP Authentication Provider

WebLogic Server does not support or certify any particular LDAP servers. Any LDAP v2 or v3 compliant LDAP server should work with WebLogic Server. The following LDAP directory servers have been tested:

Netscape iPlanet version 4.1.3
Active Directory shipped as part of Windows 2000
Open LDAP version 2.0.7
Novell NDS version 8.5.1

For more information, see:

Requirements for Using an LDAP Authentication Provider

If an LDAP Authentication provider is the only configured Authentication provider for a security realm, you must have the Admin role to boot WebLogic Server and use a user or group in the LDAP directory. Do one of the following in the LDAP directory:

By default in WebLogic Server, the Admin role includes the Administrators group. Create an Administrators group in the LDAP directory. Make sure the LDAP user who will boot WebLogic Server is included in the group.

The Active Directory LDAP directory has a default group called Administrators. Add the user who will be booting WebLogic Server to the Administrators group and define the Group Base Distinguished Name (DN) attribute so that the Administrators group is found.

If you do not want to create an Administrators group in the LDAP directory (for example, because the LDAP directory uses the Administrators group for a different purpose), create a new group (or use an existing group) in the LDAP directory and include the user from which you want to boot WebLogic Server in that group. In the WebLogic Server Administration Console, assign that group the Admin role.

Configuring a LDAP Authentication Provider

To configure an LDAP Authentication provider:

In the left pane of the WebLogic Server Administration Console, expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

Choose an LDAP Authentication provider.

Configure a new iPlanet Authenticator...
Configure a new Active Directory Authenticator...
Configure a new OpenLDAP Authenticator...
Configure a new Novell Authenticator...

If you using multiple Authentication providers, define a value for the Control Flag attribute on the General tab. The Control Flag attribute determines how the LDAP Authentication provider is used with other LDAP Authentication providers. For more information, see Configuring an LDAP Authentication Provider.

Click Apply to save your changes.

Proceed to Setting LDAP Server and Caching Information.

Setting LDAP Server and Caching Information

To configure the LDAP server:

Select the Configuration-->LDAP tab for the LDAP Authentication provider you want to use.

For example, select the iPlanet Configuration-->iPlanet tab.

Enable communication between WebLogic Server and the LDAP server by defining values for the attributes shown on the LDAP tab.

The following table describes the attributes you set on the LDAP tab. Table 3-2 Attributes on the LDAP Tab Attribute Description Host The host name of the computer on which the LDAP server is running. Port The port number on which the LDAP server is listening. If you want WebLogic Server to connect to the LDAP server using the SSL protocol, use the LDAP server's SSL port in this attribute. SSL Enabled Option for enabling the SSL protocol to protect communications between the LDAP server and WebLogic Server. Disable this attribute if the LDAP server is not configured to use the SSL protocol. Principal The Distinguished name (DN) of the LDAP user used by WebLogic Server to connect to the LDAP server. Generally, this user is the system administrator of the LDAP directory server. If you want to change passwords, this attribute must be the system administrator. Credential Password that authenticates the LDAP user defined in the Principal attribute. Cache Enabled Enables the use of a data cache with the LDAP server. Cache Size Maximum size of lookups in cache. The default is 32kb. Cache TTL Number of seconds to retain the results of an LDAP lookup.

Attribute	Description
Host	The host name of the computer on which the LDAP server is running.
Port	The port number on which the LDAP server is listening. If you want WebLogic Server to connect to the LDAP server using the SSL protocol, use the LDAP server's SSL port in this attribute.
SSL Enabled	Option for enabling the SSL protocol to protect communications between the LDAP server and WebLogic Server. Disable this attribute if the LDAP server is not configured to use the SSL protocol.
Principal	The Distinguished name (DN) of the LDAP user used by WebLogic Server to connect to the LDAP server. Generally, this user is the system administrator of the LDAP directory server. If you want to change passwords, this attribute must be the system administrator.
Credential	Password that authenticates the LDAP user defined in the Principal attribute.
Cache Enabled	Enables the use of a data cache with the LDAP server.
Cache Size	Maximum size of lookups in cache. The default is 32kb.
Cache TTL	Number of seconds to retain the results of an LDAP lookup.

To save your changes, click Apply.

Select the Details tab to configure additional attributes that control the behavior of the LDAP server.

The following table describes the attributes you set on the Details tab.

Table 3-3 Attributes on the Details Tab

Attribute

Description

Use Token Groups for Group Membership Lookup

Note: This attribute applies to the Active Directory Authentication provider only.

Indicates whether to use the Active Directory TokenGroups attribute lookup algorithm instead of the standard recursive group membership lookup algorithm.

Active Directory TokenGroups attribute holds the entire flattened group membership for a user as an array of SID values. The SID values are specially indexed in the Active Directory LDAP server and yield extremely fast lookup response.

By default, this attribute is not enabled.

Note: Access to the TokenGroups attribute is required (meaning, the user accessing the LDAP directory must have privileges to read the TokenGroups attribute and the TokenGroups attribute must be in the schema for user objects).

Enable SID to Group Lookup Caching

Note: This attribute applies to the Active Directory Authentication provider only.

Indicates whether or not SID to group name lookup results are cached. This attribute only applies if the Use Token Groups for Group Membership Lookup attribute is enabled.

Max SID To Group Lookups In Cache

Note: This attribute applies to the Active Directory Authentication provider only.

The maximum size of the Least Recently Used (LRU) cache for holding SID to group lookups. This attribute applies only if both the Use Token Groups for Group Membership Lookup and Enable SID to Group Lookup Caching attributes are enabled.

Group Membership Searching

Controls whether group searches are limited in depth or unlimited. This attribute controls how deeply a search should recursive into nested groups. For configurations that use only the first level of nested group hierarchy, this attribute allows improved performance during user searches by limiting the search to the first level of the group.

If a limited search is specified, the Max Group Membership Search Level attribute must be specified.

If an unlimited search is specified, the Max Group Membership Search Level attribute is ignored.

Max Group Membership Search Level

Controls the depth of a group membership search if the Group Membership Searching attribute is specified. Possible values are:

0—Indicates only direct groups will be found. That is, when searching for membership in Group A, only direct members of Group A will be found. If Group B is a member of Group A, the members will not be found by this search.

Any positive number—Indicates the number of levels to search. For example, if this attribute is set to 1, a search for membership in Group A will return direct members of Group A. If Group B is a member of Group A, the members of Group B will also be found by this search. However, if Group C is a member of Group B, the members of Group C will not be found by this search.

Use Retrieved User Name as Principal

Specifies that the user name retrieved from the LDAP directory should be added as the principal instead of the username supplied for authentication.

Follow Referrals

Specifies that a search for a user or group within the LDAP Authentication provider will follow referrals to other LDAP servers or branches within the LDAP directory. By default, this attribute is enabled.

Bind Anonymously On Referrals

By default, an LDAP Authentication provider uses the same DN and password used to connect to the LDAP server when following referrals during a search. If you want to connect as an anonymous user, enable this attribute. Contact your LDAP system administrator for more information.

Results Time Limit

The maximum number of milliseconds for the LDAP server to wait for results before timing out. If this attribute is set to 0, there is no maximum time limit. The default is 0.

Connect Timeout

The maximum time in seconds to wait for the connection to the LDAP server to be established. If this attribute is set to 0, there is not a maximum time limit. The default is 0.

Parallel Connect Delay

The delay in seconds when making concurrent attempts to attempt to multiple LDAP servers. If this attribute is set to 0, connection attempts are serialized. An attempt is made to connect to the first server in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. If this attribute is not set and an LDAP server is unavailable, an application may be blocked for a long time. If this attribute is greater than 0, another connection is started after the specified time.

Connection Retry Limit

The number of times WebLogic Server should try to establish a connection with an LDAP server, if the LDAP server initially throws an exception when an LDAP Authentication provider tries to connect to it.

This attribute solves the problem of having two identical LDAP Authentication providers trying to simultaneously connect to the same LDAP server. In past releases, the connection would fail and WebLogic Server would need to be rebooted. Now the server will try to reconnect the specified number of times.

Attribute	Description
Use Token Groups for Group Membership Lookup	Note: This attribute applies to the Active Directory Authentication provider only. Indicates whether to use the Active Directory `TokenGroups` attribute lookup algorithm instead of the standard recursive group membership lookup algorithm. Active Directory `TokenGroups` attribute holds the entire flattened group membership for a user as an array of SID values. The SID values are specially indexed in the Active Directory LDAP server and yield extremely fast lookup response. By default, this attribute is not enabled. Note: Access to the `TokenGroups` attribute is required (meaning, the user accessing the LDAP directory must have privileges to read the `TokenGroups` attribute and the `TokenGroups` attribute must be in the schema for user objects).
Enable SID to Group Lookup Caching	Note: This attribute applies to the Active Directory Authentication provider only. Indicates whether or not SID to group name lookup results are cached. This attribute only applies if the Use Token Groups for Group Membership Lookup attribute is enabled.
Max SID To Group Lookups In Cache	Note: This attribute applies to the Active Directory Authentication provider only. The maximum size of the Least Recently Used (LRU) cache for holding SID to group lookups. This attribute applies only if both the Use Token Groups for Group Membership Lookup and Enable SID to Group Lookup Caching attributes are enabled.
Group Membership Searching	Controls whether group searches are limited in depth or unlimited. This attribute controls how deeply a search should recursive into nested groups. For configurations that use only the first level of nested group hierarchy, this attribute allows improved performance during user searches by limiting the search to the first level of the group. If a limited search is specified, the Max Group Membership Search Level attribute must be specified. If an unlimited search is specified, the Max Group Membership Search Level attribute is ignored.
Max Group Membership Search Level	Controls the depth of a group membership search if the Group Membership Searching attribute is specified. Possible values are: 0—Indicates only direct groups will be found. That is, when searching for membership in Group A, only direct members of Group A will be found. If Group B is a member of Group A, the members will not be found by this search. Any positive number—Indicates the number of levels to search. For example, if this attribute is set to 1, a search for membership in Group A will return direct members of Group A. If Group B is a member of Group A, the members of Group B will also be found by this search. However, if Group C is a member of Group B, the members of Group C will not be found by this search.
Use Retrieved User Name as Principal	Specifies that the user name retrieved from the LDAP directory should be added as the principal instead of the username supplied for authentication.
Follow Referrals	Specifies that a search for a user or group within the LDAP Authentication provider will follow referrals to other LDAP servers or branches within the LDAP directory. By default, this attribute is enabled.
Bind Anonymously On Referrals	By default, an LDAP Authentication provider uses the same DN and password used to connect to the LDAP server when following referrals during a search. If you want to connect as an anonymous user, enable this attribute. Contact your LDAP system administrator for more information.
Results Time Limit	The maximum number of milliseconds for the LDAP server to wait for results before timing out. If this attribute is set to 0, there is no maximum time limit. The default is 0.
Connect Timeout	The maximum time in seconds to wait for the connection to the LDAP server to be established. If this attribute is set to 0, there is not a maximum time limit. The default is 0.
Parallel Connect Delay	The delay in seconds when making concurrent attempts to attempt to multiple LDAP servers. If this attribute is set to 0, connection attempts are serialized. An attempt is made to connect to the first server in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. If this attribute is not set and an LDAP server is unavailable, an application may be blocked for a long time. If this attribute is greater than 0, another connection is started after the specified time.
Connection Retry Limit	The number of times WebLogic Server should try to establish a connection with an LDAP server, if the LDAP server initially throws an exception when an LDAP Authentication provider tries to connect to it. This attribute solves the problem of having two identical LDAP Authentication providers trying to simultaneously connect to the same LDAP server. In past releases, the connection would fail and WebLogic Server would need to be rebooted. Now the server will try to reconnect the specified number of times.

Proceed to Locating Users in the LDAP Directory.

For a more secure deployment, BEA recommends using the SSL protocol to protect communications between the LDAP server and WebLogic Server. For more information, see Configuring SSL.

Locating Users in the LDAP Directory

To specify how users are located in the LDAP directory:

Select the Configuration-->Users tab for the LDAP server you chose.

For example, select the iPlanet Configuration-->Users tab.

Define information about how users are stored and located in the LDAP directory by defining values for the attributes shown on the Users tab.

The following table describes the attributes you set on the Users tab.

Table 3-4 Attributes on the Users Tab

Attribute

Description

User Object Class

The LDAP object class that stores users.

User Name Attribute

The attribute on an LDAP user object that specifies the name of the user.

User Dynamic Group DN Attribute

The attribute of an LDAP user object that specifies the distinguished name of dynamic groups to which this user belongs.

Dynamic groups are not supported with the Active Directory, Open LDAP, or Novell NDS directory servers, so set this attribute to NULL for these servers.

If this attribute does not exist, WebLogic Server looks at the Dynamic Group Object Class attribute to determine the groups to which this user belongs.

If a group contains other groups, WebLogic Server evaluates the URLs of any of the descendents of the group.

User Base DN

The base DN of the tree in the LDAP directory that contains users.

If you store WebLogic Server users under multiple roots in your directory, you can specify these roots as user.dn.1, user.dn.2, and so on. The LDAP Authentication provider will search under each of these roots in turn until it finds a matching user.

Note: You must supply a user filter (user.filter.n) for each user.dn.n entry.

User Search Scope

Specifies how deep in the LDAP directory tree to search for users.

Valid values are subtree and onelevel.

User from Name Filter

An LDAP search filter for finding a user given the name of the user.

If a search filter is not specified (that is, if the attribute is null or empty), a default search filter is created based on the user schema.

Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.

All Users Filter

An LDAP search filter for finding all users beneath the base DN. If a search filter is not specified (that is, if the attribute is null or empty), a default search filter is created based on the user schema.

Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.

Attribute	Description
User Object Class	The LDAP object class that stores users.
User Name Attribute	The attribute on an LDAP user object that specifies the name of the user.
User Dynamic Group DN Attribute	The attribute of an LDAP user object that specifies the distinguished name of dynamic groups to which this user belongs. Dynamic groups are not supported with the Active Directory, Open LDAP, or Novell NDS directory servers, so set this attribute to NULL for these servers. If this attribute does not exist, WebLogic Server looks at the Dynamic Group Object Class attribute to determine the groups to which this user belongs. If a group contains other groups, WebLogic Server evaluates the URLs of any of the descendents of the group.
User Base DN	The base DN of the tree in the LDAP directory that contains users. If you store WebLogic Server users under multiple roots in your directory, you can specify these roots as `user.dn.1`, `user.dn.2`, and so on. The LDAP Authentication provider will search under each of these roots in turn until it finds a matching user. Note: You must supply a user filter (`user.filter.n`) for each `user.dn.n` entry.
User Search Scope	Specifies how deep in the LDAP directory tree to search for users. Valid values are `subtree` and `onelevel`.
User from Name Filter	An LDAP search filter for finding a user given the name of the user. If a search filter is not specified (that is, if the attribute is null or empty), a default search filter is created based on the user schema. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.
All Users Filter	An LDAP search filter for finding all users beneath the base DN. If a search filter is not specified (that is, if the attribute is null or empty), a default search filter is created based on the user schema. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.

To save your changes, click Apply.

Proceed to Locating Groups in the LDAP Directory.

Locating Groups in the LDAP Directory

To define how groups are stored and located in the LDAP directory:

Select the Configuration-->Groups tab.

For example, select the iPlanet Configuration-->Groups tab.

Define information about how groups are stored and located in the LDAP directory by defining values for the attributes shown on the Groups tab.

The following table describes the attributes you set on the Groups tab. Table 3-5 Attributes on the Groups Tab Attribute Description Group Base DN The base DN of the tree in the LDAP directory that stores groups. Group Search Scope Specifies how deep in the LDAP directory tree to search for groups. Valid values are subtree and onelevel. Group From Name Filter An LDAP search filter for finding a group given the name of the group. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter. All Groups Filter An LDAP search filter for finding all groups beneath the base group DN. If the attribute is not specified (that is, if the attribute is null or empty), a default search filter is created based on the Group schema. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter. Static Group Object Class The name of the LDAP object class that stores static groups. Static Group Name Attribute The attribute of a static LDAP group object that specifies the name of the group.

Attribute	Description
Group Base DN	The base DN of the tree in the LDAP directory that stores groups.
Group Search Scope	Specifies how deep in the LDAP directory tree to search for groups. Valid values are `subtree` and `onelevel`.
Group From Name Filter	An LDAP search filter for finding a group given the name of the group. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.
All Groups Filter	An LDAP search filter for finding all groups beneath the base group DN. If the attribute is not specified (that is, if the attribute is null or empty), a default search filter is created based on the Group schema. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.
Static Group Object Class	The name of the LDAP object class that stores static groups.
Static Group Name Attribute	The attribute of a static LDAP group object that specifies the name of the group.

To save your changes, click Apply.

Proceed to Locating Members of a Group in the LDAP Directory.

Locating Members of a Group in the LDAP Directory

Note: The iPlanet Authentication provider supports dynamic groups. To use dynamic groups, set the Dynamic Group Object Class, Dynamic Group Name Attribute, and Dynamic Member URL Attribute attributes. If you use dynamic groups, consider the configuration information in Configuring Dynamic Groups in the iPlanet Authentication Provider to Improve Performance.

To define how groups members are stored and located in the LDAP directory:

Select on the Configuration-->Membership tab.

For example, select the iPlanet Configuration-->Membership tab.

Define information about how group members are stored and located in the LDAP directory by defining values for the attributes shown on the Membership tab.

The following table describes the attributes you set on the Membership tab.

Table 3-6 Attributes on the Membership Tab

Attribute

Definition

Static Member DN Attribute

The attribute of an LDAP group object that specifies the DNs of the members of the group.

Static Group DNs from Member DN Filter

An LDAP search filter that, given the DN of a member of a group, returns the DNs of the static LDAP groups that contain that member.

If the attribute is not specified (that is, if the attribute is null or empty), a default search filter is created based on the group schema.

Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.

Dynamic Group Object Class

The name of the LDAP object class that stores dynamic groups.

Dynamic groups are not currently supported by Active Directory, Open LDAP, or Novell NDS directory servers. Do not set this attribute if you are using these servers.

Dynamic Group Name Attribute

The attribute of a dynamic LDAP group object that specifies the name of the group.

Dynamic groups are not currently supported by Active Directory, Open LDAP, or Novell NDS directory servers. Do not set this attribute if you are using these servers.

Dynamic Member URL Attribute

The attribute of the dynamic LDAP group object that specifies the URLs of the members of the dynamic group.

Note: A Malformed URL exception can result when this attribute contains a string value with a reserved value. To avoid this exception, avoid using :, ,, ?, and / in the attribute.

Dynamic groups are not currently supported by Active Directory, Open LDAP, or Novell NDS directory servers. Do not set this attribute if you are using these servers.

Attribute	Definition
Static Member DN Attribute	The attribute of an LDAP group object that specifies the DNs of the members of the group.
Static Group DNs from Member DN Filter	An LDAP search filter that, given the DN of a member of a group, returns the DNs of the static LDAP groups that contain that member. If the attribute is not specified (that is, if the attribute is null or empty), a default search filter is created based on the group schema. Refer to the documentation for your LDAP server for more information about writing an LDAP search filter.
Dynamic Group Object Class	The name of the LDAP object class that stores dynamic groups. Dynamic groups are not currently supported by Active Directory, Open LDAP, or Novell NDS directory servers. Do not set this attribute if you are using these servers.
Dynamic Group Name Attribute	The attribute of a dynamic LDAP group object that specifies the name of the group. Dynamic groups are not currently supported by Active Directory, Open LDAP, or Novell NDS directory servers. Do not set this attribute if you are using these servers.
Dynamic Member URL Attribute	The attribute of the dynamic LDAP group object that specifies the URLs of the members of the dynamic group. Note: A Malformed URL exception can result when this attribute contains a string value with a reserved value. To avoid this exception, avoid using `:`, `,`, `?`, and `/` in the attribute. Dynamic groups are not currently supported by Active Directory, Open LDAP, or Novell NDS directory servers. Do not set this attribute if you are using these servers.

To save your changes, click Apply.

Optionally, configure additional Authentication and/or Identity Assertion providers.

Reboot WebLogic Server.

Accessing Other LDAP Servers

The LDAP Authentication providers in this release of WebLogic Server work with the iPlanet, Active Directory, Open LDAP, and Novell NDS LDAP Servers. You can use an LDAP Authentication provider to access new types of LDAP Servers. Choose the existing LDAP provider that most closely matches the new LDAP server and customize the existing attributes for the new LDAP server.

To create an LDAP Authentication provider for new LDAP server:

In the left pane of the WebLogic Server Administration Console, expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

Choose the LDAP Authentication provider that is most like the new LDAP server.

On the General tab, enter a name for the new LDAP Authentication provider in the Name attribute (for example, MyLdapServer).

Click Create.

Select the LDAP Server tab (for example, iPlanet LDAP).

Enable communication between WebLogic Server and the new LDAP server by modifying values for the attributes shown on the LDAP tab. See Setting LDAP Server and Caching Information.

Select the Users tab and define how users are located in the LDAP directory. Modify the existing values to match the values for the new LDAP server. See Locating Users in the LDAP Directory.

Select the Groups tab and define how groups are located in the LDAP directory. Modify the existing values to match the values for the new LDAP server. See Locating Groups in the LDAP Directory.

Select the Membership tab and define how members of a group are located in the LDAP directory. Modify the existing values to match the values for the new LDAP server. See Locating Members of a Group in the LDAP Directory.

Reboot WebLogic Server.

Configuring Failover for LDAP Authentication Providers

You can configure an external LDAP provider 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:

Select the Configuration-->LDAP tab for the LDAP Authentication provider for which you want to configure failover.

For example, select the iPlanet Configuration-->iPlanet tab.

Select the LDAP tab.

Specify more than one LDAP server name in the Host attribute on the LDAP tab. The attribute must contain a space-delimited list of host names. Each host name may include a trailing colon and port number. For example:

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

Click Apply.

Select the Details tab.

Set the Parallel Connect Delay attribute.

Specify the number of seconds to delay when making concurrent attempts to connect to multiple servers. An attempt is made to connect to the first server in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. This setting might cause your application to block for an unacceptably long time if a host is down. If the attribute is set to a value greater than 0, another connection setup thread is started after the specified number of delay seconds has passed. If the attribute is set to 0, connection attempts are serialized.

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

Click Apply.

Reboot WebLogic Server.

The following examples present use scenarios that will occur when the LDAP attributes are set for LDAP failover.

Example 1

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 preceeding scenario, 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.

Example 2

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

In the preceeding scenario, 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 connect to directory.knowledge.com after the connection to people.catalog.com succeeds.

Configuring a WebLogic Authentication Provider

Note: The WebLogic Server Administration Console refers to the WebLogic Authentication provider as the Default Authenticator.

The WebLogic Authentication provider is case insensitive. Ensure 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 the embedded LDAP server.

To configure the WebLogic Authentication provider:

Configure the embedded LDAP server as described in Managing the Embedded LDAP Server.

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

Choose the Configure a new Default Authenticator... link.

Define values for the attributes on the General tab.

The Minimum Password Length attribute applies to the passwords you specify when defining users in the WebLogic Authentication provider.
The Control Flag attribute determines how the WebLogic Authentication provider is used with other Authentication providers. For more information, see Setting the JAAS Control Flag Attribute.

Click Apply to save your changes.

Optionally, configure additional Authentication and/or Identity Assertion providers.

Reboot WebLogic Server.

Improving the Performance of WebLogic and LDAP Authentication Providers

WebLogic Server provides a set of attributes which can be used to optimize the performance of the WebLogic and LDAP Authentication providers. Performance can be improved in the following ways:

Configure the Active Directory Authentication provider to perform group membership lookups using the tokenGroups attribute. The tokenGroups attribute holds the entire flattened group membership for a user as an array of SID values. The SID values are specially indexed in the Active Directory and yield extremely fast lookup response.
Optimize the configuration of the group membership caches used by the WebLogic and LDAP Authentication providers.
Configure the handling of dynamic groups in the iPlanet Authentication provider.
Expose the internal PrincipalValidator cache and increase its thresholds.

The following sections describe how to implement these optimizations.

Configuring the Active Directory Authentication Provider to Improve Performance

To configure an the Active Directory Authentication provider to use the tokenGroups attribute:

In the left pane of the WebLogic Server Administration Console, expand the Security-->Realms nodes.

Select the name of the realm in which the Active Directory Authentication provider is configured (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the configured Authentication and Identity Assertion providers.

Select the Active Directory Authenticator from the Authenticators table.

Select the Details tab.

Set the following attributes on the Details tab:

Use Token Groups for Group Membership Lookup—Indicates whether to use the Active Directory tokenGroups attribute lookup algorithm instead of the standard recursive group membership lookup algorithm. By default, this attribute is not enabled.

Note: Access to the tokenGroups attribute is required (meaning, the user accessing the LDAP directory must have privileges to read the tokenGroups attribute and the tokenGroups attribute must be in the schema for user objects).

Enable SID to Group Lookup Caching—Indicates whether or not SID to group name lookup results are cached. This attribute only applies if the Use Token Groups for Group Membership Lookup attribute is enabled.
Max SID To Group Lookups In Cache—The maximum size of the Least Recently Used (LRU) cache for holding SID to group lookups. This attribute applies only if both the Use Token Groups for Group Membership Lookup and Enable SID to Group Lookup Caching attributes are enabled.

Click Apply.

Reboot WebLogic Server.

Optimizing the Group Membership Caches

To optimize the group membership caches for WebLogic and LDAP Authentication providers:

In the left pane of the WebLogic Server Administration Console, expand the Security-->Realms nodes.

Select the name of the realm in which the Authentication provider is configured (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the configured Authentication and Identity Assertion providers.

Select the desired Authentication provider.

Select the Details tab.

Set the following attributes on the Details tab:

Group Membership Searching—Controls whether group searches are limited or unlimited in depth. This attribute controls how deeply a search should recursive into nested groups. For configurations that use only the first level of nested group hierarchy, this attribute allows improved performance during user searches by limiting the search to the first level of the group.

If a limited search is specified, the Max Group Membership Search Level attribute must be specified.
If an unlimited search is specified, the Max Group Membership Search Level attribute is ignored.

Max Group Membership Search Level—Controls the depth of a group membership search if the Group Membership Searching attribute is specified. Possible values are:

0—Indicates only direct groups will be found. That is, when searching for membership in Group A, only direct members of Group A will be found. If Group B is a member of Group A, the members will not be found by this search.
Any positive number—Indicates the number of levels to search. For example, if this attribute is set to 1, a search for membership in Group A will return direct members of Group A. If Group B is a member of Group A, the members of Group B will also be found by this search. However, if Group C is a member of Group B, the members of Group C will not be found by this search.

Enable Group Membership Lookup Hierarchy Caching—Indicates whether group membership hierarchies found during recursive membership lookup are cached. Each subtree found will be cached. The cache holds the groups to which a group is a member. This attribute only applies if the Group Membership attribute is enabled. By default, the attribute is disabled.
Max Group Hierarchies in Cache—The maximum size of the Least Recently Used (LRU) cache that holds group membership hierarchies. This attribute only applies if the Enable Group Membership Lookup Hierarchy Caching attribute is enabled.
Group Hierarchy Cache TTL—The number of seconds cached entries stay in the cache. The default is 60 seconds.

Click Apply.

Reboot WebLogic Server.

Configuring Dynamic Groups in the iPlanet Authentication Provider to Improve Performance

Dynamic groups do not list the names of their members. Instead, the membership of the dynamic group is constructed by matching user attributes. Since group membership needs to be computed dynamically for dynamic groups, there is a risk of performance problems for large groups. Configuring the iPlanet Authentication provider appropriately can improve performance where dynamic groups are involved.

In the iPlanet Authentication provider, the User Dynamic Group DN Attribute attribute specifies the attribute of an LDAP user object that specifies the distinguished names (DNs) of dynamic groups to which this user belongs. If such an attribute does not exist, WebLogic Server determines if a user is a member of a group by evaluating the URLs on the dynamic group. By default, User Dynamic Group DN Attribute is null. If you set User Dynamic Group DN Attribute to some other value, to improve performance set the following attributes for the iPlanet Authentication provider:

UserDynamicGroupDNAttribute="wlsMemberOf"

DynamicGroupNameAttribute="cn"

DynamicGroupObjectClass=""

DynamicMemberURLAttribute=""

To set these attributes in the Administration Console:

Expand Security-->Realms-->realm name-->Providers-->Authentication.

On the Users tab for your iPlanet Authentication provider, set User Dynamic Group DN Attribute.

On the Membership tab, set Dynamic Group Object Class and Dynamic Member URL Attribute to null (delete anything in the fields) and leave Dynamic Group Name Attribute set to cn.

Optimizing the Principal Validator Cache

To improve the performance of a WebLogic or LDAP Authentication provider, the settings of the cache used by the WebLogic Principal Validation provider can be increased as appropriate. The Principal Validator cache used by the WebLogic Principal Validation provider caches signed WLSAbstractPrincipals.

To optimize the performance of the Principal Validator cache:

Expand the Security node.

Expand the Realms node.

All the security realms available for the WebLogic domain are listed in the Realms table.

Select the desired security realm.

Select the General tab.

Set the following attributes on the General tab:

Enable WebLogic Principal Validator Cache—Indicates whether the WebLogic Principal Validation provider uses a cache. This attribute only applies if there are Authentication providers configured in the security realm that use the WebLogic Principal Validation provider and WLSAbstractPrincipals. By default, this attribute is enabled.
Max WebLogic Principals In Cache—The maximum size of the Last Recently Used (LRU) cache used for validated WLSAbstractPrincipals. The default setting is 500. This attribute only applies if the Enable WebLogic Principal Validator Cache attribute is enabled.

Click Apply.

Reboot WebLogic Server.

Configuring a Realm Adapter Authentication Provider

The Realm Adapter Authentication provider allows you to use users and groups from 6.x security realms with the security realms in this release of WebLogic Server. Use the Realm Adapter Authentication provider if you store users and groups in the 6.x Windows NT, UNIX, RDBMS security realms or 6.x custom security realm. (There are no equivalents to the 6.x Windows NT, UNIX, RDBMS security realms in this release of WebLogic Server). A Realm Adapter Authentication provider can be configured instead of or in addition to the WebLogic Authentication provider.

When using Compatibility Security, a Realm Adapter Authentication provider is by default configured for the CompatibilityRealm. However, you can configure a Realm Adapter Authentication provider in any security realm. For information about using the Realm Adapter Authentication provider in the CompatibilityRealm, see The Default Security Configuration in the CompatibilityRealm.

The Realm Adapter Authentication provider also allows use of implementations of the weblogic.security.acl.CertAuthenticator class with this release of WebLogic Server. The Realm Adapter Authentication provider includes an Identity Assertion provider which provides identity assertion based on X.509 tokens. For information about using a CertAuthenticator with WebLogic Server, Configuring the Identity Assertion Provider in the Realm Adapter Authentication Provider.

When adding a Realm Adapter Authentication provider to a security realm with an Authentication provider already configured, the WebLogic Server Administration Console sets the Control Flag attribute on the Realm Adapter Authentication provider to OPTIONAL and checks for the presence of a fileRealm.properties file in the domain directory. The WebLogic Server Administration Console will not add the Realm Adapter Authentication provider to the security realm if the fileRealm.properties file does not exist.

Note: The subjects produced by the Realm Adapter Authentication provider do not contain principals for the groups to which a user belongs. Use the weblogic.security.SubjectUtils.isUserInGroup() method to determine whether a user is in a group. When using subjects produced by the Realm Adapter Authentication provider there is no way to iterate the complete set of groups to which a user belongs.

To define attributes for the Realm Adapter Authentication provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

Click the Configure a new Realm Adapter Authenticator... link.

Set the Control Flag attribute on the General tab. The Control Flag attribute determines how the Realm Adapter Authentication provider is used with other Authentication providers. See Setting the JAAS Control Flag Attribute.

Click Apply to save your changes.

Reboot WebLogic Server.

After you reboot, the Compatibility Security tab appears and you have access to the pages in the WebLogic Server Administration Console used to manage the 6.x security realms. Note that you are not running Compatibility security.

Optionally, configure the Identity Assertion provider in the Realm Adapter Authentication provider to use implementations of the weblogic.security.acl.CertAuthenticator class with this release of WebLogic Server. The Identity Assertion provider uses X.509 tokens to perform identity assertion.

Set the Active Type for the Identity Asserter in the Realm Adapter Authentication provider.

In the Available list box, click X.509 to highlight it.

Click the right arrow to move X.509 to the Chosen list box.

Click Apply to save your changes.

Reboot WebLogic Server.

Optionally, configure additional Authentication and/or Identity Assertion providers.

Reboot WebLogic Server.

Configuring a WebLogic Identity Assertion Provider

Note: The WebLogic Server Administration Console refers to the WebLogic Identity Assertion provider as the Default Identity Asserter.

If you are using perimeter authentication, you need to use an Identity Assertion provider. In perimeter authentication, a system outside of WebLogic Server establishes trust via tokens (as opposed to simple authentication, where WebLogic Server establishes trust via usernames and passwords). An Identity Assertion provider verifies the tokens and performs whatever actions are necessary to establish validity and trust in the token. Each Identity Assertion provider is designed to support one or more token formats.

You can use either a WebLogic Identity Assertion provider or a custom Identity Assertion provider in a security realm. This section describes how to configure a WebLogic Identity Assertion provider. For information about configuring a custom security provider (including a custom Identity Assertion provider), see Configuring a Custom Security Provider.

Multiple Identity Assertion providers can be configured in a security realm, but none are required. Identity Assertion providers can support more than one token type, but only one token type per Identity Assertion provider can be active at a given time. When using the WebLogic Identity Assertion provider, configure the active token type. The WebLogic Identity Assertion provider supports identity assertion using X509 certificates and CORBA Common Secure Interoperability version 2 (CSI v2).

If multiple Identity Assertion providers are configured in a security realm, they can all support the same token type. However, one only provider in the security realm can have the token active.

When using the WebLogic Identity Assertion provider in a security realm, you also have the option of using a user name mapper to map the tokens authenticated by the Identity Assertion provider to a user in the security realm. For more information about configuring a user name mapper, see Configuring a User Name Mapper.

To define attributes for the WebLogic Identity Assertion provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

On the Authenticators tab, click the Configure a new Default Identity Asserter... link.

The General tab appears.

Configure a user name mapper. For more information, see Configuring a User Name Mapper or Configuring a Custom User Name Mapper.

In the Trusted Client Principals attribute define the list of client principals that can use CSI v2 identity assertion. You can use an asterisk (*) to specify all client principals. This attribute is only required if you are using CSI v2 identity assertion.

Set the Active Type for the WebLogic Identity Assertion provider. The list of token types supported by the WebLogic Identity Assertion provider is displayed in the Available list box. To set the Active Type:

In the Available list box, select the desired token type.

Click the right arrow to move the token type to the Chosen list box.

Click Apply to save your changes.

Select the Details tab.

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 Base64 Decoded before sending it to the Identity Assertion provider. The setting is enabled by default for purposes of backward compatibility, however, most Identity Assertion providers will disable this attribute.

Click Apply.

Optionally, configure additional Authentication and/or Identity Assertion providers.

Reboot WebLogic Server.

Configuring Identity Assertion Performance in the Server Cache

When using an Identity Assertion provider (either for an X.509 certificate or some other type of token), Subjects (a grouping of related information for a single entity including an identity and its security-related attributes) are cached within the server. This greatly enhances performance for servlets and EJB methods with <run-as> tags as well as for other places where identity assertion is used but not cached in the HTTPSession (for example, signing and encrypting XML documents).

Note: Caching can violate the desired semantics.

You can change the lifetime of items in this cache by setting the maximum number of seconds a Subject can live in the cache via the -Dweblogic.security.identityAssertionTTL command-line argument. The default for this command-line argument is 300 seconds (that is, 5 minutes). Possible values for the command-line argument are:

Less than 0—Disables the cache.
0—Caching is enabled and the identities in the cache never timeout. Any changes in the user database of cached entities requires a server reboot in order for the server to pick them up.
Greater than 0—Caching is enabled and the cache is reset at the specified number of seconds.

To improve the performance of identity assertion, specify a higher value for this command-line argument. Note that as identity assertion performance improves, the Identity Assertion provider is less responsive to changes in the configured Authentication provider. For example, a change in the user's group will not be reflected until the Subject is flushed from the cache and recreated. Setting a lower value for the command-line argument makes authentication changes more responsive at a cost for performance.

Configuring an LDAP X509 Identity Assertion Provider

Note: The configuration of the functionality offered in the LDAP X509 Identity Assertion provider will change in future releases of WebLogic Server. This version of the LDAP X509 Identity Assertion provider is not upward compatible with future releases of WebLogic Server. In addition, the provider has only been tested with the Sun One LDAP server. For information about the usability of the LDAP X509 Identity Assertion provider, see the WebLogic Server Release Notes.

The LDAP X509 Identity Assertion provider receives an X509 certificate, looks up the LDAP object for the user associated with that certificate, ensures that the certificate in the LDAP object matches the presented certificate, and then retrieves the name of the user from the LDAP object.

The LDAP X509 Identity Assertion provider works in the following manner:

An application needs to be set up to use perimeter authentication (in other words, users or system process use tokens to assert their identity). As part of the SSL handshake, the application presents it certificate. The Subject DN in the certificate can be used to locate the object that represents the user in the LDAP server. The object contains the user's certificate and name.

The LDAP X509 Identity Assertion provider uses the certificate in the Subject DN to construct an LDAP search to find the LDAP object for the user in the LDAP server. It gets the certificate from that object, ensures it matches the certificate it holds, and retrieves the name of the user.

The username is passed to the authentication providers configured in the security realm. The authentication providers ensure the user exists and locates the groups to which the user belongs.

Typically, if you use the LDAP X509 Identity Assertion provider, you will also need to configure an LDAP Authentication provider that uses an LDAP server. The authentication provider ensures the user exists and locates the groups to which the user belongs. You should ensure both providers are properly configured to communicate with the same LDAP server.

Using an LDAP X509 Identity Assertion provider involves:

Obtaining certificates for users and putting them in an LDAP Server. There must be a correlation between the Subject DN in the certificate and the location of the object for that user in the LDAP server. The LDAP object for the user must also include attributes for the certificate and the username that will be used in the Subject.

Configuring the LDAP X509 Identity Assertion provider to find the LDAP object for the user in the LDAP directory given the certificate's Subject DN. Basically, the user's DN in LDAP and/or the LDAP object for the user must contain attributes that match values in the certificate's Subject DN.

Example 1: LDAP object matches Subject DN attribute.
Certificate's Subject DN:CN=fred, ou=Acme, c=US.
LDAP DN:
ou=people, cn=flintstone
LDAP Object:
uid=fred, CN=flintstone(username), usercert=cert
Example 2: LDAP DN attribute matches Subject DN component.
Certificate's Subject DN:
DN: CN=fred, ou=Acme, c=US.
LDAP DN:
ou=people, uid=fred
LDAP Object:
SN=flintstone(username), uid=fred,usercert=cert

Configuring the LDAP X509 Identity Assertion provider to search the LDAP server to locate the LDAP object for the user. This requires the following pieces of data.

A base LDAP DN from which to start searching. The Certificate Mapping attribute for the LDAP X509 Identity Assertion provider tells the identity assertion provider how to construct the base LDAP DN from the certificate's Subject DN. The LDAP object must contain an attribute the holds the certificate.
A search filter that only returns LDAP objects that match a defined set of attributes. The filter narrows the LDAP search. Configure the User Filter Search attribute to construct a search filter from the certificate's Subject DN.
Where in the LDAP directory to search for the base LDAP DN. The LDAP X509 Identity Assertion provider searches recursively (one level down). This attribute must match the values of the attributes in the certificate's Subject DN.

Configuring the Certificate attribute of the LDAP X509 Identity Assertion provider to specify which attribute of the LDAP object for the user holds the certificate. The LDAP object must contain an attribute the holds the certificate.

Configuring the Username attribute of the LDAP X509 Identity Assertion provider to specify which of the LDAP object's attributes holds the username that should appear in the Subject DN.

Configuring the LDAP server connection for the LDAP X509 Identity Assertion provider. The LDAP server attribute information should be the same as the information defined for the LDAP Authentication provider configured in this security realm.

Configuring an LDAP Authentication provider for use with the LDAP X509 Identity Assertion provider. The LDAP server attribute information should be the same the information defined for the LDAP X509 Identity Assertion provider configured in Step 6.

To define attributes for the LDAP X509 Identity Assertion provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

On the Authenticators tab, click the Configure a new LDAP X509 Identity Asserter... link.

The General tab appears.

Define name and token information for the LDAP X509 Identity Assertion provider.

The following table lists the attributes you set on the General tab. Table 3-7 Attributes on the General Tab Attribute Description Name The name of this LDAP X509 Identity Assertion provider. Description A short description of this LDAP X509 Identity Assertion provider. Version The version number of this LDAP X509Identity Assertion provider. Supported Types The supported token types of this LDAP X509 Identity Assertion provider. This attribute is always set to X509. Active Types The token type this LDAP X509 Identity Assertion provider uses for authentication. This token type is always set to X509. Ensure no other identity assertion provider configured in the same security realm has this attribute set to X509.

Attribute	Description
Name	The name of this LDAP X509 Identity Assertion provider.
Description	A short description of this LDAP X509 Identity Assertion provider.
Version	The version number of this LDAP X509Identity Assertion provider.
Supported Types	The supported token types of this LDAP X509 Identity Assertion provider. This attribute is always set to X509.
Active Types	The token type this LDAP X509 Identity Assertion provider uses for authentication. This token type is always set to X509. Ensure no other identity assertion provider configured in the same security realm has this attribute set to X509.

Click Apply to save your changes.

Select the Details tab.

Define information about the attributes used to map the username in the LDAP directory to the username the certificate and the LDAP server to be used by the LDAP X509 Identity Assertion provider.

The following table describes the attributes you set on the Details tab.

Note: $subj indicates the Subject attribute in the certificate. For example: CN=meyer.beasys.com, ou=CCE, o=BEASYS, L=SFO, C=US.

Table 3-8 Attributes on the Details Tab

Attribute

Definition

Certificate Mapping

Specifies how to construct the base LDAP DN used to locate the LDAP object for the user. This attribute defines how to find the object from the certificate's Subject DN.

Typically, this value is the same as the User Base DN attribute in the LDAP Authentication providers. You may include the fields from the Subject DN in this base DN.

For example: if the Certificate subject is CN=meyer.beasys.com, ou=fred, o=BEASYS, L=SFO, C=US and the mapping is ou=people, ou=$subj.ou, WebLogic Server uses ou=people, ou=fred, o=BEASYS, c=US as the DN when locating the user.

User Filter Attributes

Specifies how to select the LDAP object for the user from the LDAP objects beneath the base LDAP DN defined in the Certificate Mapping attribute. This attribute defines how to find the LDAP object from the certificate's Subject DN.

The LDAP object's class must be person. This attribute contains an array of strings, each of which is an attribute that the LDAP object must match.

Typically, the value of this attribute is the LDAP object that matches the value of an attribute in the certificate's Subject DN.

For example:

The uid attribute of the LDAP user object matches the Subject DN attribute, if the syntax is:

LDAPATTRNAME=$subj.SUBJECDNATTRNAME

For example: uid=$subj.DN

This attribute is very similar to the User Name Filter attribute on LDAP Authentication providers which maps a username to a search filter. The differences are:

This attribute maps a certificate's Subject DN to a filter and the LDAP Authentication provider uses a single string giving the system administrator complete control over the filter.

The LDAP X509 Authentication provider adds objectclass=person to the filter and uses an array of strings that are combined.

Certificate Attribute

Specifies the attribute on the LDAP object for the user that contains the user's certificate. This attribute defines how to find the certificate. Valid values are userCertificate and userCertificate;binary. The default is userCertificate.

If you use the LDAP browser to load a certificate into the LDAP directory, an attribute userCertificate of type binary is created. To access the certificate, define the Certificate attribute as userCertificate.

If you use ldapmodify to create the new attribute (for example, using the following command):

ldapmodify -p 1155 -D Principal -w Password dn: cn=support@bea.com, ou=Certs, dc=bea, dc=com changetype: modify add: UserCertificate userCertificate;binary:: MIICxDCCAi2gAwIBAgIDIDANbgkqn...
An attribute userCertificate;binary is created when the certificate data is loaded in the LDAP directory. To access the certificate, define the Certificate attribute as userCertificate;binary.

Username Attribute

Specifies the attribute on the LDAP object for the user that contains the user's name. The user's name should appear in the Subject. This attribute defines how to find the user's name.

Typically, this attribute matches the User Name attribute of the LDAP Authentication provider.

Base64 Decoding Required

Determines whether the request header value or cookie value must be Base64 Decoded before sending it to the Identity Assertion provider. The setting is enabled by default for purposes of backward compatibility, however, most Identity Assertion providers will disable this attribute.

Host

The host name of the computer on which the LDAP server is running.

Port

The port number on which the LDAP server is listening. If you want WebLogic Server to connect to the LDAP server using the SSL protocol, use the LDAP server's SSL port in this attribute.

SSL Enabled

Option for enabling the SSL protocol to protect communications between the LDAP server and WebLogic Server. Disable this attribute if the LDAP server is not configured to use the SSL protocol.

Principal

The Distinguished name (DN) of the LDAP user used by WebLogic Server to connect to the LDAP server. Generally, this user is the system administrator of the LDAP directory server. If you want to change passwords, this attribute must be the system administrator.

Credential

Password that authenticates the LDAP user defined in the Principal attribute.

Cache Enabled

Enables the use of a data cache with the LDAP server.

Cache Size

Maximum size of lookups in cache. The default is 32kb.

Cache TTL

Number of seconds to retain the results of an LDAP lookup.

Follow Referrals

Specifies that a search for a user or group within the LDAP X509 Identity Assertion provider will follow referrals to other LDAP servers or branches within the LDAP directory. By default, this attribute is enabled.

Bind Anonymously On Referrals

By default, the LDAP X509 Identity Assertion provider uses the same DN and password used to connect to the LDAP server when following referrals during a search. If you want to connect as an anonymous user, enable this attribute. Contact your LDAP system administrator for more information.

Results Time Limit

The maximum number of milliseconds for the LDAP server to wait for results before timing out. If this attribute is set to 0, there is not maximum time limit. The default is 0.

Connect Timeout

The maximum time in seconds to wait for the connection to the LDAP server to be established. If this attribute is set to 0, there is not a maximum time limit. The default is 0.

Parallel Connect Delay

The delay in seconds when making concurrent attempts to attempt to multiple LDAP servers. If this attribute is set to 0, connection attempts are serialized. An attempt is made to connect to the first server in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. If this attribute is not set and an LDAP server is unavailable, an application may be blocked for a long time. If this attribute is greater than 0, another connection is started after the specified time.

Attribute	Definition
Certificate Mapping	Specifies how to construct the base LDAP DN used to locate the LDAP object for the user. This attribute defines how to find the object from the certificate's Subject DN. Typically, this value is the same as the User Base DN attribute in the LDAP Authentication providers. You may include the fields from the Subject DN in this base DN. For example: if the Certificate subject is `CN=meyer.beasys.com, ou=fred, o=BEASYS, L=SFO, C=US` and the mapping is `ou=people, ou=$subj.ou,` WebLogic Server uses `ou=people, ou=fred, o=BEASYS, c=US` as the DN when locating the user.
User Filter Attributes	Specifies how to select the LDAP object for the user from the LDAP objects beneath the base LDAP DN defined in the Certificate Mapping attribute. This attribute defines how to find the LDAP object from the certificate's Subject DN. The LDAP object's class must be person. This attribute contains an array of strings, each of which is an attribute that the LDAP object must match. Typically, the value of this attribute is the LDAP object that matches the value of an attribute in the certificate's Subject DN. For example: The `uid` attribute of the LDAP user object matches the Subject DN attribute, if the syntax is: `LDAPATTRNAME=$subj.SUBJECDNATTRNAME` For example: `uid=$subj.DN` This attribute is very similar to the User Name Filter attribute on LDAP Authentication providers which maps a username to a search filter. The differences are: This attribute maps a certificate's Subject DN to a filter and the LDAP Authentication provider uses a single string giving the system administrator complete control over the filter. The LDAP X509 Authentication provider adds `objectclass=person` to the filter and uses an array of strings that are combined.
Certificate Attribute	Specifies the attribute on the LDAP object for the user that contains the user's certificate. This attribute defines how to find the certificate. Valid values are `userCertificate` and u`serCertificate;binary.` The default is `userCertificate`. If you use the LDAP browser to load a certificate into the LDAP directory, an attribute `userCertificate` of type binary is created. To access the certificate, define the Certificate attribute as `userCertificate.` If you use `ldapmodify` to create the new attribute (for example, using the following command): `ldapmodify -p 1155 -D Principal -w Password dn: cn=support@bea.com, ou=Certs, dc=bea, dc=com changetype: modify add: UserCertificate userCertificate;binary:: MIICxDCCAi2gAwIBAgIDIDANbgkqn...` An attribute `userCertificate;binary` is created when the certificate data is loaded in the LDAP directory. To access the certificate, define the Certificate attribute as `userCertificate;binary.`
Username Attribute	Specifies the attribute on the LDAP object for the user that contains the user's name. The user's name should appear in the Subject. This attribute defines how to find the user's name. Typically, this attribute matches the User Name attribute of the LDAP Authentication provider.
Base64 Decoding Required	Determines whether the request header value or cookie value must be Base64 Decoded before sending it to the Identity Assertion provider. The setting is enabled by default for purposes of backward compatibility, however, most Identity Assertion providers will disable this attribute.
Host	The host name of the computer on which the LDAP server is running.
Port	The port number on which the LDAP server is listening. If you want WebLogic Server to connect to the LDAP server using the SSL protocol, use the LDAP server's SSL port in this attribute.
SSL Enabled	Option for enabling the SSL protocol to protect communications between the LDAP server and WebLogic Server. Disable this attribute if the LDAP server is not configured to use the SSL protocol.
Principal	The Distinguished name (DN) of the LDAP user used by WebLogic Server to connect to the LDAP server. Generally, this user is the system administrator of the LDAP directory server. If you want to change passwords, this attribute must be the system administrator.
Credential	Password that authenticates the LDAP user defined in the Principal attribute.
Cache Enabled	Enables the use of a data cache with the LDAP server.
Cache Size	Maximum size of lookups in cache. The default is 32kb.
Cache TTL	Number of seconds to retain the results of an LDAP lookup.
Follow Referrals	Specifies that a search for a user or group within the LDAP X509 Identity Assertion provider will follow referrals to other LDAP servers or branches within the LDAP directory. By default, this attribute is enabled.
Bind Anonymously On Referrals	By default, the LDAP X509 Identity Assertion provider uses the same DN and password used to connect to the LDAP server when following referrals during a search. If you want to connect as an anonymous user, enable this attribute. Contact your LDAP system administrator for more information.
Results Time Limit	The maximum number of milliseconds for the LDAP server to wait for results before timing out. If this attribute is set to 0, there is not maximum time limit. The default is 0.
Connect Timeout	The maximum time in seconds to wait for the connection to the LDAP server to be established. If this attribute is set to 0, there is not a maximum time limit. The default is 0.
Parallel Connect Delay	The delay in seconds when making concurrent attempts to attempt to multiple LDAP servers. If this attribute is set to 0, connection attempts are serialized. An attempt is made to connect to the first server in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. If this attribute is not set and an LDAP server is unavailable, an application may be blocked for a long time. If this attribute is greater than 0, another connection is started after the specified time.

Click Apply.

Optionally, configure additional Authentication and/or Identity Assertion providers.

Reboot WebLogic Server.

Configuring a Single Pass Negotiate Identity Assertion Provider

Note: This version of the Single Pass Negotiate Identity Assertion provider is not upward compatible with future releases of WebLogic Server.

The Single Pass Negotiate Identity Assertion provider enables single sign-on (SSO) with Microsoft clients. The identity assertion provider decodes Simple and Protected Negotiate (SPNEGO) tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users. The Single Pass Negotiate Identity Assertion provider utilizes the Java Generic Security Service (GSS) Application Programming Interface (API) to accept the GSS security context via Kerberos.

The Single Pass Negotiate Identity Assertion provider is an implementation of the Security Service Provider Interface (SSPI) as defined by the WebLogic Security Framework and provides the necessary logic to authenticate a client based on the client's SPNEGO token.

For information about using the Single Pass Negotiate Identity Assertion provider with Microsoft SSO, see [xref].

To configure a Single Pass Negotiate Identity Assertion provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

The Authenticators table displays the name of the default Authentication and Identity Assertion providers.

On the Authenticators tab, click the Configure a new Single Pass Negotiate Identity Asserter... link.

The General tab appears.

Define name and token information for the Single Pass Negotiate Identity Assertion provider.

The following table lists the attributes you set on the General tab. Table 3-9 Attributes on the General Tab Attribute Description Name The name of this Single Pass Negotiate Identity Assertion provider. Description A short description of this Single Pass Negotiate Identity Assertion provider. Version The version number of this Single Pass Negotiate Identity Assertion provider. Active Types Chooser The token type this Single Pass Negotiate Identity Assertion provider uses for authentication. This token type is always set to Authorization. Ensure no other identity assertion provider configured in the same security realm has this attribute set to Authorization.

Attribute	Description
Name	The name of this Single Pass Negotiate Identity Assertion provider.
Description	A short description of this Single Pass Negotiate Identity Assertion provider.
Version	The version number of this Single Pass Negotiate Identity Assertion provider.
Active Types Chooser	The token type this Single Pass Negotiate Identity Assertion provider uses for authentication. This token type is always set to Authorization. Ensure no other identity assertion provider configured in the same security realm has this attribute set to Authorization.

Click Apply to save your changes.

Select the Details tab.

Ensure the Base64 Decoding Required attribute is checked.

Click Apply.

Optionally, configure additional Authentication and/or Identity Assertion providers.

Reboot WebLogic Server.

Ordering of Identity Assertion for Servlets

When an HTTP request is sent, there may be multiple matches that can be used for identity assertion. However, identity assertion providers can only consume one of the active token types at a time. As a result there is no way to provide a set of tokens that can be consumed with one call. Therefore, the servlet contained in WebLogic Server is forced to choose between multiple tokens to perform identity assertion. The following ordering is used:

An X.590 digital certificate (signifies two-way SSL to client or proxy plug-in with two-way SSL between the client and the Web server) if X.509 is one of the active token types configured for the Identity Assertion provider in the default security realm.

Headers with a name in the form WL-Proxy-Client-<TOKEN> where <TOKEN> is one of the active token types configured for the Identity Assertion provider in the default security realm.

Note: This method is deprecated and should only be used for the purpose of backward compatibility.

Headers with a name in the form <TOKEN> where <TOKEN> is one of the active tokens types configured for the Identity Assertion provider in the default security realm.

Cookies with a name in the form <TOKEN> where <TOKEN> is one of the active tokens types configured for the Identity Assertion provider in the default security realm.

For example, if an Identity Assertion provider in the default security realm is configured to have the FOO and BAR tokens as active token types (for the following example, assume the HTTP request contains nothing relevant to identity assertion except active token types), identity assertion is performed as follows:

If a request comes in with a FOO header over a two-way SSL connection then X.509 is used for identity assertion.
If a request comes in with a FOO header and a WL-Proxy-Client-BAR header then the BAR token is used for identity assertion.
If a request comes in with a FOO header and a BAR cookie then the FOO token will be used for identity assertion.

The ordering between multiple tokens at the same level is undefined, therefore:

If a request comes in with a FOO header and a BAR header, then either the FOO or BAR token is used for identity assertion, however, which one is used is unspecified.
If a request comes in with a FOO cookie and a BAR cookie, then either the FOO or BAR token is used for identity assertion, however, which one is used is unspecified.

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 multipart authentication. Authentication providers are called in the order in which they are configured. The Authentication Providers table lists the authentication providers in the order they were configured. Click the Re-order the Configured Authentication Providers... link to change the order of the providers. Be aware that the way each Authentication provider's Control Flag attribute is set affects the outcome of the authentication process. For more information, see Setting the JAAS Control Flag Attribute.

To change the ordering of Authentication providers:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

Click the Re-order the Configured Authentication Providers... link.

Select an Authentication provider from the list of configured Authentication providers to highlight it.

Use the arrow buttons to move the Authentication provider up or down in the list.

Click Apply to save your changes.

Reboot WebLogic Server.

Configuring a User Name Mapper

WebLogic Server verifies the digital certificate of the Web browser or Java client when establishing a two-way SSL connection. However, the digital certificate does not identify the Web browser or Java client as a user in the WebLogic Server security realm. If the Web browser or Java client requests a WebLogic Server resource protected by a security policy, WebLogic Server requires the Web browser or Java client to have an identity. The WebLogic Identity Assertion provider allows you to enable a user name mapper that maps the digital certificate of a Web browser or Java client to a user in a WebLogic Server security realm.

The user name mapper must be an implementation of the weblogic.security.providers.authentication.UserNameMapper interface. This interface maps a token to a WebLogic Server user name according to whatever scheme is appropriate for your needs. By default, WebLogic Server provides a default implementation of the weblogic.security.providers.authentication.UserNameMapper interface. You can also write your own implementation.

The WebLogic Identity Assertion provider calls the user name mapper for the following types of identity assertion token types:

X.509 digital certificates passed via the SSL handshake
X.509 digital certificates passed via CSIv2
X.501 distinguished names passed via CSIv2

The default user name mapper uses the attributes from the subject DN of the digital certificate or the distinguished name to map to the appropriate user in the WebLogic Server security realm. For example, the user name mapper can be configured to map a user from the Email attribute of the subject DN (smith@bea.com) to a user in the WebLogic Server security realm (smith).

To use the default user name mapper:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

Select the Default Identity Assertion provider.

Select the Details tab.

Check the Use the Default User Name Mapper attribute to enable the user name mapper.

Specify the following attributes:

Default User Name Mapper Attribute Type—The attribute of the subject distinguished name (DN) in a digital certificate used to create a username. Valid values are: C, CN, E, L, O, and OU.
Default User Name Mapper Attribute Delimiter—The attribute that ends the username. The user name mapper uses everything to the left of the attribute to create a username.

Click Apply.

Reboot WebLogic Server.

Configuring a Custom User Name Mapper

You can also write a custom user name mapper to map a token to a WebLogic Server user name according to whatever scheme is appropriate for your needs. The custom user name mapper must be an implementation of the weblogic.security.providers.authentication.UserNameMapper interface.

To install a custom user name mapper:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers-->Authentication Providers nodes.

Select the Default Identity Assertion provider.

Select the General tab.

Enter the class name of the implementation of the weblogic.security.providers.authentication.UserNameMapper interface in the User Name Mapper Class Name attribute.

Click Apply.

Reboot WebLogic Server.

Configuring a WebLogic Authorization Provider

Authorization is the process whereby the interactions between users and resources are limited to ensure integrity, confidentiality, and availability. In other words, authorization is responsible for controlling access to resources based on user identity or other information.

You can use either a WebLogic Authorization provider or a custom Authorization provider in a security realm. This section describes how to configure a WebLogic Authorization provider. For information about configuring a custom security provider (including a custom Authorization provider), see Configuring a Custom Security Provider.

To configure a WebLogic Authorization provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers node.

Click Authorizers.

The Authorizers table displays the name of the default Authorization provider for the realm that is being configured.

Click the Configure a new Default Authorizer... link.

Define values for the attributes on the General tab.

The Policy Deployment Enabled attribute specifies whether or not this Authorization provider stores policy information (as opposed to retrieving policy information) for the security realm. In order to support the Policy Deployment Enabled attribute, an Authorization provider must implement the DeployableAuthorizationProvider Security Service Provider Interface (SSPI). By default, the WebLogic Authorization provider has this attribute enabled. The policy information is stored in the embedded LDAP server.

Click Apply to save your changes.

Reboot WebLogic Server.

Note: The WebLogic Authorization provider improves performance by caching the roles, predicates, and resource data that it looks up. For information on configuring these caches, see Best Practices: Configure Entitlements Caching When Using WebLogic Providers in Securing WebLogic Resources.

Configuring a WebLogic Credential Mapping Provider

Credential mapping is the process whereby the authentication and authorization mechanisms of a remote system (for example, a legacy system or application) are used to obtain an appropriate set of credentials to authenticate users to a target WebLogic resource.

For information about creating credential maps, see Single Sign-On with Enterprise Information Systems, and the Security topic in Programming WebLogic J2EE Connectors.

You can use either a WebLogic Credential Mapping provider or a custom Credential Mapping provider in a security realm. This section describes how to configure a WebLogic Credential Mapping provider. For information about configuring a custom security provider (including a custom Credential Mapping provider), see Configuring a Custom Security Provider.

To configure a WebLogic Credential Mapping provider:

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Expand the Providers node.

Select Credential Mappers.

Click the Configure a new Default Credential Mapper... link.

On the General tab, set the Credential Mapping Deployment Enabled attribute.

The Credential Mapping Deployment Enabled attribute specifies whether or not this Credential Mapping provider imports credential maps from deployment descriptors (weblogic-ra.xml files) into the security realm. In order to support the Credential Mapping Deployment Enabled attribute, a Credential Mapping 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.
For more information, see Implementing the DeployableCredentialMappingProvider SSPI in Developing Security Services for WebLogic Server.

Click Apply to save your changes.

Reboot WebLogic Server.

Configuring a WebLogic Keystore Provider

Note: The WebLogic Keystore provider is deprecated in this release of WebLogic Server. It is only supported for backward compatibility. For more information about using a WebLogic Keystore provider, see Configuring SSL.

Configuring a WebLogic Role Mapping Provider

Role Mapping providers compute the set of roles granted to a subject for a given resource. Role Mapping providers supply Authorization providers with this role information so that the Authorization Provider can answer the "is access allowed?" question for WebLogic resources.

You can use either a WebLogic Role Mapping provider or a custom Role Mapping provider in a security realm. This topic describes how to configure a WebLogic Role Mapping provider. For information about configuring a custom security provider (including a custom Role Mapping provider), see Configuring a Custom Security Provider.

To configure an Role Mapping provider:

In the left pane of the WebLogic Server Administration Console. expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm).

Click the Providers node.

Click Role Mappers.

The Role Mappers table appears. This table displays the name of the default Role Mapping provider for the realm that is being configured.

Click the Configure a new Default Role Mapper... link.

The General tab appears.

Define values for the attributes on the General tab.

The Role Mapping Deployment Enabled attribute specifies whether or not this Role Mapping provider imports information from deployment descriptors for Web applications and EJBs into the security realm. In order to support the Role Mapping Deployment Enabled attribute, a Role Mapping provider must implement the DeployableRoleProvider SSPI. By default, the WebLogic Role Mapping provider has this attribute enabled. Roles are stored in the embedded LDAP server.
For more information, see Role Mapping Providers in Developing Security Services for WebLogic Server.

Click Apply to save your changes.

Reboot WebLogic Server.

Note: The WebLogic Role Mapping provider improves performance by caching the roles, predicates, and resource data that it looks up. For information on configuring these caches, see Best Practices: Configure Entitlements Caching When Using WebLogic Providers in Securing WebLogic Resources.

Configuring a Custom Security Provider

To configure a custom security provider:

Write a custom security provider. For more information, see Developing Security Providers for WebLogic Server.

Put the MBean JAR file for the provider in the WL_HOME\lib\mbeantypes directory.

Start the WebLogic Server Administration Console.

Expand the Security-->Realms nodes.

Select the name of the realm you are configuring (for example, TestRealm.)

Expand the Providers node.

Expand the node for the type of provider you are configuring. For example, expand the Authenticator node to configure a custom Authentication provider.

The tab for the provider appears.

Click the Configure a new custom Security_Provider_Type... link

where Security_Provider_Type is the name of your custom security provider. This name is read from the DisplayName attribute in the MBeanType tag of the MBean Definition File (MDF).

The General tab appears.

The Name attribute displays the name of your custom Security provider.

If desired, adjust the values for the attributes for the custom Security provider.

Click Apply to save your changes.

Reboot WebLogic Server.

Note: A Common Criteria certified configuration must not include any custom security providers. For information about the configuration of BEA WebLogic Server certified through the Common Criteria evaluation and validation process, see the product listing in the Validated Products section of the National Information Assurance Partnership Web site at http://niap.nist.gov/ . Information about the configuration of a product in evaluation is not publicly available. Such information is publicly available for validated products only.

Deleting a Security Provider

To delete a security provider:

Expand the Security-->Realms nodes.

Select the name of the realm in which the provider you want to delete is configured (for example, TestRealm).

Expand the Providers node.

Select the type of provider you want to delete (for example, TestRealm-->Authorizers).

The table page for the provider appears (for example, the Authorizers table). The table page for the provider displays the names of all the configured providers.

To delete a provider, click on the trash can icon in the provider table.

Reboot WebLogic Server.

Note: Deleting and modifying configured security providers by using the WebLogic Server Administration Console may require manual clean up of the security provider database.