9 Configuring Credential Mapping Providers

Credential mapping is the process whereby the authentication and authorization mechanisms of a remote system (for example, a legacy system or application) obtain an appropriate set of credentials to authenticate remote users to a target WebLogic resource. The WebLogic Credential Mapping provider maps Oracle WebLogic Server subjects to the username/password pairs to be used when accessing such resources.

The following topics are included:

Configuring a WebLogic Credential Mapping Provider

By default, most configuration options for the WebLogic Credential Mapping provider are defined. You do have the option of adjusting the expiration interval of the weblogic-jwt-token token type, which is used internally to propagate identity for REST invocations of other applications running in the domain. By default, the expiration interval is set to 3 minutes. However, you can adjust the interval from the Provider Specific configuration page for this security provider.

Note:

WebLogic Server provides the option of setting Credential Mapping Deployment Enabled, which specifies whether or not the Credential Mapping provider imports credential maps from a resource adapter's deployment descriptor (weblogic-ra.xml file) into the security realm. However, this option is now deprecated. Deploying credential maps from a weblogic-ra.xml file is no longer supported by WebLogic Server.

In order to support Credential Mapping Deployment Enabled, a Credential Mapping provider must implement the DeployableCredentialProvider SSPI. The credential mapping information is stored in the embedded LDAP server.

Refer to the following topics:

Configuring a PKI Credential Mapping Provider

The Public Key Infrastructure (PKI) Credential Mapping provider included in WebLogic Server maps a WebLogic Server subject and target resource to a key pair or a public certificate that can be used by applications when accessing the targeted resource. The PKI Credential Mapping provider uses the subject and resource name to retrieve the corresponding credential from the keystore.

To use the PKI Credential Mapping provider, you need to:

  1. Configure keystores with appropriate keys and distribute the keystores on all machines in a WebLogic Server cluster. Setting up keystores is not a WebLogic Server function. For information about setting up keystores, see the help for the Java keytool utility at the following locations:
    See also Configuring Keystores for information about keystores and keys in WebLogic Server.
  2. Configure a PKI Credential Mapping provider. A PKI Credential Mapping provider is not already configured in the default security realm (myrealm). See PKI Credential Mapper Attributes and Configure Credential Mapping providers in the Oracle WebLogic Server Administration Console Online Help.
  3. Create credential mappings. See Create PKI Credential Mappings in the Oracle WebLogic Server Administration Console Online Help.

This section contains the following topics:

PKI Credential Mapper Attributes

To configure the PKI Credential Mapping provider, set values for these attributes. See Configure Credential Mapping Providers in the Oracle WebLogic Server Administration Console Online Help.

  • Keystore Provider—A keystore provider for the Java Security API. If no value is specified, the default provider class is used.

  • Keystore Type— JKS (the default) or PKCS12.

  • Keystore Pass Phrase—Password used to access the keystore

  • Keystore File Name—Location of the keystore relative to the directory where the server was started.

In addition, two optional attributes determine how the PKI Credential Mapping provider locates credential mappings in cases where the exact resource or subject may not be available:

  • Use Resource Hierarchy—A credential is located by traversing up the resource hierarchy for each type of resource. The search for all possible PKI credentials will start from the specific resource and will walk up the resource hierarchy to find all possible matches. This attribute is enabled by default.

  • Use Initiator Group Names—When a subject is passed to the PKI Credential Mapper provider, a credential is located by examining the groups of which the initiator is a member. This is enabled by default.

Credential Actions

Optionally, you can label a credential mapping with a credential action. You can do this in the WebLogic Server Administration Console when you create the credential mapping. The credential action is an arbitrary string that distinguishes credential mappings used in different circumstances. For example, one credential mapping could decrypt a message from a remote resource and another credential mapping could sign messages to be sent to the same resource. The subject initiator and the target resource are not sufficient to distinguish these two credential mappings. You can use the credential action to label one of these credential mappings something like decrypt and the other one sign. Then, the container calling the PKI Credential Mapping provider can provide the desired credential action value in the ContextHandler that is passed to the provider.

For information about adding credential actions to PKI credential mappings, see Create PKI Credential Mappings in the Oracle WebLogic Server Administration Console Online Help.

Configuring a SAML Credential Mapping Provider for SAML 1.1

WebLogic Server includes SAML Credential Mapping provider Version 2. It provides greatly enhanced configuration options and is recommended for new deployments. A security realm can have not more than one SAML Credential Mapping provider, and if the security realm has both SAML Credential Mapping provider and a SAML Identity Assertion provider, both must be of the same version.

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

This section includes the following topics:

Configuring Assertion Lifetime

A SAML Assertion's validity is typically time-limited. The default time-to-live for assertions generated by the SAML Credential Mapping provider is specified by the DefaultTimeToLive attribute. You can override the default time-to-live for assertions generated for different SAML Relying Parties.

Normally, an assertion is valid from the NotBefore time, which defaults to (roughly) the time the assertion was generated, until the NotOnOrAfter time, which is calculated as (NotBefore + TimeToLive). To allow the Credential Mapper to compensate for clock differences between the source and destination sites, you can configure the SAML Credential Mapping provider's DefaultTimeToLiveDelta attribute. This time-to-live offset value is a positive or negative integer indicating how many seconds before or after "now" the assertion's NotBefore value should be set to. If you set a value for DefaultTimeToLiveDelta, then the assertion lifetime is still calculated as (NotBefore + TimeToLive), but the NotBefore value is set to (now + TimeToLiveDelta). For example, given the following settings:

DefaultTimeToLive = 120
DefaultTimeToLiveDelta = -30

an assertion when generated would have a lifetime of two minutes (120 seconds), starting 30 seconds before it is generated.

Relying Party Registry

When you configure WebLogic Server to act as a source of SAML security assertions, you need to register the parties that may request SAML assertions to be generated. For each SAML Relying Party, you can specify the SAML profile used, details about the Relying Party, and the attributes expected in assertions for the Relying Party. See the following topics:

Configuring a SAML 2.0 Credential Mapping Provider for SAML 2.0

The SAML 2.0 Credential Mapping provider in WebLogic Server generates SAML 2.0 assertions that can be used to assert identity in the SAML 2.0 Web SSO Profile and the WS-Security SAML Token Profile version 1.1 use cases. The SAML 2.0 Credential Mapping provider generates the assertion types listed and described in Table 9-1.

Table 9-1 Assertion Types Supported by the SAML 2.0 Credential Mapping Provider

Assertion Type Description
bearer

The subject of the assertion is the bearer of the assertion, subject to optional constraints on confirmation using attributes that may be included in the <SubjectConfirmationData> element of the assertion.

Used for all assertions generated for the SAML 2.0 Web Browser SSO Profile and with the Web Service Security SAML Token Profile 1.1.

sender-vouches

The Identity Provider (different from the subject) vouches for the verification of the subject. The receiver must have a trust relationship with the Identity Provider.

Used with the Web Service Security SAML Token Profile 1.1 only.

holder-of-key

The subject represented in the assertion uses an X.509 certificate that may not be trusted by the receiver to protect the integrity of the request messages.

Used with the Web Service Security SAML Token Profile 1.1 only.

For general information about WebLogic Server's support for SAML 2.0, see Security Assertion Markup Language (SAML) and Single Sign-On with the WebLogic Security Framework in Understanding Security for Oracle WebLogic Server. For information about how to use the SAML 2.0 Credential Mapping provider in a SAML 2.0 single sign-on configuration, see Configuring Single Sign-On with Web Browsers and HTTP Clients Using SAML. For information about specifying the confirmation method for assertions generated for web service Service provider partners, see Using Security Assertion Markup Language (SAML) Tokens For Identity in Securing WebLogic Web Services for Oracle WebLogic Server.

This section includes the following topics:

SAML 2.0 Credential Mapping Provider Attributes

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

To configure the SAML 2.0 Credential Mapping provider, set the following attributes:

  • Issuer URI

    Name of this security provider. The value that you specify should match the Entity ID specified in the SAML 2.0 General page that configures the per-server SAML 2.0 properties.

  • Name Qualifier

    Used by the Name Mapper class as the security or administrative domain that qualifies the name of the subject. This provides a means to federate names from disparate user stores while avoiding the possibility of subject name collision.

  • Assertion life time

    Values that limit the life time of generated assertions during which they may be used. Expired assertions cannot be made available for use.

  • Web service assertion signing key alias and passphrase

    Used for signing generated assertions.

  • Custom name mapper class

    The custom Java class that overrides the default SAML 2.0 Credential Mapping provider name mapper class, which maps Subjects to identity information contained in the assertion.

  • Generate attributes

    Specifies whether group membership information associated with the authenticated Subject is included in generated assertions.

Service Provider Partners

When you configure WebLogic Server to act as an Identity Provider, you need to create and configure the Service Provider partners for whom SAML 2.0 assertions are generated. When an Identity Provider site needs to generate an assertion, the SAML 2.0 Credential Mapping provider determines the Service Provider partner for whom the assertion must be generated, and generates it according to the configuration of that Service Provider partner.

The way in which you configure a Service Provider partner, and the specific information you configure for that partner, depends upon whether the partner is used for web single sign-on or web services. Configuring a web single sign-on Service Provider partner consists of importing that partner's metadata file and establishing additional basic information about that partner, such as the following:

  • Determining whether SAML documents, such as authentication responses, SAML artifacts, and artifact requests, must be signed

  • Certificates used for validating signed documents received from this partner

  • The binding to be used for sending SAML artifacts to this partner

  • The client user name and password used by this partner when connecting to the local site's binding

For details about configuring a Service Provider partner for web single sign-on, see:

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

  • Audience URIs, which specify an audience restriction to be included in assertions generated for 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

  • Values that specify the life span attributes of assertions generated for this partner

  • Confirmation method for assertions received from this partner

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

This section includes the following topics:

Partner Lookup Strings Required for Web Service Partners

For web service Service 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 that consists of the target service 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 Service Provider partner for which a SAML 2.0 assertion needs to be generated.

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 is included in the generated assertion. The ability to specify a partner lookup string that is also an Audience URI eliminates the need to specify a given target URL twice: once for lookup, and again for audience restriction.

Note:

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

This section includes the following topics:

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

Table 9-2 Service 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:-:http://www.avitek.com:7001/myserver/myservicecontext/myservice-endpoint specifies the endpoint that can be matched to this Service Provider, for which an assertion should be generated.

This form of partner lookup string excludes the endpoint URL from being added as an Audience URI in the generated assertion.

target:+:<endpoint-url>

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

Using the plus sign (+) in the lookup string results in the endpoint URL being added as an Audience URI in the assertion generated for this Service Provider partner.

target:*:<endpoint-url>

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

If more than one Service 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 in the generated assertion.

Note:

Configuring one or more partner lookup strings for a Service 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 generated.

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 generated for this Service 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 Service Provider partner entry, one or more of the default partner's Audience URI entries may contain a wildcard match that works for all targets. The actual wildcard URI may depend on the specific format used by the web service run time. For example:

  • target:*:http://

  • target:*:https://

Management of Partner Certificates

The SAML 2.0 Credential Mapping provider manages a set of trusted certificates for each partner configured for web single sign-on. Whenever a signed authentication or artifact request is received during a message exchange with a partner, the trusted certificate is used to verify the partner's signature. Partner certificates are used for the following purposes:

  • To validate trust when the SAML 2.0 Credential Mapping provider receives a signed authentication request or artifact request.

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

From the WebLogic Server Administration Console, you can view a web single sign-on Service Provider partner's signing certificate and transport layer client certificate in the partner management pages of the configured SAML 2.0 Credential Mapping provider.

Java Interface for Configuring Service Provider Partner Attributes

For details about the available operations on web service partners, see the com.bea.security.saml2.providers.registry.Partner Java interface in the Java API Reference for Oracle WebLogic Server.