17 Configuring Identity Assertion Providers

In perimeter authentication, a system outside of Oracle 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.

This chapter includes the following sections:

• About the Identity Assertion Providers

• How an LDAP X509 Identity Assertion Provider Works

• Configuring an LDAP X509 Identity Assertion Provider: Main Steps

• Configuring a Negotiate Identity Assertion Provider

• Configuring a SAML Identity Assertion Provider for SAML 1.1

• Configuring a SAML 2.0 Identity Assertion Provider for SAML 2.0

• Ordering of Identity Assertion for Servlets

• Configuring Identity Assertion Performance in the Server Cache

• Authenticating a User Not Defined in the Identity Store

• Configuring a User Name Mapper

• Configuring a Custom User Name Mapper

About the Identity Assertion Providers

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

Note:

WebLogic Server includes an Oracle Identity Cloud Integrator provider that combines authentication and identity assertion into a single provider. When the identity store is the Oracle Identity Cloud Service, the provider establishes identity (the Subject) on WebLogic Server with the authenticated user, the user's groups, and the user's application roles. See Configuring the Oracle Identity Cloud Integrator Provider.

Multiple Identity Assertion providers can be configured in a security realm, but none are required. Identity Assertion providers can support more than one token type, but only one token type per Identity Assertion provider can be active at a given time. In the Active Type field on the Provider Specific configuration page in the WebLogic Server Administration Console, define the active token type. The WebLogic Identity Assertion provider supports identity assertion with:

• X.509 certificates

• 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 Client Principals field, available from the Provider Specific page in the WebLogic Server Administration Console.

• weblogic-jwt-token tokens

  This token type is used internally for propagating identity in REST invocations of other applications in the domain, and is configured by default.

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.

See Configure Authentication and Identity Assertion providers in the Oracle WebLogic Server Administration Console Online Help.

How an LDAP X509 Identity Assertion Provider Works

The LDAP X509 Identity Assertion provider receives an X.509 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 user name 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 Configuring Keystores.

   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 Online 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 Online Help. For information about using the Negotiate Identity Assertion provider with Microsoft client SSO, see Configuring Single Sign-On with Microsoft Clients

Table 17-1 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 Configuring Single Sign-On with Web Browsers and HTTP Clients Using SAML. For general information about SAML support in WebLogic Server, see Security Assertion Markup Language (SAML) in Understanding Security for Oracle WebLogic Server.

The following sections explain how to configure a SAML Identity Assertion provider for SAML 1.1:

• Asserting Party Registry

• Certificate Registry

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. See the following topics:

• Configuring Asserting Parties

• Configure a SAML 1.1 Asserting Party in the Oracle WebLogic Server Administration Console Online Help.

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 WebLogic Server 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 Web single sign-on, and also for 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. (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 WebLogic Server 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 MBean Reference for Oracle WebLogic Server.

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

For information about how to configure an Identity Provider, see Identity Provider Partners.

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:

• Create and Configure Web Single Sign-On Identity Provider Partners

• Create a SAML 2.0 Web Single Sign-on Identity Provider partner in the Oracle WebLogic Server Administration Console Online Help

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

The following topics explain how to configure Identity Provider partner attributes:

• Partner Lookup Strings Required for Web Service Partners

• Management of Partner Certificates

• Java Interface for Configuring Identity Provider Partner Attributes

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

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

Note:

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

Authenticating a User Not Defined in the Identity Store

The WebLogic Identity Assertion provider supports the ability to authenticate a user who is not defined in the security realm's identity store. Instead, the user is created as a virtual user and is authenticated by means of a Subject that is populated with principals derived from attributes in the X.509 certificate passed in as part of the two-way SSL connection.

The WebLogic Identity Assertion provider is not configured by default to authenticate virtual users. However, by customizing this provider's configuration, you can enable this capability in a WebLogic domain.

Note:

Virtual user authentication is supported only on network ports that are configured for 2-way SSL, with listening servlets using CLIENT-CERT authentication.

Virtual user authentication is not supported in topologies where:

• SSL terminates at a front-end proxy

• Requests are forwarded to a WebLogic Server instance in which SSL has not been enabled

The following sections explain how virtual user authentication works and give the steps to configure it in a WebLogic domain:

How Virtual User Authentication Works in a WebLogic Domain

The flow of virtual user authentication follows the standard Weblogic Server security provider JAAS authentication process. When the WebLogic Identity Assertion provider is configured to allow virtual users, a user who is not defined in the security realm's identity store can be authenticated into the domain as described in the following sequence:

1. When a user issues a request on a resource hosted in the WebLogic domain, a two-way SSL connection is established between that user and WebLogic Server.

2. The WebLogic Identity Assertion provider is invoked to authenticate the user. Because virtual users are enabled for this provider, the X.509 client certificate is passed to the provider as an X.509 type token.

3. The WebLogic Identity Assertion provider invokes the configured user name mapper to:

   1. Extract data from attributes contained in the X.509 certificate.

   2. Map the required certificate attribute data to Subject principals and credentials.

   3. Return a virtual user callback handler to the Login Module for the Virtual User Authentication provider.

   If the WebLogic Identity Assertion provider is configured to allow virtual users, and a configured user name mapper allows virtual users for the given certificate, the virtual user would be considered allowed.

4. The Login Module uses the virtual user callback handler to build an authenticated Subject, which is composed of principals derived from the X.509 certificate attributes. Principals derived from the certificate include the user name and can also include group name, private credentials, public credentials, and other principals, depending on the user name mapper that is used.

5. The WebLogic Security Framework invokes the Virtual User Authentication provider before any other authentication providers. Because the JAAS control flag is set to SUFFICIENT, the user is authenticated into the WebLogic domain. No identity store, such as an LDAP server, is used to validate the user or to obtain additional subject components.

Configuring Two-Way SSL and Managing Certificates Securely

Prior to configuring the WebLogic Security Framework to enable virtual users to be authenticated into a WebLogic domain, Oracle strongly recommends that you optimize the SSL configuration in your domain, and leverage the certificate validation features available in WebLogic Server to ensure that client certificates are properly trusted and validated, by completing the following steps:

1. Configure two-way SSL (SSL with client authentication), in which the server presents a certificate to the client and the client presents a certificate to the server.
2. Configure SSL to limit the minimum SSL version that is enabled for SSL connections. See Specifying the SSL/TLS Protocol Version.
3. Make sure that SSL certificate validation is properly configured for your domain. See SSL Certificate Validation.
4. Configure X.509 certificate revocation (CR) checking, which checks a certificate's revocation status as part of the SSL certificate path validation process. CR checking improves the security of certificate usage by ensuring that received certificates have not been revoked by the issuing certificate authority. See X.509 Certificate Revocation Checking.

Customizing the WebLogic Identity Assertion Provider (DefaultIdentityAsserter)

The WebLogic Identity Assertion provider, also known as the DefaultIdentityAsserter, is configured by default in WebLogic domains. To enable virtual user authentication, you can customize the default instance of this provider in your WebLogic domain, or you can create a separate instance of this provider and customize it instead.

To configure the WebLogic Identity Assertion provider so that virtual user authentication is enabled, complete the following steps:

1. Configure this provider to process X.509 token types. You can set this in the DefaultIdentityAsserterMBean.ActiveTypes attribute.

   To set this attribute using the WebLogic Server Administration Console, you can select the WebLogic Identity Assertion provider and navigate to the Configuration > Common page. In the Active Types field, select the X.509 token type and move it to the Chosen list.

2. Enable virtual users. You can do this by setting the DefaultIdentityAsserterMBean.VirtualUserAllowed attribute to true.

   To set this attribute using the WebLogic Server Administration Console, you can navigate to the Configuration > Provider Specific page for the WebLogic Identity Assertion provider, and select Virtual User Allowed.

3. Enable the default user name mapper. You can do this by setting the DefaultIdentityAsserterMBean.UseDefaultUserNameMapper attribute to true.

   To set this attribute using the WebLogic Server Administration Console, select Use Default User Name Mapper, which is also on the Configuration > Provider Specific page for the WebLogic Identity Assertion provider.

For more information about completing these steps, see Authenticate users not defined in the identity store in Oracle WebLogic Server Administration Console Online Help.

WebLogic Server also supports the use of a custom user name mapper that is an implementation of the weblogic.security.providers.authentication.X509SubjectComponentMapper interface. If you need to map other attributes from the X.509 certificate, such as group principals, private credentials, or public credentials, a custom user name mapper might be appropriate.

Configuring the Virtual User Authentication Provider

The Virtual User Authentication Provider is not available by default in a WebLogic domain. For information about how to configure this provider, see Configuring the Virtual User Authentication Provider. Note that after you add this provider to the security realm:

1. Re-order the authentication providers so that the Virtual User Authentication provider is first. See Re-order Authentication providers in Oracle WebLogic Server Administration Console Online Help.
2. Set the JAAS control flag for the Virtual User Authentication provider to SUFFICIENT. See Set the JAAS control flag in Oracle WebLogic Server Administration Console Online Help.

Using WLST to Configure Virtual User Authentication

This section provides an example of configuring virtual user authentication in a WebLogic domain. Example 17-1 shows the following:

1. Connecting to the WebLogic Server instance.

2. Creating an instance of a Virtual User Authentication provider.

3. Ordering the Virtual User Authentication provider first among the authentication providers in the security realm.

4. Enabling virtual users in the WebLogic Identity Assertion provider (DefaultIdentityAsserter).

5. Enabling the default user name mapper provided by WebLogic Server.

6. Saving and activating changes to the security realm.

Example 17-1 Configuring the Virtual User Authentication Provider and Enabling Virtual Users

    connect('','','t3://host:port')
    Please enter your username :
    Please enter your password :
    ...
    edit()
    startEdit()
    print 1
    cd('/SecurityConfiguration/'+domainName+'/Realms/myrealm')
    print 2
    auth=cmo.lookupAuthenticationProvider('VirtualUserAtnProvider')
    print 3
    if auth == None:
      print 4
      auth = cmo.createAuthenticationProvider('VirtualUserAtnProvider','weblogic.security.providers.authentication.VirtualUserAuthenticator')
    print auth
    set('AuthenticationProviders',jarray.array([ObjectName('Security:Name=myrealmVirtualUserAtnProvider'),ObjectName('Security:Name=myrealmDefaultAuthenticator'),ObjectName('Security:Name=myrealmDefaultIdentityAsserter')],ObjectName))
    print 5
 
    cd('AuthenticationProviders/DefaultIdentityAsserter')
    set('VirtualUserAllowed','true')
    print( "VirtualUserAllowed set to true" )
    set('UseDefaultUserNameMapper','true')
    print( "UseDefaultUserNameMapper set to true" )
    save()
    activate()

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 can map either of the following:

• The digital certificate of a Web browser or Java client to a user in a WebLogic Server security realm.

• Attributes contained in the X.509 certificate to Subject principals and credentials for a user that is not defined in the identity store of the security realm (see Authenticating a User Not Defined in the Identity Store).

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, as described in Configuring a Custom User Name Mapper.

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 ([e-mail]) 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. The default attribute type is E.

• 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 example, when extracting a user name from an email address, the user name mapper uses all characters in the email address up to the @ character. Therefore, if you want the user name mapper to map a different attribute in the Subject DN — for example, the Common Name, or CN — it might be appropriate to specify a different delimiter.

See Configure a user name mapper in the Oracle WebLogic Server Administration Console Online Help.

Configuring a Custom User Name Mapper

You can also write a custom user name mapper to map a token to a WebLogic user name, or to a virtual user, according to whatever scheme is appropriate for your needs. Note the following:

• A custom user name mapper that maps a token to a WebLogic user must be an implementation of the weblogic.security.providers.authentication.UserNameMapper interface.

• A custom user name mapper that maps an X.509 token to Subject principals that are used to authenticate a virtual user — that is, a user that is not defined in the security realm identity store — must be an implementation of the weblogic.security.providers.authentication.X509SubjectComponentMapper interface.

  If you need to map other attributes from the X.509 certificate, such as group principals, private credentials, or public credentials, a custom user name mapper might be appropriate.

See Configure a custom user name mapper in the Oracle WebLogic Server Administration Console Online Help.