5 Configuring Authentication Providers

WebLogic Server includes numerous Authentication security providers. Most of them work in similar fashion: given a username and password credential pair, the provider attempts to find a corresponding user in the provider's data store. These Authentication providers differ primarily in what they use as a data store: one of many available LDAP servers, a SQL database, or other data store. In addition to these username/password based security providers, WebLogic Server includes identity assertion Authentication providers, which use certificates or security tokens, rather than username/password pairs, as credentials.

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

Choosing an Authentication Provider

Authentication is the process whereby the identity of users and 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: password-based and 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.

WebLogic Server offers the following types of Authentication providers:

  • The WebLogic Authentication provider, also known as the DefaultAuthenticator, accesses user and group information in WebLogic Server's embedded LDAP server.

  • The Oracle Internet Directory Authentication provider accesses users and groups in Oracle Internet Directory, an LDAP version 3 directory.

  • The Oracle Virtual Directory Authentication provider accesses users and groups in Oracle Virtual Directory, an LDAP version 3 enabled service.

  • LDAP Authentication providers access external LDAP stores. You can use an LDAP Authentication provider to access any LDAP server. WebLogic Server provides LDAP Authentication providers already configured for Open LDAP, Sun iPlanet, Microsoft Active Directory, and Novell NDS LDAP servers.

  • RDBMS Authentication providers access external relational databases. WebLogic Server provides three RDBMS Authentication providers: SQL Authenticator, Read-only SQL Authenticator, and Custom RDBMS Authenticator.

  • The WebLogic Identity Assertion provider validates X.509 and IIOP-CSIv2 tokens and optionally can use a user name mapper to map that token to a user in a WebLogic Server security realm.

  • The SAML Authentication provider, which authenticates users based on Security Assertion Markup Language 1.1 (SAML) assertions.

  • The Negotiate Identity Assertion provider, which uses Simple and Protected Negotiate (SPNEGO) tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users.

  • The SAML Identity Assertion provider, which acts as a consumer of SAML security assertions. This enables WebLogic Server to act as a SAML destination site and supports using SAML for single sign-on.

In addition, you can use:

  • Custom (non-WebLogic) Authentication providers, which offer different types of authentication technologies.

  • Custom (non-WebLogic) Identity Assertion providers, which support different types of tokens.

Using More Than One Authentication Provider

Each security realm must have at least one Authentication provider configured. The WebLogic Security Framework supports 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.

How you configure multiple Authentication providers can affect the overall outcome of the authentication process. Configure the JAAS Control Flag for each Authentication provider to set up login dependencies between Authentication providers and allow single-sign on between providers. See Setting the JAAS Control Flag Option.

Authentication providers are called in the order in which they were configured in the security realm. Therefore, use caution when configuring Authentication providers. You can use the WebLogic Administration Console to re-order the configured Authentication providers, thus changing the order in which they are called. See Changing the Order of Authentication Providers.

Setting the JAAS Control Flag Option

When you configure multiple Authentication providers, use the JAAS Control Flag for each provider to control how the Authentication providers are used in the login sequence. You can set the JAAS Control Flag in the WebLogic Administration Console. See "Set the JAAS control flag" in the Oracle WebLogic Server Administration Console Help. You can also use the WebLogic Scripting Tool or Java Management Extensions (JMX) APIs to set the JAAS Control Flag for an Authentication provider.

JAAS Control Flag values are:

  • REQUIRED—The Authentication provider is always called, and the user must always pass its authentication test. Regardless of whether authentication succeeds or fails, authentication still continues down the list of providers.

  • REQUISITE—The user is required to pass the authentication test of this Authentication provider. If the user passes the authentication test of this Authentication provider, subsequent providers are executed but can fail (except for Authentication providers with the JAAS Control Flag set to REQUIRED).

  • SUFFICIENT—The user is not required to pass the authentication test of the Authentication provider. If authentication succeeds, no subsequent Authentication providers are executed. If authentication fails, authentication continues down the list of providers.

  • 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 is set to OPTIONAL. If necessary, change the setting of the Control Flag and the order of Authentication providers so that each Authentication provider works properly in the authentication sequence.

Note:

As part of the startup process, WebLogic Server must be able to initialize all security providers that are configured in the security realm, including any Authentication providers that have a JAAS Control Flag set to OPTIONAL. If the initialization process for any security provider cannot be completed, WebLogic Server fails to boot, and an error message similar to the following is displayed:
<BEA-090870> <The realm "myrealm" failed to be loaded:

Changing the Order of Authentication Providers

The order in which WebLogic Server calls multiple Authentication providers can affect the overall outcome of the authentication process. The Authentication Providers table lists the authentication providers in the order in which they will be called. By default, Authentication providers are called in the order in which they were configured. You can use the Administration Console to change the order of Authentication providers. Select the Reorder button on the Security Realms > RealmName > Providers > Authentication page in the Administration Console to change the order in which Authentication providers are called by WebLogic Server and listed in the console.

See "Re-order Authentication Providers" in the Oracle WebLogic Server Administration Console Help.

Configuring the WebLogic Authentication Provider

The WebLogic Authentication provider (also called the DefaultAuthenticator) uses WebLogic Server's embedded LDAP server to store user and group membership information and, optionally, a set of user attributes such as phone number, email address, and so on. This provider allows you to create, modify, list, and manage users and group membership in the WebLogic Server Administration Console. By default, most configuration options for the WebLogic Authentication provider are already defined. You should need to configure a WebLogic Authentication provider only when creating a new security realm. However, note the following:

  • The WebLogic Authentication provider is configured in the default security realm with the name DefaultAuthenticator.

  • User and group names in the WebLogic Authentication provider are case insensitive. For information about creating and managing users and groups in the WebLogic Server Administration Console, see "Manage users and groups" in the Oracle WebLogic Server Administration Console Help.

  • Ensure that all user names are unique.

  • Specify the minimum length of passwords defined for users that are stored in the embedded LDAP server, which you can by means of the Minimum Password Length option that is available on the Configuration > Provider Specific page for the WebLogic Authentication provider.

  • Users in the WebLogic Authentication provider can be modified to include a set of attributes. See Setting User Attributes.

  • If you are using multiple Authentication providers, set the JAAS Control Flag to determine how the WebLogic Authentication provider is used in the authentication process. See Using More Than One Authentication Provider.

Setting User Attributes

After you have defined a user in the WebLogic Authentication provider, you can set or modify for that user one more of the attributes listed in Table 5-1. These attributes conform to the user schema for representing individuals in the inetOrgPerson LDAP object class, described in RFC 2798.

Table 5-1 Attributes that Can Be Set for a User

Attribute Description
c

Two-letter ISO 3166 country code

departmentnumber

Code for department to which the user belongs

displayname

Preferred name of the user

employeenumber

Numeric or alphanumeric identifier assigned to the user

employeetype

Type of employment, which represents the employer to employee relationship

facsimiletelephonenumber

Facsimile (fax) telephone number

givenname

First name; that is, not surname (last name) or middle name

homephone

Home telephone number

homepostaladdress

Home postal address

l

Name of a locality, such as a city, county or other geographic region

mail

Electronic address of user (email)

mobile

Mobile telephone number

pager

Pager telephone number

postaladdress

Postal address at location of employment

postofficebox

Post office box

preferredlanguage

User's preferred written or spoken language

st

Full name of state or province

street

Physical location of user

telephonenumber

User's telephone number in organization

title

Title representing user's job function


When you set a value for an attribute, the attribute is added for the user. Likewise, if you subsequently delete the value of an attribute, the attribute is removed for the user. The set of available attributes is limited to the preceding list, however. The attribute names cannot be customized.

These attributes can be managed for a user by operations on the UserAttributeEditorMBean, or viewed via operations on the UserAttributeReaderMBean.

For more information about setting, modifying, or viewing the attributes for a user created in the WebLogic Authentication provider, see "Manage values for user attributes" in Oracle WebLogic Server Administration Console Help.

Configuring LDAP Authentication Providers

This section includes the following topics:

LDAP Authentication Providers Included in WebLogic Server

WebLogic Server includes the following LDAP Authentication providers:

  • Oracle Internet Directory Authentication provider

  • Oracle Virtual Directory Authentication provider

  • iPlanet Authentication provider

  • Active Directory Authentication provider

  • Open LDAP Authentication provider

  • Novell Authentication provider

  • generic LDAP Authentication provider

Each LDAP Authentication provider stores user and group information in an external LDAP server. They differ primarily in how they are configured by default to match typical directory schemas for their corresponding LDAP server. For information about configuring the Oracle Internet Directory and Oracle Virtual Directory Authentication providers to match the LDAP schema for user and group attributes, see Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers.

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:

  • Oracle Internet Directory

  • Oracle Virtual Directory

  • Sun 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

An LDAP Authentication provider can also be used to access other LDAP servers. However, you must either use the LDAP Authentication provider (LDAPAuthenticator) or choose a pre-defined LDAP provider and customize it. See Accessing Other LDAP Servers.

Note:

The Active Directory Authentication provider also supports Microsoft Active Directory Application Mode (ADAM) as a standalone directory server.

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, if one does not already exist. 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 Group Base Distinguished Name (DN) 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 Administration Console, assign that group the Admin role.

Note:

If the LDAP user who boots WebLogic Server is not properly added to a group that is assigned to the Admin role, and the LDAP authentication provider is the only authentication provider with which the security realm is configured, WebLogic Server cannot be booted.

Configuring an LDAP Authentication Provider: Main Steps

To configure an LDAP Authentication provider:

  1. Choose an LDAP Authentication provider that matches your LDAP server and create an instance of the provider in your security realm. For information, see the following topics:

  2. Configure the provider-specific attributes of the LDAP Authentication provider, which you can do through the Administration Console. For each LDAP Authentication provider, attributes are available to:

    1. Enable communication between the LDAP server and the LDAP Authentication provider. For a more secure deployment, Oracle recommends using the SSL protocol to protect communications between the LDAP server and WebLogic Server. Enable SSL with the SSLEnabled attribute.

    2. Configure options that control how the LDAP Authentication provider searches the LDAP directory.

      Note:

      The value you enter for principal must be an LDAP administrator who has the privilege to search users and groups in the corresponding LDAP server. If the LDAP administrator does not have privileges to search the LDAP server, an LDAP exception with error code 50 is generated.
    3. Specify where in the LDAP directory structure users are located.

    4. Specify where in the LDAP directory structure groups are located.

      Note:

      When specifying an LDAP search filter for users or groups using the following LDAPAuthenticatorMBean attributes, wildcards are accepted but they can have a negative performance impact on the LDAP server, particularly if you use a combination of them:
      • AllUsersFilter

      • UserFromNameFilter

      • AllGroupsFilter

      • GroupFromNameFilter

      For example, the following filter expression combines five wildcarded conditions, each condition using two asterisk wildcard characters:

      (|(cn=*wall*)(givenname=*wall*)(sn=*wall*)(cn=*wall*)(mail=*wall*))
      

      The preceding example filter would likely cause an unacceptable overhead on the corresponding LDAP server.

    5. Define how members of a group are located.

    6. Set the name of the global universal identifier (GUID) attribute defined in the LDAP server.

      Note:

      If you are configuring either the Oracle Internet Directory or Oracle Virtual Directory Authentication provider, see Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers. This section explains how to match the authentication provider attributes for users and groups to the LDAP directory structure.
    7. Set timeout values for the connection to the LDAP server. You can specify two timeout values: a connection timeout, and a socket timeout.

      The connection timeout, specified in the LDAPServerMBean.ConnectTimeout attribute for all LDAP Authentication providers, has a default value of zero. This default setting specifies no timeout limit, and can result in a slowdown in WebLogic Server execution if the LDAP servers configured for an LDAP Authentication provider are unavailable. In addition, if WebLogic Server has multiple LDAP Authentication providers configured, the failure to connect to one LDAP server may block the use of the other LDAP Authentication providers.

      Oracle recommends that you set the LDAPServerMBean.ConnectTimeout attribute on the LDAP Authentication provider to a non-zero value; for example, 60 seconds. You can set this value via either the WebLogic Server Administration Console or WLST. You can also set this value in the config.xml file by adding the following configuration parameter for the LDAP Authentication provider:

      <wls:connect-time>60</wls:connect-time>
      

      Note:

      Oracle recommends that you do not edit the config.xml file directly.

      The socket timeout, specified in the -Dweblogic.security.providers.authentication.ldap.socketTimeout JVM configuration option, sets the timeout in seconds for connecting to any one LDAP server specified in the LDAPServerMBean.Host attribute. The default value of the socket timeout is 0, which sets no socket timeout on the connection.

      For information about the appropriate values to set for the connection timeout and socket timeout values for an LDAP Authentication provider, see Configuring Failover for LDAP Authentication Providers.

  3. Configure performance options that control the cache for the LDAP server. Use the Configuration > Provider Specific and Performance pages for the provider in the Administration Console to configure the cache. See Improving the Performance of WebLogic and LDAP Authentication Providers.

Note:

If the LDAP Authentication provider fails to connect to the LDAP server, or throws an exception, check the configuration of the LDAP Authentication provider to make sure it matches the corresponding settings in the LDAP server.

For more information, see:

Accessing Other LDAP Servers

The LDAP Authentication providers in this release of WebLogic Server are configured to work readily with the Oracle Internet Directory, Oracle Virtual Directory, SunONE (iPlanet), Active Directory, Open LDAP, and Novell NDS LDAP servers. You can use an LDAP Authentication provider to access other types of LDAP servers. Choose either the LDAP Authentication provider (LDAPAuthenticator) or the existing LDAP provider that most closely matches the new LDAP server and customize the existing configuration to match the directory schema and other attributes for your LDAP server.

If you are using Active Directory, see Following Referrals in the Active Directory Authentication Provider.

Enabling an LDAP Authentication Provider for SSL

If you want to secure the connection between WebLogic Server and the LDAP server — for example, because the LDAP server requires it — you must do the following:

  • Create and configure a custom trust keystore for use with the LDAP server

  • Specify that the SSL protocol should be used by the LDAP Authentication provider when connecting to the LDAP server

To do this, complete the following steps:

  1. Configure the LDAP Authentication provider. Make sure you select SSLEnabled on the Configuration > Provider Specific page.

  2. Obtain the root certificate authority (CA) certificate for the LDAP server.

  3. Create a trust keystore using the preceding certificate. For example, the following example shows using the keytool command to create the keystore ldapTrustKS with the root CA certificate rootca.pem.:

    keytool -import -keystore ./ldapTrustKS -trustcacerts -alias oidtrust -file rootca.pem -storepass TrustKeystorePwd -noprompt
    

    For more information about creating a trust keystore, see Chapter 11, "Configuring Identity and Trust".

  4. Copy the keystore to a location from which WebLogic Server has access.

  5. Start the WebLogic Server Administration Console and navigate to the server-name > Configuration > Keystores page, where server-name is the WebLogic Server instance for which you are configuring this keystore.

  6. If necessary, in the Keystores field, click Change to select the Custom Identity and Custom Trust configuration rules.

  7. If the communication with the LDAP server uses 2-way SSL, configure the custom identity keystore, keystore type, and passphrase.

  8. In Custom Trust Keystore, enter the path and file name of the trust keystore created in step 2.

  9. In Custom Trust Keystore Type, enter jks.

  10. In Custom Trust Keystore Passphrase, enter the password used when creating the keystore.

  11. Reboot the WebLogic Server instance for changes to take effect.

For more information, see Chapter 12, "Configuring SSL". For more information about using the WebLogic Server Administration Console to configure keystores and enable SSL, see the following topics in the Oracle WebLogic Server Administration Console Help:

Dynamic Groups and WebLogic Server

Many LDAP servers have a concept of dynamic groups or virtual groups. These are groups that, rather than consisting of a list of users and groups, contain some policy statements, queries, or code that define the set of users that belong to the group. Even if a group is marked dynamic, users must log out and log back in before any changes in their group memberships take effect. The term dynamic describes the means of defining the group and not any runtime semantics of the group within WebLogic Server.

Use of GUID and LDAP DN Data in WebLogic Principals

When a user is authenticated into WebLogic Server, an authentication provider creates a Subject with a set of user and group principals, which include the user and group names, respectively. The LDAP Authentication providers included in WebLogic Server also store the global universal identifier (GUID) and LDAP distinguished name (DN) data of users and groups as attributes of those principals. By default, WebLogic Server does not use the GUID or DN data in WebLogic principals. However, if the WebLogic domain is configured to use JAAS authorization, the GUID and DN data can be used in principal comparison operations that occur with Java policy decisions.

When configuring an LDAP Authentication provider, make sure that the name of the GUID attribute defined in the LDAP server is specified correctly for that provider. The default GUID attribute name for each LDAP Authentication provider included in WebLogic Server is listed in Table 5-2.

Table 5-2 Name of GUID Attribute for LDAP Authentication Providers in WebLogic Server

Provider Default GUID Attribute Name

WebLogic Authentication provider

orclguidFoot 1 

Oracle Internet Directory Authentication provider

orclguid

Oracle Virtual Directory Authentication provider

orclguidFoot 2 

Active Directory Authentication provider

objectguidFoot 3 

iPlanet Authentication provider

nsuniqueid

Novell Authentication provider

guid

Open LDAP Authentication provider

entryuuid


Footnote 1 Note that the GUID attribute name for the embedded LDAP server cannot be modified, so the WebLogic Authentication provider does not have a corresponding attribute that is configurable.

Footnote 2 The GUID attribute name you configure for the Oracle Virtual Directory Authentication provider depends on whether Oracle Virtual Directory has a mapping of this attribute name. The mapping specifies a name for this attribute that is renamed from the one defined in the LDAP server with which Oracle Virtual Directory is connected. If a mapping exists, specify the name that is defined in the mapping. For example, if the GUID attribute is renamed in the mapping to OVDguid, configure the Oracle Virtual Directory Authentication provider to use OVDguid as the GUID attribute name. If a mapping does not exist, specify the name that is defined in the LDAP server. For example, if the LDAP server is Sun iPlanet Directory, and Sun iPlanet Directory defines the GUID attribute name as nsuniqueid, configure the Oracle Virtual Directory Authentication provider to use nsuniqueid. For more information, see "Understanding Oracle Virtual Directory Mapping" in Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory.

Footnote 3 The Active Directory Authentication provider also supports Microsoft Active Directory Application Mode (ADAM) as a standalone directory server.

For more information about how GUID and DN data in principal objects may be used, see Configuring a Domain to Use JAAS Authorization.

Configuring Users and Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

The following sections explain how to change default values in the Oracle Internet Directory and Oracle Virtual Directory Authentication providers that specify how users and groups are located in the LDAP server:

Configuring User and Group Name Types

By default, the Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured to search users and groups in the LDAP directory using the class attribute types identified in Table 5-3:

Table 5-3 Default User Name and Group Name Attribute Types

Class Attribute Type

User object class

user name

cn

Group object class

group name

cn


If the user name attribute type, or group name attribute type, defined in the LDAP directory structure differs from the default settings for the Authentication provider you are using, you must change those provider settings. The following sections explain how to make those changes.

Note:

Neither the Oracle Internet Directory Authentication provider nor Oracle Virtual Directory Authentication provider can read the name of a user or group from the LDAP server if the name contains an invalid character. Invalid characters are:
  • Comma (,)

  • Plus sign (+)

  • Quotes (")

  • Backslash (\)

  • Angle brackets (< or >)

  • Semicolon (;)

If either of these providers encounters a group or user name containing an invalid character, the name is ignored. (WebLogic Server in general does not support group names containing any of these invalid characters. See "Create groups" in the Oracle WebLogic Server Administration Console Help.)

Changing the User Name Attribute Type

By default, the Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured with the user name attribute set to type cn. If the user name attribute type in the LDAP directory structure uses a different type — for example, uid — you must change the following Authentication provider attributes:

  • AllUsersFilter

  • UserFromNameFilter

  • UserNameAttribute

For example, if the LDAP directory structure has the user name attribute type uid, the preceding Authentication provider attributes must be changed as shown in Table 5-4. The required changes are shown in bold.

Table 5-4 Changing the User Name Attribute Type for the User Object Class

Attribute Name Default Setting Required New Setting

UserNameAttribute

cn

uid

AllUsersFilterFoot 1 

(&(cn=*)(objectclass=person))

(&(uid=*)(objectclass=person))

UserFromNameFilterFootref 1

(&(cn=%u)(objectclass=person))

(&(uid=%u)(objectclass=person))


Footnote 1 When specifying an LDAP search filter for users or groups, wildcards are accepted. However, using multiple asterisk wildcards, particularly for a user or group name attribute, have a negative performance impact on the LDAP server.

For information about configuring the user name attribute type, see the following topics in the Oracle WebLogic Server Administration Console Help:

Changing the Group Name Attribute Type

By default, the Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured with the group name attribute type of cn for the static group object class and dynamic group object class. If the group name attribute type in the LDAP directory structure is different — for example, type uid is used — you must change the following Authention provider attributes:

  • AllGroupsFilter

  • GroupFromNameFilter

  • StaticGroupNameAttribute (for static groups)

  • DynamicGroupNameAttribute (for dynamic groups)

For example, if the LDAP directory structure of the group object class uses a group name attribute of type uid, you must change the Authentication provider attributes as shown in Table 5-5. The required changes are shown in bold.

Table 5-5 Required Changes for the Group Name Attribute Type

Attribute Name Default Setting Required Changes

StaticGroupNameAttribute

cn

uid

DynamicGroupNameAttribute

cn

uid

AllGroupsFilterFoot 1 

(&(cn=*)(|(objectclass=groupofUniqueNames)(objectclass=orcldynamicgroup)))

(&(uid=*)(|(objectclass=groupofUniqueNames)(objectclass=orcldynamicgroup)))

GroupFromNameFilterFootref 1

(|(&(cn=%g)(objectclass=groupofUniqueNames))(&(cn=%g)(objectclass=orcldynamicgroup)))

(|(&(uid=%g)(objectclass=groupofUniqueNames))(&(uid=%g)(objectclass=orcldynamicgroup)))


Footnote 1 When specifying an LDAP search filter for users or groups, wildcards are accepted. However, using multiple asterisk wildcards, particularly for a user or group name attribute, have a negative performance impact on the LDAP server.

For more information about configuring group name attributes, see the following topics in the Oracle WebLogic Server Administration Console Help

Configuring Static Groups

The Oracle Internet Directory and Oracle Virtual Directory Authentication providers are configured by default with the following settings for static groups:

  • Static group object class name of groupofuniquenames

  • Static member DN attribute of type uniquemember

However, the directory structure of the Oracle Internet Directory or Oracle Virtual Directory LDAP server with which you are configuring either of these Authentication providers may instead define the following for static groups:

  • Static group object class name of groupofnames

  • Static member DN attribute of type member

If the LDAP database schema contains the static group object class name of groupofnames, and the static member DN attribute of type member, you need to change the Oracle Internet Directory or Oracle Virtual Directory Authentication provider attribute settings as shown in Table 5-6. The required changes are shown in bold.

Table 5-6 Attribute Settings for Static Groups in the Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

Attribute Default Setting Required Changes

StaticGroupObjectClass

groupofuniquenames

groupofnames

StaticMemberDNAttribute

uniquemember

member

AllGroupsFilterFoot 1 

(&(cn=*)(|(objectclass=groupofUniqueNames)(objectclass=orcldynamicgroup)))

(&(cn=*)(|(objectclass=groupofnames)(objectclass=orcldynamicgroup)))

GroupFromNameFilterFootref 1

(|(&(cn=%g)(objectclass=groupofUniqueNames))(&(cn=%g)(objectclass=orcldynamicgroup)))

(|(&(cn=%g)(objectclass=groupofnames))(&(cn=%g)(objectclass=orcldynamicgroup)))


Footnote 1 When specifying an LDAP search filter for users or groups, wildcards are accepted. However, using multiple asterisk wildcards, particularly for a user or group name attribute, have a negative performance impact on the LDAP server.

For more information about configuring static groups, see the following topics in the Oracle WebLogic Server Administration Console Help:

Configuring Failover for LDAP Authentication Providers

You can configure an LDAP provider to work with multiple LDAP servers and enable failover if one LDAP server is not available. Use the Host attribute (found in the Administration Console on the Configuration > Provider Specific page for the LDAP Authentication provider) to specify the names of the additional LDAP servers. Each host name may include a trailing space character and a port number. In addition, set the Parallel Connect Delay and Connection Timeout attributes for the LDAP Authentication provider:

  • Parallel Connect Delay—Specifies 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 value is greater than 0, another connection setup thread is started after the specified number of delay seconds has passed. If the value is 0, connection attempts are serialized.

  • Connection Timeout—Specifies the maximum number of seconds to wait for the connection to the LDAP server(s) to be established. If the value is set to 0, the default, there is no maximum time limit and WebLogic Server waits until the TCP/IP layer times out to return a connection failure.

    If multiple hosts are set in the Host attribute, the connection timeout controls the total timeout value for attempts to connect to all the specified hosts.

    Oracle recommends setting the connection timeout to a value of at least 60 seconds, depending upon the configuration of TCP/IP.

  • Socket Timeout—Specifies the maximum number of seconds to wait for the connection to any one host specified in the Host attribute. The socket timeout is specified only using the -Dweblogic.security.providers.authentication.ldap.socketTimeout=seconds security parameter for the JVM in which WebLogic Server runs. The default value of the socket timeout is 0, which sets no socket timeout.

    Note that setting the socket timeout is not available in the WebLogic Server Administration Console. For information about the options for configuring WebLogic Server security parameters, see "Security" in Command Reference for Oracle WebLogic Server.

The following examples present scenarios that occur when an LDAP Authentication provider is configured for LDAP failover.

LDAP Failover Example 1

In the following scenario, an LDAP Authentication provider is configured with three servers in its Host attribute: directory.knowledge.com:1050, people.catalog.com, and 199.254.1.2. The status of the LDAP servers is as follows:

  • directory.knowledge.com:1050 is down

  • people.catalog.com is up

  • 199.254.1.2 is up

WebLogic Server attempts to connect to directory.knowledge.com. After three seconds, or the socket connection throws an exception, the connect attempt times out and WebLogic Server attempts to connect to the next specified host (people.catalog.com). WebLogic Server then uses people.catalog.com as the LDAP Server for this connection. Otherwise, after another three seconds, WebLogic Server tries to connect to 199.254.1.2. This process continues, but will fail if the overall LDAP server connection process exceeds 10 seconds.

Table 5-7 LDAP Configuration Example 1

LDAP Option Value

Host

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

Parallel Connect Delay

0

Connect Timeout

10

Socket Timeout

3

LDAP Failover Example 2

In the following scenario, WebLogic Server attempts to connect to directory.knowledge.com. After 1 second (specified by the Parallel Connect Delay attribute), the connect attempt times out and WebLogic Server tries to connect to the next specified host (people.catalog.com) and directory.knowledge.com at the same time. If the connection to people.catalog.com succeeds, WebLogic Server uses people.catalog.com as the LDAP Server for this connection. WebLogic Server cancels the connection to directory.knowledge.com after the connection to people.catalog.com succeeds.

Table 5-8 LDAP Configuration Example 2

LDAP Option Value

Host

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

Parallel Connect Delay

1

Connect Timeout

10

Socket Timeout

3

Following Referrals in the Active Directory Authentication Provider

If Active Directory uses LDAP referrals, you must configure the Active Directory Authentication provider to follow those referrals by making sure that the LDAPServerMBean.FollowReferrals attribute is enabled. This attribute is enabled by default, but Oracle recommends that you make sure it is specifically enabled.

You can enable this attribute using WLST or the WebLogic Server Administration Console. If you are using the Administration Console, this attribute is available from the Configuration > Provider Specific page for the Active Directory Authentication provider.

Improving the Performance of WebLogic and LDAP Authentication Providers

To improve the performance of WebLogic and LDAP Authentication providers:

Optimizing the Group Membership Caches

To optimize the group membership caches for WebLogic and LDAP Authentication providers, set the following attributes (found in the Administration Console on the LDAP Authentication provider's Configuration > Provider Specific and Performance pages):

  • Group Membership Searching—Available from the Provider Specific page, this attribute controls whether group searches are limited or unlimited in depth. This option controls how deeply to search into nested groups. For configurations that use only the first level of nested group hierarchy, this option allows improved performance during user searches by limiting the search to the first level of the group.

    • If a limited search is defined, Max Group Membership Search Level must be defined.

    • If an unlimited search is defined, Max Group Membership Search Level is ignored.

  • Max Group Membership Search Level—Available from the Provider Specific page, this attribute controls the depth of a group membership search if Group Membership Searching is defined. 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 option 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— Available from the Performance page, this attribute 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 setting only applies if Group Membership is enabled. By default, it is disabled.

  • Max Group Hierarchies in Cache—Available from the Performance page, this attribute specifies the maximum size of the Least Recently Used (LRU) cache that holds group membership hierarchies. A value of 1024 is recommended. This setting only applies if Enable Group Membership Lookup Hierarchy Caching is enabled.

  • Group Hierarchy Cache TTL—Available from the Performance page, this attribute specifies the number of seconds cached entries stay in the cache. The default is 60 seconds. A value of 6000 is recommended.

In planning your cache settings, bear in mind the following considerations:

  • Enabling a cache involves a trade-off of performance and accuracy. Using a cache means that data is retrieved faster, but runs the risk that the data may not be the latest available.

  • The time-to-live (TTL) setting how long you are willing to accept potentially stale data. This depends a lot on your particular business needs. If you frequently changes group memberships for users, then a long TTL could mean that group related changes won't show up for a while, and you may want a short TTL. If group memberships almost never change after a user is added, a longer TTL may be fine.

  • The cache size is related to the amount of memory you have available, as well as the cache TTL. Consider the number of entries that might be loaded in the span of the TTL, and size the cache in relation to that number. A longer TTL will tend to require a larger cache size.

Optimizing the Connection Pool Size and User Cache

When configuring any of the LDAP Authentication providers, you can improve the performance of the connection between WebLogic Server and the LDAP server by optimizing the size of the LDAP connection pool and user cache. To make these optimizations, complete the following steps:

  1. Set the LDAP connection pool size to 100 by using either of the following methods:

    • Define the following system property in the setDomainEnv script, which is located in the bin directory of the WebLogic domain:

      -Dweblogic.security.providers.authentication.LDAPDelegatePoolSize=100
      
    • In the WebLogic Server Administration Console, select the Provider Specific page for the LDAP authentication provider you are configuring (Security Realms > myrealm > Providers > Authentication > your LDAP Authentication provider > Provider Specific), and specify 100 in the field labeled Connection Pool Size.

  2. Enable and enlarge the cache used with the LDAP server by completing the following steps in the WebLogic Server Administration Console:

    1. Select the Provider Specific page for the LDAP Authentication provider (Security Realms > myrealm > Providers > Authentication > your LDAP Authentication provider > Provider Specific).

    2. Scroll towards the bottom and make sure that Cache Enabled is checked.

    3. In the field labeled Cache Size, specify a value of 3200 KB.

    4. In the field labeled Cache TTL, specify a time-to-live value that matches the Group Hierarchy Cache TTL value (see Optimizing the Group Membership Caches). A value of 6000 is recommended).

    5. Set the results timeout value for the LDAP server. On the current Provider Specific configuration page, specify a value of 1000 ms in the field labeled Results Time Limit.

  3. Restart WebLogic Server for the changes to take effect.

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

  1. Expand Security Realms > RealmName > Providers > Authentication.

  2. On the Provider Specific tab for your iPlanet Authentication provider, set User Dynamic Group DN Attribute. 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, set these attributes for your security realm (found in the Administration Console on the Configuration > Performance page for the security realm):

  • Enable WebLogic Principal Validator Cache—Indicates whether the WebLogic Principal Validation provider uses a cache. This setting only applies if Authentication providers in the security realm use the WebLogic Principal Validation provider and WLSAbstractPrincipals. By default, it 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 setting only applies if Enable WebLogic Principal Validator Cache is enabled.

Configuring the Active Directory Authentication Provider to Improve Performance

To configure an Active Directory Authentication provider to use the tokenGroups option, set the following attributes (found in the Administration Console on the Active Directory Authentication provider's Configuration > Provider Specific page):

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

    Note:

    Access to the tokenGroups option is required (meaning, the user accessing the LDAP directory must have privileges to read the tokenGroups option and the tokenGroups option 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 setting only applies if the Use Token Groups for Group Membership Lookup option 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 setting applies only if both the Use Token Groups for Group Membership Lookup and Enable SID to Group Lookup Caching options are enabled.

Configuring RDBMS Authentication Providers

In WebLogic Server, an RDBMS Authentication provider is a username/password based Authentication provider that uses a relational database (rather than an LDAP directory) as its data store for user, password, and group information. WebLogic Server includes these RDBMS Authentication providers:

  • SQL Authenticator—Uses a SQL database and allows both read and write access to the database. This Authentication provider is configured by default with a typical SQL database schema, which you can configure to match your database's schema. See Configuring the SQL Authentication Provider.

  • Read-only SQL Authenticator—Uses a SQL database and allows only read access to the database. For write access, you use the SQL database's own interface, not the WebLogic security provider. See Configuring the Read-Only SQL Authenticator.

  • Custom RDBMS Authenticator—Requires you to write a plug-in class. This may be a better choice if you want to use a relational database for your authentication data store, but the SQL Authenticator's schema configuration is not a good match for your existing database schema. See Configuring the Custom DBMS Authenticator.

For information about adding an RDBMS Authentication provider to your security realm, see "Configure Authentication and Identity Assertion providers" in the Oracle WebLogic Server Administration Console Help. Once you have created an instance of the RDBMS Authentication provider, configure it on the RDBMS Authentication provider's Configuration > Provider Specific page in the Administration Console.

Common RDBMS Authentication Provider Attributes

All three RDBMS Authentication providers include these configuration options.

Data Source Attribute

The Data Source Name specifies the WebLogic Server data source to use to connect to the database.

Group Searching Attributes

The Group Membership Searching and Max Group Membership Search Level attributes specify whether recursive group membership searching is unlimited or limited, and if limited, how many levels of group membership can be searched. For example, if you specify that Group Membership Searching is LIMITED, and the Max Group Membership Search Level is 0, then the RDBMS Authentication providers will find only groups that the user is a direct member of. Specifying a maximum group membership search level can greatly increase authentication performance in certain scenarios, since it may reduce the number of DBMS queries executed during authentication. However, you should only limit group membership search if you can be certain that the group memberships you require are within the search level limits you specify.

Note:

If the RDBMS contains cyclic groups, or groups that are defined to contain themselves, the RDBMS Authentication provider may be unable to complete the authentication process. Setting the Group Membership Searching and Max Group Membership Search Level attributes can help limit recursive group name lookups. However, the use of RDBMS Authentication providers with cyclic groups is not supported and must be avoided.

Group Caching Attributes

You can improve the performance of RDBMS Authentication providers by caching the results of group hierarchy lookups. Use of this cache can reduce the frequency with which the RDBMS Authentication provider needs to access the database. In the Administration Console, you can use the Performance page for your Authentication provider to configure the use, size, and duration of this cache. See "Security Realms: Security Providers: SQL Authenticator: Performance" in the Oracle WebLogic Server Administration Console Help.

Configuring the SQL Authentication Provider

For detailed information about configuring a SQL Authentication provider, see "Security Realms: Security Providers: SQL Authenticator: Provider Specific" in the Oracle WebLogic Server Administration Console Help. In addition to the attributes described in Common RDBMS Authentication Provider Attributes, the SQL Authentication provider has the following configurable attributes.

Password Attributes

The following attributes govern how the RDBMS Authentication provider and its underlying database handle user passwords:

  • Plaintext Passwords Enabled

  • Password Style Retained

  • Password Style

  • Password Algorithm

SQL Statement Attributes

SQL statement attributes specify the SQL statements used by the provider to access and edit the username, password, and group information in the database. With the default values in the SQL statement attributes, it is assumed that the database schema includes the following tables:

  • users (username, password, [description])

  • groupmembers (group name, group member)

  • groups (group name, group description)

    Note:

    The tables referenced by the SQL statements must exist in the database; the provider will not create them. You can modify these attributes as needed to match the schema of your database. However, if your database schema is radically different from this default schema, you may need to use a Custom DBMS Authentication provider instead.

Configuring the Read-Only SQL Authenticator

For detailed information about configuring a Read-Only SQL Authentication provider, see "Security Realms: Security Providers: Read-Only SQL Authenticator: Provider Specific" in the Oracle WebLogic Server Administration Console Help. In addition to the attributes described in Common RDBMS Authentication Provider Attributes, the Read-Only SQL Authentication provider's configurable attributes include attributes that specify the SQL statements used by the provider to list the username, password, and group information in the database. You can modify these attributes as needed to match the schema of your database.

Configuring the Custom DBMS Authenticator

The Custom DBMS Authentication provider, like the other RDBMS Authentication providers, uses a relational database as its data store for user, password, and group information. Use this provider if your database schema does not map well to the SQL schema expected by the SQL Authenticator. In addition to the attributes described in Common RDBMS Authentication Provider Attributes, the Custom DBMS Authentication provider's configurable attributes include the following.

Plug-In Class Attributes

A Custom DBMS Authentication provider requires that you write a plug-in class that implements the weblogic.security.providers.authentication.CustomDBMSAuthenticatorPlugin interface. The class must exist in the system classpath and must be specified in the Plug-in Class Name attribute for the Custom DBMS Authentication provider. Optionally, you can use the Plugin Properties attribute to specify values for properties defined by your plug-in class.

Configuring a Windows NT Authentication Provider

The Windows NT Authentication provider uses account information defined for a Windows NT domain to authenticate users and groups and to permit Windows NT users and groups to be listed in the WebLogic Server Administration Console.

To use the Windows NT Authentication provider, create the provider in the Administration Console. In most cases, you should not need to do anything more to configure this Authentication provider. Depending on how your Windows NT domains are configured, you may want to set the Domain Controllers and Domain Controller List attributes, which control how the Windows NT Authentication provider interacts with the Windows NT domain.

Note:

The Windows NT Authentication provider is deprecated as of WebLogic Server 10.0. Use one or more other supported authentication providers instead.

Domain Controller Settings

Usernames in a Windows NT domain can take several different forms. You may need to configure the Windows NT Authentication provider to match the form of usernames you expect your users to sign on with. A simple username is one that gives no indication of the domain, such as smith. Compound usernames combine a username with a domain name and may take a form like domain\smith or smith@domain.

If the local machine is not part of a Microsoft domain, then no changes to the Domain Controllers and Domain Controller List attributes are needed. On a stand-alone machine, the users and groups to be authenticated are defined only on that machine.

If the local machine is part of a Microsoft domain and is the domain controller for the local domain, then no changes are needed to the Domain Controller List attribute. Users defined on the local machine and the domain are the same in this case, so you can use the default Domain Controllers setting.

If the local machine is part of a Microsoft domain, but is not the domain controller for the local domain, then a simple username might be found on either the local machine or in the domain. In this case, consider the following:

  • Do you want to prevent the users and groups from the local machine from being displayed in the Console when the local machine is part of a Microsoft domain?

  • Do you want users from the local machine to be found and authenticated when a simple username is entered?

If the answer to either question is yes, then set the Domain Controller attribute to DOMAIN.

If you have multiple trusted domains, you may need to set the Domain Controller attribute to LIST and specify a Domain Controller List. Do this if:

  • You require the users and groups for other trusted domains to be visible in the Console, or

  • You expect that your users will be entering simple usernames and expect them to be located in the trusted domains (that is, users will sign on with a simple username like smith, not smith@domain or domain\Smith).

If either of these situations is the case, then set the Domain Controllers attribute to LIST and specify the names of the domain controllers in the Domain Controller List attribute for the trusted domains that you want to be used. Consider also whether to use explicit names for the local machine and local domain controller or if you want to use placeholders in the list for those. You can use the following placeholders in the Domain Controller List attribute:

  • [Local]

  • [LocalAndDomain]

  • [Domain]

LogonType Setting

The proper value of the LogonType attribute in the Windows NT Authentication provider depends on the Windows NT logon rights of the users that you want to be able to authenticate:

  • If users have the "logon locally" right assigned to them on the machines that will run WebLogic Server, then use the default value, interactive.

  • If users have the "Access this computer from the Network" right assigned to them, then change the LogonType attribute to network.

You must assign one of these rights to users in the Windows NT domain or else the Windows NT Authentication provider will not be able to authenticate any users.

UPN Names Settings

UPN style usernames can take the form user@domain. You can configure how the Windows NT Authentication provider handles usernames that include the @ character, but which may not be UPN names, by setting the mapUPNNames attribute in the Windows NT Authentication provider.

If none of your Windows NT domains or local machines have usernames that contain the @ character other than UPN usernames, then you can use the default value of the mapUPNNames attribute, FIRST. However, you may want to consider changing the setting to ALWAYS in order to reduce the amount of time it takes to detect authentication failures. This is especially true if you have specified a long domain controller list.

If your Windows NT domains do permit non-UPN usernames with the @ character in them, then:

  • if a username with the @ character is more likely to be a UPN username than a simple username, set the mapUPNNames attribute to FIRST.

  • if a username with the @ character is more likely to be a simple username than a UPN username, set the mapUPNNames attribute to LAST.

  • if a username is never in UPN format, set the mapUPNNames attribute to NEVER.

Configuring the SAML Authentication Provider

The SAML Authentication provider may be used in conjunction with the SAML 1.1 or SAML 2.0 Identity Assertion provider to do the following:

  • Allow virtual users to log in via SAML

    If true, the SAML Identity Asserter will create user/group principals, with the possible result that the user is logged in as a virtual user — a user that does not correspond to any locally-known user.

  • If the SAML Authentication provider is configured to run before other authentication providers, and has a JAAS Control Flag set to SUFFICIENT, this provider creates an authenticated subject using the user name and groups retrieved from a SAML assertion by the SAML Identity Assertion provider V2 or the SAML 2.0 Identity Assertion provider.

If the SAML Authentication provider is not configured, or if another authentication provider (e.g., the default LDAP Authentication provider) is configured before it and its JAAS Control Flag set is set to SUFFICIENT, then the user name returned by the SAML Identity Assertion provider is validated by the other authentication provider. In the case of the default LDAP Authentication provider, authentication fails if the user does not exist in the identity directory.

If you want groups from a SAML assertion, you must configure the SAML Authentication provider even if you want the LDAP Authentication provider to verify the user's existence. Otherwise, the groups with which the user is associated is derived from the LDAP directory and not with the groups in the assertion.

The SAML Authentication provider creates a subject only for users whose identities are asserted by either the SAML Identity Assertion provider V2 or SAML 2.0 Identity Assertion provider. The SAML Authentication provider ignores all other authentication or identity assertion requests.

Configuring the Password Validation Provider

WebLogic Server includes a Password Validation provider, which is configured by default in each security realm. The Password Validation provider manages and enforces a set of configurable password composition rules, and is automatically invoked by a supported authentication provider whenever a password is created or updated for a user in the realm. When invoked, the Password Validation provider performs a check to determine whether the password meets the criteria established by the composition rules. The password is then accepted or rejected as appropriate.

The following authentication providers can be used with the Password Validation provider:

  • WebLogic Authentication provider

  • SQL Authenticator provider

  • LDAP Authentication provider

  • Oracle Internet Directory Authentication Provider

  • Oracle Virtual Directory Authentication Provider

  • Active Directory Authentication provider

  • iPlanet Authentication provider

  • Novell Authentication provider

  • Open LDAP Authentication provider

The following sections describe the composition rules that may be configured and explain how to create and configure an instance of the Password Validation provider in a security realm:

For information about configuring the Password Validation provider in the WebLogic Server Administration Console, see "Configure the Password Validation provider" in the Oracle WebLogic Server Administration Console Help.

Password Composition Rules for the Password Validation Provider

By default, the Password Validation provider is configured to require passwords that have a minimum length of eight characters. When used with one of the supported LDAP authentication providers listed in the preceding section, the Password Validation provider also requires that passwords meet the additional criteria listed in Table 5-9.

Table 5-9 Additional Password Composition Rules Required by Password Validation Provider When Used with an LDAP Authentication Provider

LDAP Authentication Provider Additional Password Composition Requirement
  • Oracle Internet Directory Authentication provider

  • Oracle Virtual Directory Authentication provider

At least one of the characters in the password must be numeric.

  • WebLogic Authentication provider

  • LDAP Authentication provider

  • Active Directory Authentication provider

  • iPlanet Authentication provider

  • Novell Authentication provider

  • Open LDAP Authentication provider

At least one of the characters in the password must be non-alphabetic. For example, a numeric character, an asterisk (*), or an octothorpe (#).


The password composition rules you optionally can configure for the Password Validation provider include the following:

  • User name policies — Rules that determine whether the password may consist of or contain the user's name, or the reverse of that name

  • Password length policies — Rules for the minimum or maximum number of characters in a password (composition rules may specify both a minimum and maximum length)

  • Character policies — Rules regarding the inclusion of the following characters in the password:

    • Numeric characters

    • Lowercase alphabetic characters

    • Uppercase alphabetic characters

    • Non-alphanumeric characters

For information about the specific composition rules that may be configured for the Password Validation provider, including the settings for these rules that Oracle recommends for a production environment, see "System Password Validation Provider: Provider Specific" in the Oracle WebLogic Server Administration Console Help.

Caution:

Setting password composition rules is only one component of hardening the WebLogic Server environment against brute-force password attacks. To protect user accounts, you should also configure user lockout. User lockout specifies the number of incorrect passwords that may be entered within a given interval of time before the user is locked out of his or her account. For more information, see Protecting User Accounts.

Using the Password Validation Provider with the WebLogic Authentication Provider

By default, the WebLogic Authentication provider requires a minimum password length of 8 characters, of which one is non-alphabetic. However, the minimum password length enforced by this provider can be customized. If the WebLogic Authentication provider and Password Validation provider are both configured in the security realm, and you attempt to create a password that does not meet the minimum length enforced by the WebLogic Authentication provider, an error is generated. For example, the following message is displayed in the Administration Console:

Error [Security:090285]password must be at least 8 characters long
Error Errors must be corrected before proceeding.

If the WebLogic Authentication provider rejects a password because it does not meet the minimum length requirement, the Password Validation provider is not called. To ensure that the Password Validator is always used in conjunction with the WebLogic Authentication provider, make sure that the minimum password length is the same for both providers.

Using the Administration Console, you can set the minimum password length for WebLogic Authentication provider by completing the following steps:

  1. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

  2. In the left pane, select Security Realms and click the name of the realm you are configuring (for example, myrealm).

  3. Select Providers > Authentication and click DefaultAuthenticator.

  4. Select Configuration > Provider Specific and enter the minimum password length in the field labeled Minimum Password Length.

  5. Click Save to save your changes.

  6. To activate these changes, in the Change Center, click Activate Changes.

For information about how to set the minimum password length in the Password Validation provider, see Using WLST to Create and Configure the Password Validation Provider.

Using the Password Validation Provider with an LDAP Authentication Provider

When the Password Validation provider and an LDAP Authentication provider (for example, Oracle Internet Directory Authentication provider) are configured in the security realm, passwords are validated through two separate policy checks: one from Password Validation provider, and the other from the LDAP server, which has its own password policy check. For example, Oracle Internet Directory has its own password validation mechanism, which is controlled by the LDAP server administrator. These two password validation mechanisms are separate, and each has its own set of password composition rules. If the composition rules are inconsistent, failures may occur in the WebLogic Server Administration Console when you try to create or reset a password, even if the rules for the Password Validation provider are enforced. Therefore you should make sure that the password composition rules for the Password Validation provider do not conflict with those for the LDAP server.

Using WLST to Create and Configure the Password Validation Provider

The Password Validation provider can be administered in the security realm via a WLST script that performs operations on the SystemPasswordValidatorMBean, described in the Oracle WebLogic Server MBean Reference. You may create and configure the Password Validation provider from a single WLST script, or you may have separate scripts that perform these functions separately. The following topics explain how, providing sample WLST code snippets:

Creating an Instance of the Password Validation Provider

The Password Validation provider is created automatically in the security realm when you create a new domain. However, you can use WLST to create one as well, as shown in Example 5-1. This code does the following:

  1. Gets the current realm and Password Validation provider.

  2. Determines whether an instance of the Password Validator provider (named SystemPasswordValidator) has been created:

    • If the provider has been created, the script displays a message confirming its presence.

    • If the provider has not been created, the script creates it in the security realm and displays a message indicating that it has been created.

Example 5-1 Creating the System Password Validator

edit()
startEdit()

realm = cmo.getSecurityConfiguration().getDefaultRealm()
pwdvalidator = realm.lookupPasswordValidator('SystemPasswordValidator')

if pwdvalidator:
   print 'Password Validator provider is already created'

else:
# Create SystemPasswordValidator
 syspwdValidator = realm.createPasswordValidator('SystemPasswordValidator', 
 'com.bea.security.providers.authentication.passwordvalidator.SystemPasswordValidator')
 print "---  Creation of System Password Validator succeeded!"

save()
activate()

Specifying the Password Composition Rules

Example 5-2 shows an example of WLST code that sets the composition rules for the Password Validation provider. For information about the rule attributes that can be set in this script, see the description of the SystemPasswordValidatorMBean in the Oracle WebLogic Server MBean Reference.

Example 5-2 Configuring the Password Composition Rules

edit()
startEdit()

# Configure SystemPasswordValidator
try:
  pwdvalidator.setMinPasswordLength(8)
  pwdvalidator.setMaxPasswordLength(12)
  pwdvalidator.setMaxConsecutiveCharacters(3)
  pwdvalidator.setMaxInstancesOfAnyCharacter(4)
  pwdvalidator.setMinAlphabeticCharacters(1)
  pwdvalidator.setMinNumericCharacters(1)
  pwdvalidator.setMinLowercaseCharacters(1)
  pwdvalidator.setMinUppercaseCharacters(1)
  pwdvalidator.setMinNonAlphanumericCharacters(1)
  pwdvalidator.setMinNumericOrSpecialCharacters(1)
  pwdvalidator.setRejectEqualOrContainUsername(true)
  pwdvalidator.setRejectEqualOrContainReverseUsername(true)
  print " --- Configuration of SystemPasswordValidator complete  ---"
except Exception,e:
        print e

save()
activate()

Configuring Identity Assertion Providers

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 through tokens (as opposed to simple authentication, where WebLogic Server establishes trust through 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.

WebLogic Server includes the following Identity Assertion providers:

  • WebLogic Identity Asserter

  • LDAP X.509 Identity Asserter

  • Negotiate Identity Asserter

  • SAML Identity Asserter (for SAML 1.1)

  • SAML 2.0 Identity Asserter

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. In the Active Type field on the Provider Specific configuration page in the Administration Console, define the active token type. The WebLogic Identity Assertion provider supports identity assertion with X.509 certificates and CORBA Common Secure Interoperability version 2 (CSI v2). If you are using CSI v2 identity assertion, define the list of client principals in the Trusted Principals field.

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

With the WebLogic Identity Assertion provider, you can use 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 WebLogic Credential Mapping Provider.

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 value on the Provider Specific page 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 option.

For more information see "Configure Authentication and Identity Assertion providers" in the Oracle WebLogic Server Administration Console Help. In addition, see the following sections:

How an LDAP X509 Identity Assertion Provider Works

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:

  1. An application is set up to use perimeter authentication (in other words, users or system process use tokens to assert their identity).

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

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

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

Configuring an LDAP X509 Identity Assertion Provider: Main Steps

Typically, if you use the LDAP X509 Identity Assertion provider, you 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.

To use an LDAP X509 Identity Assertion provider:

  1. Obtain certificates for users and put them in an LDAP Server. See Chapter 11, "Configuring Identity and Trust".

    A correlation must exist 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 configuration information for the certificate and the username that will be used in the Subject.

  2. In your security realm, configure an LDAP X509 Identity Assertion provider. See "Configure Authentication and Identity Assertion providers" in the Oracle WebLogic Server Administration Console Help.

  3. In the WebLogic Server Administration Console, configure the LDAP X509 Identity Assertion provider to find the LDAP object for the user in the LDAP directory given the certificate's Subject DN.

  4. Configure 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 option 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 that holds the certificate.

    • A search filter that only returns LDAP objects that match a defined set of options. The filter narrows the LDAP search. Configure User Filter Search 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 value must match the values in the certificate's Subject DN.

  5. Configure the Certificate Attribute attribute of the LDAP X509 Identity Assertion provider to specify how the LDAP object for the user holds the certificate. The LDAP object must contain an attribute that holds the certificate.

  6. Configure the User Name Attribute 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.

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

  8. Configure an LDAP Authentication provider for use with the LDAP X509 Identity Assertion provider. The LDAP server information should be the same the information defined for the LDAP X509 Identity Assertion provider configured in Step 7. See Configuring LDAP Authentication Providers.

Configuring a Negotiate Identity Assertion Provider

The 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 Negotiate Identity Assertion provider utilizes the Java Generic Security Service (GSS) Application Programming Interface (API) to accept the GSS security context via Kerberos.

The 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 adding a Negotiate Identity Assertion provider to a security realm, see "Configure Authentication and Identity Assertion providers" in the Oracle WebLogic Server Administration Console Help. For information about using the Negotiate Identity Assertion provider with Microsoft client SSO, see Chapter 6, "Configuring Single Sign-On with Microsoft Clients"

Table 5-10 Negotiate Identity Asserter Attributes

Attribute Description

Form Based Negotiation Enabled

Indicates whether the Negotiate Identity Assertion provider and servlet filter should negotiate when a Web application is configured for FORM authentication.

Active Types

The token type this Negotiate Identity Assertion provider uses for authentication. Available token types are Authorization.Negotiate and WWW-Authenticate.Negotiate.

Ensure no other identity assertion provider configured in the same security realm has this attribute set to X509.


Configuring a SAML Identity Assertion Provider for SAML 1.1

The SAML Identity Assertion provider acts as a consumer of SAML 1.1 security assertions, allowing WebLogic Server to act as a destination site for using SAML 1.1 for single sign-on. The SAML Identity Assertion provider validates SAML 1.1 assertions by checking the signature and validating the certificate for trust in the certificate registry maintained by the provider. If so, identity is asserted based on the AuthenticationStatement contained in the assertion. The SAML Identity Assertion provider can also ensure that the assertion has not been previously used. The SAML Identity Assertion provider must be configured if you want to deploy a SAML Assertion Consumer Service on a server instance.

This release of WebLogic Server includes two SAML Identity Assertion providers for SAML 1.1. SAML Identity Asserter Version 2 provides greatly enhanced configuration options and is recommended for new deployments. SAML Identity Asserter Version 1 has been deprecated in WebLogic Server 9.1. A security realm can have not more than one SAML Identity Assertion provider, and if the security realm has both a SAML Identity Assertion provider and a SAML Credential Mapping provider, both must be of the same version. Do not use a Version 1 SAML provider in the same security realm as a Version 2 SAML provider. For information about configuring the SAML Identity Assertion provider Version 1, see "Configuring a SAML Identity Assertion Provider" in Securing WebLogic Server in the WebLogic Server 9.0 documentation.

For information about how to use the SAML Identity Assertion provider in a SAML single sign-on configuration, see Chapter 7, "Configuring Single Sign-On with Web Browsers and HTTP Clients". For general information about SAML support in WebLogic Server, see "Security Assertion Markup Language (SAML)" in Understanding Security for Oracle WebLogic Server.

Asserting Party Registry

When you configure WebLogic Server to act as a consumer of SAML security assertions, you need to register the parties whose SAML assertions will be accepted. For each SAML Asserting Party, you can specify the SAML profile used, details about the Asserting Party, and the attributes expected in assertions received from the Asserting Party. For information, see:

Certificate Registry

The SAML Identity Assertion provider maintains a registry of trusted certificates. Whenever a certificate is received, it is checked against the certificates in the registry for validity. For each Asserting Party, the following certificates from that partner are contained in this registry:

  • The certificate used for validating the signature of assertions received from this Asserting Party.

  • The certificate used for verifying signatures on SAML protocol elements from this Asserting Party. This certificate must be set for the Browser/POST profile.

  • The TLS/SSL certificate used for verifying trust in the Asserting Party when that partner is retrieving an artifact from the Assertion Retrieval Service (ARS) via an SSL connection.

You can add trusted certificates to the certificate registry through the Administration Console:

  1. In the Console, navigate to the Security Realms > RealmName > Providers > Authentication page.

  2. Click the name of the SAML Identity Assertion provider and open the Management > Certificates page.

On the Management > Certificates page, you can add, view, or delete certificates from the registry.

Configuring a SAML 2.0 Identity Assertion Provider for SAML 2.0

The SAML 2.0 Identity Assertion provider acts as a consumer of SAML 2.0 security assertions, allowing WebLogic Server to act as a Service Provider for the following:

  • Web single sign-on

  • WebLogic Web Services Security: accepting SAML tokens for identity through the use of the appropriate WS-SecurityPolicy assertions

The SAML 2.0 Identity Assertion provider does the following:

  • Validates SAML 2.0 assertions by checking the signature and validating the certificate for trust based on data configured for the partner. The SAML 2.0 Identity Assertion provider then extracts the identity information contained in the assertion, and maps it to a local subject in the security realm.

  • Optionally, extracts attribute information contained in an assertion that the SAML Authentication provider, if configured in the security realm, can use to determine the local groups in which the mapped subject belongs. (For more information, see Configuring the SAML Authentication Provider.)

  • Optionally, verifies that an assertion's specified lifespan and re-use settings are properly valid, rejecting the assertion if it is expired or is not available for reuse.

Configuration of the SAML 2.0 Identity Assertion provider is controlled by setting attributes on the SAML2IdentityAsserterMBean. You can access the SAML2IdentityAsserterMBean using the WebLogic Scripting Tool (WLST), or through the Administration Console by using the Security Realms > RealmName > Providers > Authentication page and creating or selecting SAML2IdentityAsserter. For details about these attributes, see SAML2IdentityAsserterMBean in the Oracle WebLogic Server MBean Reference.

For information about how to use the SAML 2.0 Identity Assertion provider in a SAML single sign-on configuration, see Chapter 7, "Configuring Single Sign-On with Web Browsers and HTTP Clients". For general information about SAML support in WebLogic Server, see "Security Assertion Markup Language (SAML)" in Understanding Security for Oracle WebLogic Server. For information about using the SAML 2.0 Identity Assertion provider in Web Service Security, see "Using Security Assertion Markup Language (SAML) Tokens For Identity" in Securing WebLogic Web Services for Oracle WebLogic Server.

Identity Provider Partners

When you configure WebLogic Server to act as a Service Provider, you create and configure the Identity Provider partners from whom SAML 2.0 assertions are received and validated. Configuring an Identity Provider partner consists of establishing basic information about that partner, such as the following:

  • Partner name and general description

  • Name mapper class to be used with this partner

  • Whether to consume attribute statements included in assertions received from this partner

  • Whether the identities contained in assertions received from this partner should be mapped to virtual users

  • Certificates used for validating signed assertions received from this partner

The specific information you establish depends upon whether you are configuring the partner for web single sign-on or web services. Configuring a web single sign-on Identity Provider partner also involves importing that partner's metadata file and establishing additional basic information about that partner, such as the following:

  • Redirect URIs, which are URLs that, when invoked by an unauthenticated user, cause the user request to be redirected to that Identity Provider partner for authentication

  • Whether SAML artifact requests received from this partner must be signed

  • How SAML artifacts should be delivered to this partner

For details about configuring web single sign-on Identity Provider partners, see:

Configuring a web service Identity Provider partner does not use a metadata file, but does consist of establishing the following information about that partner:

  • Issuer URI, which is a string that uniquely identifies this Identity Provider partner, distinguishing it from other partners in your SAML federation

  • Audience URIs, which specify an audience restriction to be included in assertions received from this partner

    In WebLogic Server, the Audience URI attribute is overloaded to also include the partner lookup string, which is required by the web service run time to discover the partner. See Partner Lookup Strings Required for Web Service Partners.

  • Custom name mapper class that overrides the default name mapper and that is to be used specifically with this partner

For more information about configuring web service Service Provider partners, see "Create a SAML 2.0 Web Service Identity Provider partner" in the Oracle WebLogic Server Administration Console Help.

Partner Lookup Strings Required for Web Service Partners

For web service Identity Provider partners, you also configure Audience URIs. In WebLogic Server, the Audience URI attribute is overloaded to perform two distinct functions:

  • Specify an audience restriction consisting of a target URL, per the OASIS SAML 2.0 specification.

  • Contain a partner lookup string, which is required at run time by WebLogic Server to discover the Identity Provider partner for which a SAML 2.0 assertion needs to be validated.

The partner lookup string specifies an endpoint URL, which is used for partner lookup and can optionally also serve as an Audience URI restriction that must be included in the assertion received from this Identity Provider partner.

Note:

You must configure a partner lookup string for an Identity Provider partner so that partner can be discovered at run time by the web service run time.

Lookup String Syntax

The partner lookup string has the following syntax:

[target:char:]<endpoint-url>

In this syntax, target:char: is a prefix that designates the partner lookup string, where char represents one of three special characters: a hyphen, plus sign, or asterisk (-, +, or *). This prefix determines how partner lookup is performed, as described in Table 5-11.

Note:

A WebLogic Server instance that is configured in the role of Service Provider always strips off the transport, host, and port portions of an endpoint URL that is passed in to the SAML 2.0 Identity Assertion provider. Therefore, the endpoint URLs you configure in any lookup string for an Identity Provider partner should contain only the portion of the URL that follows the host and port. For example, target:*:/myserver/xxx.

When you configure a Service Provider site, this behavior enables you to configure a single Identity Provider partner that can be used to validate all assertions for the same web service, regardless of the variations in the transport protocol (i.e., HTTP vs. HTTPS), host name, IP address, and port information across all the machines in a domain that host that web service.

Table 5-11 Identity Provider Partner Lookup String Syntax

Lookup String Description
target:-:<endpoint-url>

Specifies that partner lookup is conducted for an exact match of the URL, <endpoint-url>. For example, target:-:/myserver/myservicecontext/my-endpoint specifies the endpoint that can be matched to this Identity Provider partner, for which an assertion should be validated.

This form of partner lookup string excludes the endpoint URL from being added as an Audience URI for this Identity Provider partner.

target:+:<endpoint-url>

Specifies that partner lookup is conducted for an exact match of the URL, <endpoint-url>.

Note: Using the plus sign (+) in the lookup string results in the endpoint URL being added as an Audience URI in the assertion received from this Identity Provider partner. Because this form of lookup string is unlikely to produce a match for an Identity Provider partner, it should be avoided.

target:*:<endpoint-url>

Specifies that partner lookup is conducted for an initial-string pattern match of the URL, <endpoint-url>. For example, target:*:/myserver specifies that any endpoint URL beginning with /myserver can be matched to this Identity Provider, such as: /myserver/contextA/endpointA and /myserver/contextB/endpointB.

If more than one Identity Provider partner is discovered that is a match for the initial string, the partner with the longest initial string match is selected.

This form of partner lookup string excludes the endpoint URL from being added as an Audience URI for this Identity Provider partner.


Notes:

Configuring one or more partner lookup strings for an Identity Provider partner is required in order for that partner to be discovered at run time. If this partner cannot be discovered, no assertions for this partner can be validated.

If you configure an endpoint URL without using the target lookup prefix, it will be handled as a conventional Audience URI that must be contained in assertions received from this Identity Provider partner. (This also enables backwards-compatibility with existing Audience URIs that may be configured for this partner.)

Specifying Default Partners

To support the need for a default Identity Provider partner entry, one or more of the default partner's Audience URI entries may contain a wildcard match that works for all targets. For example, target:*:/.

Management of Partner Certificates

The SAML 2.0 Identity Assertion provider manages the trusted certificates for configured partners. Whenever a certificate is received during an exchange of partner messages, the certificate is checked against the certificates maintained for the partner. Partner certificates are used for the following purposes:

  • To validate trust when the Service Provider site receives a signed assertion or a signed SAML artifact request.

  • To validate trust in an Identity Provider partner that is retrieving a SAML artifact from the Artifact Resolution Service (ARS) via an SSL connection.

The following certificates, which are obtained from each configured Identity Provider partner, are required:

  • The certificate used to verify signed SAML documents received from the partner, such as assertions and artifact requests

    The certificate used to verify signed SAML documents in web single sign-on is included in the metadata file received from the Identity Provider partner. When configuring web service Identity Provider partners, you obtain this certificate from your partner and import it into this partner's configuration via the Assertion Signing Certificate tab of the partner management page in the Administration Console.

  • The Transport Layer Security (TLS) client certificate that is used to verify the connection made by the partner to the local site's SSL binding for retrieving SAML artifacts (used in web single sign-on only)

    When configuring a web single sign-on Identity Provider partner, you must obtain the TLS client certificate directly from the partner. It is not automatically included in the metadata file. You can import this certificate into the configuration data for this partner via the Transport Layer Client Certificate tab of the partner management page in the Administration Console.

Java Interface for Configuring Identity Provider Partner Attributes

Operations on web service partners are available in the com.bea.security.saml2.providers.registry.Partner Java interface.

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 active token type 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:

  1. An X.509 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.

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

  4. 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, X.509 is used for identity assertion.

  • If a request comes in with a FOO header and a WL-Proxy-Client-BAR header, the BAR token is used for identity assertion.

  • If a request comes in with a FOO header and a BAR cookie, 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.

Configuring Identity Assertion Performance in the Server Cache

When you use an Identity Assertion provider, either for an X.509 certificate or some other type of token, subjects are cached within the server. (A subject is a grouping of related information for a single entity (such as a person), including an identity and its security-related configuration options.) Caching subjects within the server greatly enhances performance for servlets and EJB methods with <run-as> tags as well as in other situations where identity assertion is used but not cached in the HTTPSession, for example, in 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 time out so long as the server is running. 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:

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 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 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@example.com) to a user in the WebLogic Server security realm (smith). Use Default User Name Mapper Attribute Type and Default Username Mapper Attribute Delimiter attributes of the WebLogic Identity Assertion provider to define this information:

  • Default User Name Mapper Attribute Type—The subject distinguished name (DN) in a digital certificate used to calculate a username. Valid values are: C, CN, E, L, O, OU, S and STREET.

  • Default User Name Mapper Attribute Delimiter—Ends the username. The user name mapper uses everything to the left of the value to calculate a username. The default delimiter is @.

For more information, see "Configure a user name mapper" in the Oracle WebLogic Server Administration Console Help.

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. You then configure the custom user name mapper in the active security realm, using the User Name Mapper Class Name attribute of the WebLogic Identity Assertion provider.

For more information, see "Configure a custom user name mapper" in the Oracle WebLogic Server Administration Console Help.