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.
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: 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:
Each security realm must have one at least one Authentication provider configured. The WebLogic Security Framework is 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.
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 Administration Console Online 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.
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.
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. Use the Reorder button on the Security Realms 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 Administration Console Online Help.
The WebLogic Authentication provider uses WebLogic Server’s embedded LDAP server to store user and group membership information. This provider allows you to edit, list, and manage users and group membership. 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:
DefaultAuthenticator
.
WebLogic Server includes the following LDAP Authentication providers:
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.
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:
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.
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:
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.
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.To configure an LDAP Authentication provider:
SSLEnabled
attribute.
The LDAP Authentication providers in this release of WebLogic Server are configured to work readily with the 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.
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.
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 comma and a port number. In addition, set the Parallel Connect Delay and Connection Timeout attributes for the LDAP Authentication provider:
The following examples present scenarios that occur when an LDAP Authentication provider is configured for LDAP failover.
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:
WebLogic Server attempts to connect to directory.knowledge.com
. After 10 seconds, the connect attempt times out and WebLogic Server attempts to connect to the next specified host (people.catalog.com
). WebLogic Server then uses people.catalog.com
as the LDAP Server for this connection.
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.
To improve the performance of WebLogic and LDAP Authentication providers:
tokenGroups
option. The tokenGroups
option holds the entire flattened group membership for a user as an array of system ID (SID) values. The SID values are specially indexed in the Active Directory and yield extremely fast lookup response. See Configuring the Active Directory Authentication Provider to Improve Performance.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):
In planning your cache settings, bear in mind the following considerations:
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:
cn
.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):
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):
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). |
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:
For information about adding an RDBMS Authentication provider to your security realm, see Configure Authentication and Identity Assertion providers in the Administration Console Online 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.
All three RDBMS Authentication providers include these configuration options.
The Data Source Name specifies the WebLogic Server data source to use to connect to the database.
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.
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 Administration Console Online Help.
For detailed information about configuring a SQL Authentication provider, see Security Realms: Security Providers: SQL Authenticator: Provider Specific in the Administration Console Online Help. In addition to the attributes described in Common RDBMS Authentication Provider Attributes, the SQL Authentication provider has the following configurable attributes.
The following attributes govern how the RDBMS Authentication provider and its underlying database handle user passwords:
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:
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. |
For detailed information about configuring a Read-Only SQL Authentication provider, see Security Realms: Security Providers: Read-Only SQL Authenticator: Provider Specific in the Administration Console Online 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.
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.
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 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.
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. |
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:
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:
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:
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:
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 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:
mapUPNNames
attribute to FIRST.mapUPNNames
attribute to LAST.mapUPNNames
attribute to NEVER.
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:
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 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
WebLogic Server includes a Password Validation provider, which manages and enforces a set of configurable password composition rules. When configured in a security realm, the Password Validation provider is automatically invoked by a supported authentication provider whenever a password is created or updated for a user in that realm. The Password Validation provider then performs a check to determine whether the password meets the criteria established by the composition rules, and the password is accepted or rejected as appropriate.
The following authentication providers can be used with the Password Validation provider:
The Password Validation provider may be configured only via the WebLogic Scripting Tool (WLST). This provider cannot be configured via the WebLogic Administration Console. 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:
The password composition rules you can configure for the Password Validation provider include the following:
Table 5-3 describes each of the password composition rules you can configure, identifies the default values of those rules, and recommends settings you can use to create strong passwords that cannot be easily determined.
Note: | 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. |
The minimum number of characters that the password must contain. In order to be accepted, the password must contain at least as many characters as the value specified.
|
||||
For information about setting these composition rules, see Using WLST to Create and Configure the Password Validation Provider.
By default, the WebLogic Authentication provider requires a minimum password length of 8 characters. 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:
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.
The Password Validation provider can be administered in the security realm only via WLST. 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 to do this, providing sample WLST code snippets:
Listing 5-1 shows an example of WLST code that creates an instance of the Password Validation provider in the security realm. This code does the following:
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()
Listing 5-2 shows an example of WLST code that sets the composition rules for the Password Validation provider. For information about the rules attributes set in this script, see Table 5-3.
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.setRejectEqualOrContainUsername(true)
pwdvalidator.setRejectEqualOrContainReverseUsername(true)
print " --- Configuration of SystemPasswordValidator complete ---"
except Exception,e:
print e
save()
activate()
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:
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 only 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 Administration Console Online Help. In addition, see the following sections:
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:
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:
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.
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 Administration Console Online Help. For information about using the Negotiate Identity Assertion provider with Microsoft client SSO, see Configuring Single Sign-On with Microsoft Clients.
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 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 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 WebLogic Security.
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:
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:
You can add trusted certificates to the certificate registry through the Administration Console:
On the Management Certificates page, you can add, view, or delete certificates from the registry.
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:
The SAML 2.0 Identity Assertion provider does the following:
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. The SAML2IdentityAsserterMBean
is described at the following location:
For information about how to use the SAML 2.0 Identity Assertion provider in a SAML single sign-on configuration, see 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 WebLogic Security. 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.
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:
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:
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:
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.
For more information about configuring web service Service Provider partners, see Create a SAML 2.0 Web Service Identity Provider partner in the Administration Console Online Help.
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:
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. |
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-5.
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 . |
Note: | 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. |
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. |
Note: | 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.) |
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:*:/
.
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:
The following certificates, which are obtained from each configured Identity Provider partner, are required:
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.
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.
Operations on web service partners are available in the
com.bea.security.saml2.providers.registry.Partner
Java interface.
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:
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. |
<
TOKEN
>
where <
TOKEN
>
is one of the active tokens types configured for the Identity Assertion provider in the default security realm.<
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:
FOO
header over a two-way SSL connection, X.509 is used for identity assertion.FOO
header and a WL-Proxy-Client-BAR
header, the BAR
token is used for identity assertion.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:
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.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.
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:
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. |
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:
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:
C
, CN
, E
, L
, O
, OU
, S and STREET
.For more information, see Configure a user name mapper in the Administration Console Online Help.
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 custom user name mappers in the Administration Console Online Help.