9 SAML APIs

The Security Assertion Markup Language, SAML, is an XML-based protocol for exchanging security information between disparate entities. The SAML standard defines a framework for exchanging security information between software entities on the Web. SAML security is based on the interaction of asserting and relying parties.

SAML provides single sign-on capabilities; users can authenticate at one location and then access service providers at other locations without having to log in multiple times.

WebLogic Server supports SAML versions 2.0 and 1.1. The WebLogic Server implementation:

For a general description of SAML and SAML assertions in a WebLogic Server environment, see "Security Assertion Markup Language (SAML)" in Understanding Security for Oracle WebLogic Server.

For information on configuring a SAML credential mapping provider, see "Configuring a SAML Credential Mapping Provider for SAML 1.1" and "Configuring a SAML 2.0 Credential Mapping Provider for SAML 2.0" in Securing Oracle WebLogic Server

For access to the SAML specifications, go to http://www.oasis-open.org. Also see the Technical Overview of the OASIS Security Assertion Markup Language (SAML) V1.1 (http://www.oasis-open.org/committees/download.php/6628/sstc-saml-tech-overview-1.1-draft-05.pdf) and Security Assertion Markup Language (SAML) 2.0 Technical Overview (http://www.oasis-open.org/committees/download.php/11511/sstc-saml-tech-overview-2.0-draft-03.pdf).

This section covers the following topics:

SAML API Description

Table 9-1 lists the WebLogic SAML APIs. Table 9-2 lists the WebLogic SAML 2.0 APIs. See the Javadoc for details.

Table 9-1 WebLogic SAML APIs

WebLogic SAML API Description

weblogic.security.providers.saml

The WebLogic SAML package.

SAMLAssertionStore

Interface that defines methods for storing and retrieving assertions for the Artifact profile. This interface is deprecated in favor of SAMLAssertionStoreV2.

SAMLAssertionStoreV2

The SAMLAssertionStoreV2 interface extends the SAMLAssertionStore interface, adding methods to support identification and authentication of the destination site requesting an assertion from the SAML ARS.

Note that V2 refers to the second version of the WebLogic SAML provider, not to version 2 of the SAML specification.

SAMLCredentialAttributeMapper

Interface used to perform mapping from Subject to SAMLAssertion attributes.

SAMLCredentialNameMapper

Interface that defines methods used to map subject information to fields in a SAML assertion.

SAMLIdentityAssertionAttributeMapper

Interface used to perform mapping from SAML Attribute Statement to Attribute Principals.

SAMLIdentityAssertionNameMapper

Interface that defines methods used to map information from a SAML assertion to user and group names.

SAMLUsedAssertionCache

Interface that defines methods for caching assertion IDs so that the POST profile one-use policy can be enforced.

Classes implementing this interface must have a public no-arg constructor.

SAMLNameMapperInfo

Instances of this class are used to pass user and group information to and from the name mappers. The class also defines several useful constants.

SAMLAssertionStoreV2.AssertionInfo

The AssertionInfo class is returned by SAMLAssertionStoreV2.retrieveAssertionInfo(). It contains the retrieved assertion and related information. An implementation of the SAMLAssertionStoreV2 interface would have to return this class.

SAMLAttributeInfo

A class that represents a single attribute of a SAMLAssertion AttributeStatement.

SAMLAttributeStatementInfo

A class that represents an AttributeStatement in a SAMLAssertion.

SAMLNameMapperInfo

The SAMLNameMapperInfo is used to represent user name and group information for SAML assertions.

SAMLCommonPartner

Abstract representation of attributes common to a SAML 1.1 Partner.

SAMLRelyingParty

Represents a SAML Relying Party entry in the SAML Relying Party registry.

SAMLAssertingParty

Represents a SAML Asserting Party entry in the LDAP Asserting Party registry.

SAMLPartner

Abstract representation of a SAML partner.


Note:

The SAML name mapper classes are required to be in the system classpath. If you create a custom SAMLIdentityAssertionNameMapper, SAMLCredentialNameMapper, SAMLAssertionStore, or SAMLUsedAssertionCache, you must place the respective class in the system classpath.

Table 9-2 WebLogic SAML 2.0 APIs

WebLogic SAML 2.0 APIs Description

com.bea.security.saml2.providers

Provides interfaces and classes for the configuration, control, and monitoring of SAML 2.0 security providers in a WebLogic security realm.

SAML2AttributeInfo

A class that represents a single attribute of a SAML 2.0 Assertion AttributeStatement.

SAML2AttributeStatementInfo

A class that represents an AttributeStatement in a SAML 2.0 Assertion.

SAML2CredentialAttributeMapper

Interface used to perform mapping from Subject to SAML 2.0 Assertion attributes.

SAML2CredentialNameMapper

Interface used to perform the mapping of user and group information to SAML 2.0 assertions.

SAML2IdentityAsserterAttributeMapper

Interface used to perform mapping from SAML 2.0 Attribute Statement to Attribute Principals.

SAML2IdentityAsserterNameMapper

Interface used to perform the mapping of user information contained in a SAML 2.0 assertion to a local user name.

SAML2NameMapperInfo

The SAML2NameMapperInfo is used to represent user name and group information contained in SAML 2.0 assertions.

com.bea.security.saml2.providers.registry

Abstract interfaces for SAML 2.0 Identity Provider and Service Provider partners and metadata.

BindingClientPartner

Binding Client partner is a partner that supports backend channel communication.

IdPPartner

Abstract representation of a SAML 2.0 Identity Provider partner.

Endpoint

Abstract representation of a SAML 2.0 service endpoint.

IndexedEndpoint

This class represents the end point that could be indexed, like Artifact Resolution Service's end point.

MetadataPartner

Metadata partner contains contact information for the partner, which is mainly required by the SAML 2.0 metadata profile.

Partner

Abstract representation of a SAML 2.0 partner. This interface defines mandatory information for a partner.

SPPartner

Abstract representation of a SAML 2.0 Service Provider partner.

WebSSOIdPPartner

Abstract representation of a SAML 2.0 Identity Provider partner for Web SSO profile.

WebSSOPartner

Abstract representation of a SAML 2.0 partner for Web SSO profile.

WebSSOSPPartner

Abstract representation of a SAML 2.0 Service Provider partner for Web SSO profile.

WSSIdPPartner

Abstract representation of a SAML 2.0 Identity Provider partner for WSS SAML Token profile.

WSSPartner

Abstract representation of a SAML 2.0 partner for WSS SAML Token profile.

WSSSPPartner

Abstract representation of a SAML 2.0 Service Provider partner for WSS SAML Token profile. It has no specific attributes/methods.


Custom POST Form Parameter Names

The parameters names passed to the POST form when a custom POST form is specified for SAML POST profile handling depend on which SAML provider is configured.

  • For the WebLogic Server 9.1and higher, Federation Services implementation (in effect when V2 providers are configured), see Table 9-3.

  • For the WebLogic Server 9.0 SAML services implementation (in effect when V1 providers are configured), see Table 9-4.

The tables provide the parameter names and their data types (required for casting the returned Java Object).

For both implementations, the SAML response itself is passed using the parameter name specified by SAML:

SAMLResponse (String): The base64-encoded SAML Response element.

Table 9-3 SAML V2 Provider Custom POST Form Parameters

Parameter Description

TARGET (String)

The TARGET URL specified as a query parameter on the incoming Intersite Transfer Service (ITS) request.

SAML_AssertionConsumerURL (String)

The URL of the Assertion Consumer Service (ACS) at the destination site (where the form should be POSTed).

SAML_AssertionConsumerParams (Map)

A Map containing name/value mappings for the assertion consumer parameters configured for the relying party. Names and values are Strings.

SAML_ITSRequestParams (Map)

A Map containing name/value mappings for the query parameters received with the ITS request. Names and values are Strings. The Map may be empty. TARGET and Rich Presence Information Data Format (RPID) parameters are removed from the map before passing it to the form.


Table 9-4 SAML V1 Provider Custom POST Form Parameters

Parameter Description

targetURL (String)

The TARGET URL specified as a query parameter on the incoming ITS request.

consumerURL (String)

The URL of the ACS at the destination site (where the form should be POSTed).


Creating Assertions for Non-WebLogic SAML 1.1 Relying Parties

If you use the SAML 1.1 Credential Mapping Provider Version 2 to configure a source site, but configure a third-party SAML Relying Party that is implemented on a non-WebLogic Server platform, the SAML assertions generated by WebLogic Server might not support all of the attributes required by the configured third-party SAML Relying Party. In this case the Relying Party might be unable to work with the Asserting Party because certain expected attributes of the assertion are not available.

You can create a custom SAML name mapper that maps Subjects to the specific SAML 1.1 assertion attributes required by your third-party SAML Relying Party by implementing the SAMLCredentialAttributeMapper interface, which is provided by WebLogic Server. Details about the SAMLCredentialAttributeMapper are available in the Oracle WebLogic Server API Reference.

The following sections explain how to create a custom SAML name mapper:

Overview of Creating a Custom SAML Name Mapper

To create a custom implementation of the SAMLCredentialAttributeMapper interface, you must do the following:

  • Use the following classes to describe the attribute data for an assertion:

  • Also implement the SAMLCredentialNameMapper interface. The SAMLCredentialAttributeMapper and SAMLCredentialNameMapper interfaces must both be in the same implementation.

    By also implementing the SAMLCredentialNameMapper interface, you can later use the WebLogic Server Administration Console to set the NameMapperClassName attribute to the class name of this SAMLCredentialAttributeMapper instance.

    You configure the custom SAML name mapper in the active security realm, using the User Name Mapper Class Name attribute of the SAML Credential Mapping Provider Version 2.

Do You Need Multiple SAMLCredentialAttributeMapper Implementations?

The name mapper class name you configure for a SAML Credential Mapping Provider Version 2, as described in Make the Custom SAMLCredentialAttributeMapper Class Available in the Console, is used as the default for that provider. However, you can optionally set a name mapper class name specific to any or all of the Relying Parties configured for the SAML Credential Mapping Provider Version 2. Setting the name mapper class name in this manner overrides the default value. If the configured SAML Relying Parties require different attributes, you can create multiple SAMLCredentialAttributeMapper implementations.

Classes, Interfaces, and Methods

This section describes the new classes, interfaces, and methods that you must use when creating your custom SAML name mapper implementation. See Example Custom SAMLCredentialAttributeMapper Class, for example code.

SAMLAttributeStatementInfo Class

Example 9-1 shows the methods and arguments in the SAMLAttributeStatementInfo class. Embedded comments provide additional information and context.

Example 9-1 Listing of SAMLAttributeStatementInfo Class

/**
 * A class that represents the attributes of an AttributeStatement
 * in a SAML Assertion
 */

class SAMLAttributeStatementInfo {

/**
 * Constructs a SAMLAttributeStatementInfo with
 * no attributes. The SAMLAttributeStatementInfo
 * represents a empty SAMLAttributeStatement. It is
 * expected that SAMLAttributeInfo elements will be
 * added to this instance.
 *

Public SAMLAttributeStatementInfo();

/**
 * Constructs a SAMLAttributeStatementInfo containing multiple
 * SAMLAttributeInfo elements. The SAMLAttributeStatementInfo
 * represents a SAML AttributeStatement with multiple Attributes.
 *
 *
 * @param data SAMLAttributeInfo
 */

    public SAMLAttributeStatementInfo(Collection data);

/**
 * returns a Collection of SAMLAttributeInfo elements. The
 * collection represents the Attributes contained by
 * a single AttributeStatement of a SAML Assertion
 *
 * The returned Collection is immutable and may be empty.
 *
 * @return Collection
 */

    public Collection getAttributeInfo();

/**
 * adds a Collection of SAMLAttributeInfo instances to
 * this SAMLAttributeStatementInfo instance, to the
 * end of the existing list, in the order that the
 * param Collection iterates through the Collection.
 *
 * See SAMLAttributeInfo(String, String, Collection)
 * for information on parameter handling.
 *
 * @param data
 *
 */

    public void setAttributeInfo(Collection data);

/**
 * Adds a single SAMLAttributeInfo instance to this
 * SAMLAttributeStatementInfo instance, at the end of
 * the existing list.
 *
 * See SAMLAttributeInfo(String, String, Collection)
 * for information on parameter handling.
 *
 * @param info
 */

    public void addAttributeInfo(SAMLAttributeInfo info);
SAMLAttributeInfo Class

Example 9-2 shows the methods and arguments in the SAMLAttributeInfo class. Embedded comments provide additional information and context.

Example 9-2 Listing of SAMLAttributeInfo Class

/**
 * A class that represents a single Attribute of a SAML Assertion
 * AttributeStatement.
 */

class SAMLAttributeInfo {

/**
 * Constructs a SAMLAttributeInfo instance with all null fields
 */

   public SAMLAttributeInfo();

/**
 * Constructs a SAMLAttributeInfo instance representing the SAML 1.1
 * Attribute fields
 *
 * null elements of the Collection are ignored.
 * Elements with null 'name' or 'namespace' fields
 * are ignored; the resulting SAMLAttributeInfo will not
 * be included in a created SAMLAssertion. Null
 * attribute values are added as the empty string (ie, “”).
 * @param name String
 * @param namespace String
 * @param values Collection of String values
 */

    public SAMLAttributeInfo(String name, String namespace, Collection values;

/**
 * Constructs a SAMLAttributeInfo instance representing the attribute fields
 * See SAMLAttributeInfo(String, String, Collection) for
 * information on parameter handling.
 *
 * @param name String
 * @param namespace String
 * @param value String
 */

    public SAMLAttributeInfo(String name, String namespace, String value);

/**
 * sets the name and namespace of this attribute
 * See SAMLAttributeInfo(String, String, Collection) for
 * information on parameter handling.
 *
 * @param name String, cannot be null
 * @param namespace String, cannot be null
 */

    public void setAttributeName(String name, String namespace);

/**
 * returns the name of this attribute.
 * @return String
 */

    public String getAttributeName();

/**
 * returns a String representing this attribute's namespace
 * @return String
 */

    public String getAttributeNamespace();

/**
 * sets a Collection of Strings representing this attribute's values
 * an empty collection adds no values to this instance, collection elements
 * that are null are added as empty strings.
 *
 * @param values Collection
 */

    public void setAttributeValues(Collection values);

/**
 * adds a single String value to the end
 * of this instance's Collection of elements
 * See SAMLAttributeInfo(String, String, Collection) for
 * information on parameter handling.
 *
 * @param value String
 */

    public void addAttributeValue(String value);

/**
 * returns a Collection of Strings representing this
 * attribute's values, in the order they were added.
 * If this attribute has no values, the returned
 * value is null.
 *
 * @return Collection
 */

    public Collection getAttributeValues();
}

SAMLCredentialAttributeMapper Interface

The SAML Credential Mapping Provider Version 2 determines if the custom SAML name mapper is an implementation of the attribute mapping interface and, if so, calls the methods of the attribute mapping interface to obtain SAML attribute name/value pairs to write to the generated SAML assertion. If the implementation does not support the attribute mapping interface, attribute mapping is silently skipped.

The SAML Credential Mapping Provider Version 2 does not validate the attribute names or values obtained from the custom attribute mapper. Attribute names and values are treated as follows:

  • Any attribute with a non-null attribute name and namespace is written to the SAML assertion.

  • An attribute with a null attribute name or namespace is ignored, and subsequent attributes of the same Collection are processed normally.

  • Any attribute with a null value is written to the SAMLAttributeInfo instances with a value of "". The resulting SAML assertion is written as the string <AttributeValue></AttributeValue>.

Example 9-3 Listing of SAMLCredentialAttributeMapper Interface

/**
 * Interface used to perform mapping of Subject to SAMLAssertions
 * attributes.
 * <p>
 * To specify an instance of this interface to be used by the SAML
 * Credential Mapper, set the <tt>NameMapperClassName</tt> attribute.
 * <p>
 * Classes implementing this interface must have a public no-arg
 * constructor and must be in the system classpath.
 *
 * @author Copyright (c) 2008 by BEA Systems, Inc. All Rights Reserved.
 */

public interface SAMLCredentialAttributeMapper
{
/**
 * Maps a <code>Subject</code> to a set of values used to construct a
 * <code>SAMLAttributeStatementInfo</code> element for a SAML assertion.
 * The returned <code>Collection</code> contains
 * SAMLAttributeStatementInfo elements, each element
 * of which will be used to
 * construct a SAML <code>AttributeStatement</code> element for the SAML
 * assertion.
 *
 * @param subject The <code>Subject</code> that should be mapped.
 * @param handler The <code>ContextHandler</code> passed to the SAML
 * Credential Mapper.
 *
 * @return A <code>Collection</code> of SAMLAttributeStatementInfo
 * instances,or <code>null</code> if no mapping is made.
 */

    public Collection mapAttributes(Subject subject, ContextHandler handler);
New Methods for SAMLNameMapperInfo Class

The SAMLCredentialNameMapper calls new methods on the SAMLNameMapperInfo class to get and set the authentication method attribute to be written to the SAML Assertion.

The new methods are shown in Example 9-4. Embedded comments provide additional information and context.

Example 9-4 Listing of SAMLNameMapperInfo Class

public class SAMLNameMapperInfo
{
[ existing definition ]
/**
 * Called by the SAML Credential Name Mapper implementation to set
 * the authentication method attribute to be written to the SAML Assertion.
 * See SAML 1.1 Assertions and Protocols, Section 7.1 for possible
 * values returned.
 *
 * @param value the Authentication Method
 */

    public void setAuthenticationMethod(String value);

/**
 * Called by the SAML Credential Mapper to retrive the authentication
 * method attribute to be written to the SAML Assertion. See SAML 1.1
 * Assertions and Protocols, Section 7.1 for possible values returned.
 *
 * @return the Authentication Method
 */

    public String getAuthenticationMethod();

Example Custom SAMLCredentialAttributeMapper Class

Example 9-5 shows an example implementation of the SAMLCredentialNameMapper and SAMLCredentialAttributeMapper interfaces.

While the SAMLCredentialNameMapper example implementation maps user and group information stored in the Subject, the SAMLCredentialAttributeMapper example implementation maps attribute information stored in the ContextHandler.

This example does not show how the attributes are placed in the ContextHandler.

Note that you could implement the SAMLCredentialAttributeMapper to map information stored in the Subject rather than the ContextHandler.

Embedded comments provide additional information and context.

Example 9-5 Listing of Example Custom SAMLCredentialAttributeMapper Class

import java.util.ArrayList;
import java.util.Collection;
import java.util.Set;
import javax.security.auth.Subject;
import weblogic.security.providers.saml.SAMLAttributeStatementInfo;
import weblogic.security.providers.saml.SAMLAttributeInfo;
import weblogic.security.providers.saml.SAMLCredentialNameMapper;
import weblogic.security.providers.saml.SAMLCredentialAttributeMapper;
import weblogic.security.providers.saml.SAMLNameMapperInfo;
import weblogic.security.service.ContextHandler;
import weblogic.security.service.ContextElement;
import weblogic.security.spi.WLSGroup;
import weblogic.security.spi.WLSUser;

/**
 * @exclude
 *
 * The <code>CustomSAMLAttributeMapperImpl</code> class implements
 * name and attribute mapping for the SAML Credential Mapper.
 *
  * @author Copyright (c) 2004 by BEA Systems, Inc. All Rights Reserved.
  */

public class CustomSAMLAttributeMapperImpl implements
SAMLCredentialNameMapper,SAMLCredentialAttributeMapper
{

/**
 * Your logging code here
 */

        private final static String defaultAuthMethod =
     "urn:oasis:names:tc:SAML:1.0:am:unspecified";

        private final static String SAML_CONTEXT_ATTRIBUTE_NAME =
     "com.bea.contextelement.saml.context.attribute.name";

        private String nameQualifier = null;
        private String authMethod = defaultAuthMethod;

        public CustomSAMLAttributeMapperImpl()
        {
               // make constructor public
        }

/**
 * Set the name qualifier value
 */

        public synchronized void setNameQualifier(String nameQualifier) {
             this.nameQualifier = nameQualifier;
        }

/**
 * Map a <code>Subject</code> and return mapped user and group
 * info as a <code>SAMLNameMapperInfo</code> object.
 */

         public SAMLNameMapperInfo mapSubject(Subject subject, ContextHandler handler) {

               // Provider checks for null Subject...
               Set subjects = subject.getPrincipals(WLSUser.class);
               Set groups = subject.getPrincipals(WLSGroup.class);
               String userName = null;

               if (subjects == null || subjects.size() == 0) {
                   yourlogcode("mapSubject: No valid WLSUser principals
                   found in Subject, returning null");
                   return null;
               }

               if (groups == null || groups.size() == 0) {
                   yourlogcode("mapSubject: No valid WLSGroup pricipals
                   found in Subject, continuing");
               }

               if (subjects.size() != 1) {
                   yourlogcode("mapSubject: More than one WLSUser
                   principal found in Subject, taking first user only");
               }

               userName = ((WLSUser)subjects.iterator().next()).getName();
               if (userName == null || userName.equals("")) {
                   yourlogcode("mapSubject: Username string is null or
                   empty, returning null");
                   return null;
               }

               // Return mapping information...
                  yourlogcode("mapSubject: Mapped subject: qualifier: " +
                  nameQualifier + ", name: " + userName + ", groups: " + groups);
                  return new SAMLNameMapperInfo(nameQualifier, userName,
                  groups);
         }
/**
 * Map a <code>String</code> subject name and return mapped user and group
 * info as a <code>SAMLNameMapperInfo</code> object.
 */

         public SAMLNameMapperInfo mapName(String name, ContextHandler handler) {

                yourlogcode("mapName: Mapped name: qualifier: " +
                nameQualifier + ", name: " + name);
                return new SAMLNameMapperInfo(nameQualifier, name, null);
         }

/**
 * Returns the SAML AttributeName for group information.
 *
 * @return The AttributeName.
 */

         public String getGroupAttrName() {
                return SAMLNameMapperInfo.BEA_GROUP_ATTR_NAME;
         }

/**
 * Returns the SAML AttributeNamespace for group information.
 *
 * @return The AttributeNamespace.
 */

         public String getGroupAttrNamespace() {
                return SAMLNameMapperInfo.BEA_GROUP_ATTR_NAMESPACE;
         }

/**
 * set the auth method.
 * @param method String
 */

         public void setAuthenticationMethod(String method)
         {
                if (method != null)
                  authMethod = method;
         }

/**
 * get the auth method
 * @return method String
 */

         public String getAuthenticationMethod()
         {
                return authMethod;
         }

/**
 * maps a Subject/Context to a Collection of SAMLAttributeStatementInfo
 * instances.
 *
 * @return <code>Collection</code>
 */

         public Collection mapAttributes(Subject subject, ContextHandler handler)
         {
                yourlogcode("mapAttributes: Subject: "+subject.toString()+",
                   ContextHandler: "+handler.toString());

                Object element = handler.getValue(SAML_CONTEXT_ATTRIBUTE_NAME);

                yourlogcode("mapAttributes: got element from ContextHandler");
                yourlogcode("mapAttributes: element is a:"+element.getClass().getName());
                TestAttribute[] tas = (TestAttribute[])element;

/*
 * loop through all test attributes and write a SAMLAttributeStatementInfo
 * for each one.
 */

           ArrayList statementList = new ArrayList();
           for (int k = 0; k < tas.length; k++)
            {
             ArrayList al = null;
             String[] values = tas[k].getValues();
             if (values != null)
             {
               al = new ArrayList();
               for (int i = 0; i < values.length; i++)
               if (values[i] != null)
                  al.add(values[i]);
               else al.add("");
             }

               SAMLAttributeInfo ai = new SAMLAttributeInfo(tas[k].getName(),
                tas[k].getNamespace(), al);

               SAMLAttributeStatementInfo asi = new
                 SAMLAttributeStatementInfo();
               asi.addAttributeInfo(ai);
               statementList.add(asi);
            }
            return statementList;
         }
}

Make the Custom SAMLCredentialAttributeMapper Class Available in the Console

To have the SAML Credential Mapping Provider Version 2 use this SAMLCredentialAttributeMapper instance, you use the WebLogic Server Administration Console to set the existing NameMapperClassName attribute to the class name of this SAMLCredentialAttributeMapper instance.

That is, you use the Console control for the name mapper class name attribute to specify the class name of the SAMLCredentialAttributeMapper in the active security realm.

You can configure the user name mapper class name attribute in one of the following ways:

  • Once for the SAML Provider Version 2

  • Individually for one or more Relying Parties

  • Both for the SAML Credential Mapping Provider Version 2, and individually for Relying Parties.

To use a custom user name mapper with the WebLogic SAML Credential Mapping Provider Version 2:

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

  2. On the Security Realms page, select the name of the realm you are configuring (for example, TestRealm).

  3. Expand Providers > Credential Mapping and select the name of the SAML Credential Mapping Provider Version 2.

  4. Select the Provider Specific tab.

  5. In the Default Name Mapper Class Name field, enter the class name of your SAMLCredentialAttributeMapper implementation.

    The class name must be in the system classpath.

  6. Click Save.

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

When you configure a SAML Relying Party, you can optionally set a name mapper class specific to that Relying Party, which will override the default value you set here for the default name mapper class name.

For details about how to set a name mapper class name in the Administration Console, see "Configure a custom user name mapper" in the Oracle WebLogic Server Administration Console Help.

Configuring SAML SSO Attribute Support

This section describes SAML SSO attributes and how to use them with SAML 2.0 and SAML 1.1. The following topics are described:

What Are SAML SSO Attributes?

A SAML assertion is a piece of data produced by a SAML authority regarding either an act of authentication performed on a subject, attribute information about the subject, or authorization data applying to the subject with respect to a specified resource.

The SAML specification (see http://www.oasis-open.org) allows additional, unspecified information about a particular subject to be exchanged between SAML partners as attribute statements in an assertion. A SAML attribute assertion is therefore a particular type of SAML assertion that conveys site-determined information about attributes of a Subject.

In previous versions of WebLogic Server, the SAML 1.1 Credential Mapping provider supported attribute information, stored in the Subject, that specified the groups to which the identity contained in the assertion belonged

In this release, WebLogic Server enhances the SAML 1.1 and 2.0 Credential Mapping provider and Identity Assertion provider mechanisms to support the use of a custom attribute mapper that can obtain additional attributes (other than group information) to be written into SAML assertions, and to then map attributes from incoming SAML assertions.

To do this:

  • The SAML credential mapper (on the SAML Identity Provider site) determines how to package the attributes based on the existence of this custom attribute mapper.

  • The SAML identity asserter (on the SAML Service Provider site) determines how to get the attributes based on the configuration of the custom name mapper.

  • The Java Subject is used to make the attributes extracted from assertions available to applications. This requires that the SAML Authentication provider be configured and the virtual user be enabled on a SAML partner.

New API's for SAML Attributes

This release includes the following new SAML attribute API's for SAML 2.0:

For SAML 1.1 you can instead use the following existing SAML attribute API's:

Subsequent sections describe the use of these SAML attribute API's.

SAML 2.0 Basic Attribute Profile Required

SAML 1.1 does not prescribe the name format of the SAML attribute.

However, only the SAML 2.0 Basic Attribute Profile is supported for SAML 2.0. Only attributes with the urn:oasis:names:tc:SAML:2.0:attrname-format:basic name format in SAML2AttributeInfo are written into a SAML 2.0 assertion.

The urn:oasis:names:tc:SAML:2.0:attrname-format:basic name format is the default, so you need not set it.

If you do set the name format, you must specify urn:oasis:names:tc:SAML:2.0:attrname-format:basic in the SAML2.AttributeInfo.setAttributeNameFormat method, as follows:

SAML2AttributeInfo attrInfo = new SAML2AttributeInfo(
"AttributeWithSingleValue", "ValueOfAttributeWithSingleValue");
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo);

Passing Multiple Attributes to SAML Credential Mappers

When the configured attribute mapper is called, it returns Collection<SAML2AttributeStatementInfo>. You can specify multiple attribute statements, each containing multiple attributes, each possibly having multiple attribute values.

An example of doing this is as follows:

private Collection<SAML2AttributeStatementInfo> getAttributeStatementInfo(
Subject subject, ContextHandler handlers) {
Collection<SAML2AttributeInfo> attrs = new ArrayList<SAML2AttributeInfo>();
 
SAML2AttributeInfo attrInfo = new SAML2AttributeInfo(
"AttributeWithSingleValue", "ValueOfAttributeWithSingleValue");
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo);
 
ArrayList<String> v = new ArrayList<String>();
v.add("Value1OfAttributeWithMultipleValue");
v.add("Value2OfAttributeWithMultipleValue");
v.add("Value3OfAttributeWithMultipleValue");
SAML2AttributeInfo attrInfo1 = new SAML2AttributeInfo(
"AttributeWithMultipleValue", v);
attrInfo1.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
 
attrs.add(attrInfo1);
 
SAML2AttributeInfo attrInfo2 = new SAML2AttributeInfo(
"AttributeWithInvalidNameFormat",
"ValueOfAttributeWithInvalidNameFormatValue");
attrInfo2.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified");
attrs.add(attrInfo2);
 
SAML2AttributeInfo attrInfo3 = new SAML2AttributeInfo(
"AttributeWithNullValue", "null");
attrInfo3.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo3);
:
:
Collection<SAML2AttributeStatementInfo> attrStatements = new ArrayList<SAML2AttributeStatementInfo>();
attrStatements.add(new SAML2AttributeStatementInfo(attrs));
attrStatements.add(new SAML2AttributeStatementInfo(attrs1));
return attrStatements;
}

How to Implement SAML Attributes

This section walks through the process you follow to implement SAML attributes.

Note:

This section uses the SAML 2.0 interface names for the purpose of example. SAML 1.1 usage is similar except for different interface names for the mapper- and partner-related classes, as well as the attribute and method names used for the mapper configuration.

From the SAML credential mapping (Identity Provider) site:

  1. Instantiate the SAML2AttributeInfo and SAML2AttributeStatementInfo classes.

    Implement the SAML2CredentialAttributeMapper interface.

    Also implement the SAML2CredentialNameMapper interface in the same implementation. (The SAML2CredentialAttributeMapper and SAML2CredentialNameMapper interfaces must both be in the same implementation.)

    By implementing the SAML2CredentialNameMapper interface, you can then use the WebLogic Server Administration Console to set the NameMapperClassName attribute to the class name of your SAML2CredentialAttributeMapper instance.

  2. Use the WebLogic Server Administration Console to configure your new custom attribute mapper on a SAML provider, or on each individual partner, using the NameMapperClassName attribute of the SAML Credential Mapping provider to identify it. See Make the Custom SAML Credential Attribute Mapper Class Available in the Console.

  3. The SAML Credential Mapping provider determines if the configured custom name mapper is an implementation of the attribute mapping interface and, if so, calls your custom attribute mapping interface to obtain attribute values to write to the generated SAML assertions.

  4. The SAML Credential Mapping provider does not validate the attribute names or values obtained from your custom attribute mapper.

    Any attribute with a non-null attribute name is written to the attribute statements in the SAML assertion. An attribute with a null or empty attribute name is ignored, and subsequent attributes are processed.

    If an attribute has multiple values, each value appears as an <AttributeValue> element of a single <Attribute> in SAML attribute statements.

    For SAML 1.1, attributes with a null value are written to the SAML assertion as an empty string ("").

    For SAML 2.0, null or empty attribute values are handled based on Assertions and the Protocols for the OASIS SAML V2.0 March 2005 (http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf).

    An attribute with a name format other than urn:oasis:names:tc:SAML:2.0:attrname-format:basic is skipped.

From the SAML Identity Assertion (Service Provider) site:

  1. Implement the SAML2IdentityAsserterAttributeMapper and SAML2IdentityAsserterNameMapper interfaces in the same implementation. (The SAML2IdentityAsserterAttributeMapper and SAML2IdentityAsserterNameMapper interfaces must both be in the same implementation.)

    By implementing the SAML2IdentityAsserterNameMapper interface, you can then use the WebLogic Server Administration Console to set the NameMapperClassName attribute to the class name of your SAML2IdentityAsserterAttributeMapper instance.

  2. Use the WebLogic Server Administration Console to configure the SAML Identity Assertion provider, as described in Make the Custom SAML Identity Asserter Class Available in the Console. Set the NameMapperClassName attribute to the class name of your custom SAML2IdentityAsserterAttributeMapper instance.

    The SAML Identity Assertion provider processes <AttributeStatement> elements of the incoming SAML assertions and constructs a collection of SAML attribute statements.

  3. The SAML Identity Assertion provider determines if the configured custom name mapper implements the SAML2IdentityAsserterAttributeMapper interface. If it does, the SAML Identity Assertion provider calls the mapAttributeInfo method to obtain the SAML assertion's attributes.

    Your mapAttributeInfo method takes a Collection of SAMLAttributeStatementInfo instances that represent the attributes of attribute statements in a SAML Assertion, and maps the desired attributes in any application specific way.

  4. The SAML IdentityAssertion provider makes the attributes from a SAML assertion available to consumers via the Java Subject. This requires that the SAML Authentication provider be configured and the virtual user be enabled on a SAML partner.

    The attributes returned by the mapper are stored as subject principals or private credentials, depending on the class type of the mapped attributes. Specifically, if the mapper returns a collection of Principal objects, the mapped attributes are stored into the subject principal set. Otherwise, the subject private credential set is used to carry the mapped attributes.

    The consuming code needs to know the class type of the object that the mapper uses to represent attributes added to the subject, as shown in Example 9-7.

  5. The SAML Identity Assertion provider checks the ContextHandler and attribute mapper. (This walk through assumes the presence of the attribute mapper as stated in Step 4).

    Note:

    If both the ContextHandler and attribute mapper are present and configured, the attributes are instead made available to Web services via the ContextHandler, as described in Securing WebLogic Web Services for Oracle WebLogic Server .

Examples of the SAML 2.0 Attribute Interfaces

This section provides examples of implementing the SAML 2.0 attribute interfaces that allow writing additional attributes into SAML assertions.

Example Custom SAML 2.0 Credential Attribute Mapper

Example 9-6 shows an example of a single class that implements both the SAML2CredentialNameMapper interface and the SAML2CredentialAttributeMapper interface.

Example 9-6 SAML 2.0 Credential Attribute Mapper

public class CustomSAML2CredentialAttributeMapperImpl implements
SAML2CredentialNameMapper, SAML2CredentialAttributeMapper {
private String nameQualifier = null;
 
public Collection<SAML2AttributeStatementInfo> mapAttributes(
Subject subject, ContextHandler handler) {
return getAttributeStatementInfo(subject, handler);
}
       /**
         * same as SAML2NameMapperImpl
         */
        public SAML2NameMapperInfo mapName(String name, ContextHandler handler) {
                System.out
                               .println("CustomSAML2CredentialAttributeMapperImpl:mapName: Mapped name: qualifier: "
                                        + nameQualifier + ", name: " + name);
                return new SAML2NameMapperInfo(nameQualifier, name, null);
        }
 
        /**
         * same as SAML2NameMapperImpl
         */
        public synchronized void setNameQualifier(String nameQualifier) {
                this.nameQualifier = nameQualifier;
        }
 
        /**
         * same as SAML2NameMapperImpl
         */
         public SAML2NameMapperInfo mapSubject(Subject subject,
                        ContextHandler handler) {
 
                // Provider checks for null Subject...
                Set subjects = subject.getPrincipals(WLSUser.class);
                Set groups = subject.getPrincipals(WLSGroup.class);
                String userName = null;
                Set<String> groupStrings = new java.util.HashSet();
 
                if (subjects == null || subjects.size() == 0) {
                        System.out
                                        .println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: No valid WLSUser pricipals found in Subject, returning null");
                        return null;
                }
 
                if (groups == null || groups.size() == 0) {
                        System.out
                                        .println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: No valid WLSGroup pricipals found in Subject, continuing");
                }
                 else{
                 java.util.Iterator<WLSGroup> it = groups.iterator();
                 while(it.hasNext()){
                 WLSGroup wg = it.next();
                 groupStrings.add(wg.getName());
                 }
                 }

                if (subjects.size() != 1) {
                        System.out
                                        .println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: More than one WLSUser principal found in Subject, taking first user only");
                }
 
                userName = ((WLSUser) subjects.iterator().next()).getName();
                if (userName == null || userName.equals("")) {
                        System.out
                                        .println("CustomSAML2CredentialAttributeMapperImpl:mapSubject: Username string is null or empty, returning null");
                        return null;
                }
 
                // Return mapping information...
                System.out
                                TRACE.info("CustomSAML2CredentialAttributeMapperImpl:mapSubject: Mapped subject: qualifier: "
                                                + nameQualifier
                                                + ", name: "
                                                + userName
                                                + ", groups: "
                                                + groups);

  SAML2NameMapperInfo saml2NameMapperInfo = new
  SAML2NameMapperInfo(nameQualifier, userName, groupStrings);
   //SAML2NameMapperInfo saml2NameMapperInfo = new
  SAML2NameMapperInfo(nameQualifier, userName, groups);

                return new SAML2NameMapperInfo(nameQualifier, userName, groups);
        }

private Collection<SAML2AttributeStatementInfo> getAttributeStatementInfo(
Subject subject, ContextHandler handlers) {
Collection<SAML2AttributeInfo> attrs = new ArrayList<SAML2AttributeInfo>();
 
SAML2AttributeInfo attrInfo = new SAML2AttributeInfo(
"AttributeWithSingleValue", "ValueOfAttributeWithSingleValue");
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
attrs.add(attrInfo);
 
ArrayList<String> v = new ArrayList<String>();
v.add("Value1OfAttributeWithMultipleValue");
v.add("Value2OfAttributeWithMultipleValue");
v.add("Value3OfAttributeWithMultipleValue");
SAML2AttributeInfo attrInfo1 = new SAML2AttributeInfo(
"AttributeWithMultipleValue", v);
attrInfo.setAttributeNameFormat("urn:oasis:names:tc:SAML:2.0:attrname-format:basic");
 
attrs.add(attrInfo1);
: 
:
Collection<SAML2AttributeStatementInfo> attrStatements = new ArrayList<SAML2AttributeStatementInfo>();
attrStatements.add(new SAML2AttributeStatementInfo(attrs));
attrStatements.add(new SAML2AttributeStatementInfo(attrs1));
return attrStatements;
}
}

Use the WebLogic Server Administration Console to configure the User Name Mapper class name to the fully-qualified class name of this mapper implementation, as described in Make the Custom SAML Credential Attribute Mapper Class Available in the Console.

The attributes encapsulated in the collection of SAML2AttributeStatementInfo objects returned by the custom mapper implementation are included in the generated assertions by the SAML 2.0 Credential Mapping provider.

Custom SAML 2.0 Identity Asserter Attribute Mapper

Example 9-7 shows an example implementation of SAML2IdentityAsserterNameMapper and SAML2IdentityAsserterAttributeMapper.

Example 9-7 Custom SAML 2.0 Identity Asserter Attribute Mapper

public class CustomSAML2IdentityAsserterAttributeMapperImpl implements
SAML2IdentityAsserterNameMapper, SAML2IdentityAsserterAttributeMapper {
/**
 * same as SAML2NameMapperImpl
 */
public String mapNameInfo(SAML2NameMapperInfo info, ContextHandler handler) {
// Get the user name ...
String userName = info.getName();
System.out
.println("CustomSAML2IdentityAsserterAttributeMapperImpl:mapNameInfo: returning name: "
+ userName);
return userName;
}
}
:
:
public Collection<Object> mapAttributeInfo0(
Collection<SAML2AttributeStatementInfo> attrStmtInfos,
ContextHandler contextHandler) {
if (attrStmtInfos == null || attrStmtInfos.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: attrStmtInfos has no elements");
return null;
}
 
Collection<Object> customAttrs = new ArrayList<Object>();
 
for (SAML2AttributeStatementInfo stmtInfo : attrStmtInfos) {
Collection<SAML2AttributeInfo> attrs = stmtInfo.getAttributeInfo();
if (attrs == null || attrs.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: no attribute in statement: "
+ stmtInfo.toString());
} else {
for (SAML2AttributeInfo attr : attrs) {
if (attr.getAttributeName().equals("AttributeWithSingleValue")){
    CustomPrincipal customAttr1 = new CustomPrincipal(attr
.getAttributeName(), attr.getAttributeNameFormat(),
attr.getAttributeValues());
    customAttrs.add(customAttr1);
}else{
String customAttr = new StringBuffer().append(
attr.getAttributeName()).append(",").append(
attr.getAttributeValues()).toString();
customAttrs.add(customAttr);
}
}
}
}
return customAttrs;
}
 
public Collection<Principal> mapAttributeInfo(
Collection<SAML2AttributeStatementInfo> attrStmtInfos,
ContextHandler contextHandler) {
if (attrStmtInfos == null || attrStmtInfos.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: attrStmtInfos has no elements");
return null;
}
 
Collection<Principal> pals = new ArrayList<Principal>();
 
for (SAML2AttributeStatementInfo stmtInfo : attrStmtInfos) {
Collection<SAML2AttributeInfo> attrs = stmtInfo.getAttributeInfo();
if (attrs == null || attrs.size() == 0) {
System.out
.println("CustomIAAttributeMapperImpl: no attribute in statement: "
+ stmtInfo.toString());
} else {
for (SAML2AttributeInfo attr : attrs) {
CustomPrincipal pal = new CustomPrincipal(attr
.getAttributeName(), attr.getAttributeNameFormat(),
attr.getAttributeValues());
pals.add(pal);
}
}
}
return pals;
}

The SAML 2.0 IdentityAssertion provider makes the attributes from a SAML assertion available to consumers via the subject.

Use the WebLogic Server Administration Console to configure the User Name Mapper class name to the fully-qualified class name of this mapper implementation, as described in Make the Custom SAML Identity Asserter Class Available in the Console.

If you are allowing virtual users to log in via SAML, you need to create and configure an instance of the SAML Authentication provider. For information, see Configuring the SAML Authentication Provider.

If the virtual user is enabled and SAML Authenticator provider configured, the attributes returned by the custom attribute mapper are added into the subject.

The attributes returned by the mapper are stored as subject principals or private credentials, depending on the class type of the mapped attributes. Specifically, if the mapper returns a collection of Principal objects, the mapped attributes are stored into the subject principal set. Otherwise, the subject private credential set is used to carry the mapped attributes. The example code shows both approaches.

Your application code needs to know the class type of the object that the mapper uses to represent attributes added to the subject. Applications can retrieve the SAML attributes from the subject private credential or principal set, given the class type that the customer attribute mapper uses to represent the attributes.

Examples of the SAML 1.1 Attribute Interfaces

This section provides examples of implementing the SAML 1.1 attribute interfaces that allow writing additional attributes into SAML assertions.

Example Custom SAML 1.1 Credential Attribute Mapper

Example 9-8 shows an example of a single class that implements both the SAMLCredentialNameMapper interface and the SAMLCredentialAttributeMapper interface.

Example 9-8 SAML 1.1 Credential Attribute Mapper

public class CustomCredentialAttributeMapperImpl implements
    SAMLCredentialNameMapper, SAMLCredentialAttributeMapper {
  private String nameQualifier = null;
 
  public Collection<SAMLAttributeStatementInfo> mapAttributes(Subject subject,
      ContextHandler handler) {
    return AttributeStatementInfoGenerator.getInfos(subject, handler);
  }
…
public SAMLNameMapperInfo mapSubject(Subject subject, ContextHandler handler) {
 
    // Provider checks for null Subject...
    Set subjects = subject.getPrincipals(WLSUser.class);
    Set groups = subject.getPrincipals(WLSGroup.class);
    String userName = null;
:
 userName = ((WLSUser) subjects.iterator().next()).getName();
    if (userName == null || userName.equals("")) {
      System.out
          .println("CustomCredentialAttributeMapperImpl:mapSubject: Username string is null or empty, returning null");
      return null;
    }
:
    // Return mapping information...
    System.out
        .println("CustomCredentialAttributeMapperImpl:mapSubject: Mapped subject: qualifier: "
            + nameQualifier + ", name: " + userName + ", groups: " + groups);
    return new SAMLNameMapperInfo(nameQualifier, userName, groups);
  }
:
:
class AttributeStatementInfoGenerator {
  static final String SAML_ATTR_NAME_SAPCE = "urn:bea:security:saml:attributes";
 
  static Collection<SAMLAttributeStatementInfo> getInfos(Subject subject,
      ContextHandler handlers) {
    SAMLAttributeInfo info1 = new SAMLAttributeInfo("AttributeWithSingleValue",
        SAML_ATTR_NAME_SAPCE, "ValueOfAttributeWithSingleValue");
 
    ArrayList<String> v2 = new ArrayList<String>();
    v2.add("Value1OfAttributeWithMultipleValue");
    v2.add("Value2OfAttributeWithMultipleValue");
    SAMLAttributeInfo info2 = new SAMLAttributeInfo("AttributeWithMultipleValue",
        SAML_ATTR_NAME_SAPCE, v2);
 
    SAMLAttributeStatementInfo stmt1 = new SAMLAttributeStatementInfo();
    stmt1.addAttributeInfo(info1);
    stmt1.addAttributeInfo(info2);
 
    ArrayList<SAMLAttributeStatementInfo> result = new ArrayList<SAMLAttributeStatementInfo>();
    result.add(stmt1);
:
:
    return result;
  }

Use the WebLogic Server Administration Console to configure the User Name Mapper class name to the fully-qualified class name of this mapper implementation, as described in Make the Custom SAML Credential Attribute Mapper Class Available in the Console.

The attributes encapsulated in the collection of SAMLAttributeStatementInfo objects returned by the custom mapper implementation are included in the generated assertions by the SAML 1.1 Credential Mapping provider.

Custom SAML 1.1 Identity Asserter Attribute Mapper

Example 9-9 shows an example implementation of SAMLIdentityAssertionNameMapper and SAMLIdentityAssertionAttributeMapper.

Example 9-9 Custom SAML 1.1 Identity Asserter Attribute Mapper

public class CustomIdentityAssertionAttributeMapperImpl implements
    SAMLIdentityAssertionNameMapper, SAMLIdentityAssertionAttributeMapper {

  public String mapNameInfo(SAMLNameMapperInfo info, ContextHandler handler) {
    // Get the user name ...
    String userName = info.getName();
    System.out
        .println("CustomIdentityAssertionAttributeMapperImpl:mapNameInfo: returning name: "
            + userName);
    return userName;
  }

:
public void mapAttributeInfo(
      Collection<SAMLAttributeStatementInfo> attrStmtInfos,
      ContextHandler contextHandler) {
    if (attrStmtInfos == null || attrStmtInfos.size() == 0) {
      System.out
          .println("CustomIAAttributeMapperImpl: attrStmtInfos has no elements");
      return;
    }
:
   Object obj = contextHandler  .getValue(ContextElementDictionary.SAML_ATTRIBUTE_PRINCIPALS);
    if (obj == null || !(obj instanceof Collection)) {
      System.out.println("CustomIAAttributeMapperImpl: can't get "
          + ContextElementDictionary.SAML_ATTRIBUTE_PRINCIPALS
          + " from context handler");
      return;
    } 
:
    Collection<Principal> pals = (Collection<Principal>) obj;
 
    for (SAMLAttributeStatementInfo stmtInfo : attrStmtInfos) {
      Collection<SAMLAttributeInfo> attrs = stmtInfo.getAttributeInfo();
      if (attrs == null || attrs.size() == 0) {
        System.out
            .println("CustomIAAttributeMapperImpl: no attribute in statement: "
                + stmtInfo.toString());
      } else {
        for (SAMLAttributeInfo attr : attrs) {
          CustomPrincipal pal = new CustomPrincipal(attr.getAttributeName(),
              attr.getAttributeNamespace(), attr.getAttributeValues());
          pals.add(pal);
        }
      }
    }
  }

The SAML 1.1 IdentityAssertion provider makes the attributes from a SAML assertion available to consumers via the subject.

Use the WebLogic Server Administration Console to configure the User Name Mapper class name to the fully-qualified class name of this mapper implementation, as described in Make the Custom SAML Identity Asserter Class Available in the Console.

If you are allowing virtual users to log in via SAML, you need to create and configure an instance of the SAML Authentication provider. For information, see Configuring the SAML Authentication Provider.

If the virtual user is enabled and SAML Authenticator provider configured, the attributes returned by the custom attribute mapper are added into the subject.

The attributes returned by the mapper are stored as subject principals or private credentials, depending on the class type of the mapped attributes. Specifically, if the mapper returns a collection of Principal objects, the mapped attributes are stored into the subject principal set. Otherwise, the subject private credential set is used to carry the mapped attributes.

Your application code needs to know the class type of the object that the mapper uses to represent attributes added to the subject. Applications can retrieve the SAML attributes from the subject private credential or principal set, given the class type that the customer attribute mapper uses to represent the attributes.

Make the Custom SAML Credential Attribute Mapper Class Available in the Console

To have the SAML Credential Mapping provider use your SAML2CredentialAttributeMapper (SAML 2.0) or SAMLCredentialAttributeMapper (SAML 1.1) instance, you use the WebLogic Server Administration Console to set the existing NameMapperClassName attribute to the class name of this SAML2CredentialAttributeMapper or SAML2CredentialAttributeMapper instance.

That is, you use the Console control for the name mapper class name attribute to specify the class name of the SAML2CredentialAttributeMapper or SAMLCredentialAttributeMapper instance in the active security realm.

To use a custom user name mapper with the WebLogic SAML Credential Mapping provider

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

  2. On the Security Realms page, select the name of the realm you are configuring (for example, TestRealm).

  3. Expand Providers > Credential Mapping and select the name of the SAML 2.0 Credential Mapping provider, or the SAML Credential Mapping provider Version 2.

  4. Select the Provider Specific tab.

  5. In the Name Mapper Class Name (SAML 2.0) or Default Name Mapper Class Name (SAML 1.1) field, enter the class name of your SAML2CredentialAttributeMapper or SAMLCredentialAttributeMapper implementation.

    The class name must be in the system classpath.

  6. Click Save.

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

Make the Custom SAML Identity Asserter Class Available in the Console

To have the SAML Identity Assertion provider use this SAML2IdentityAsserterAttributeMapper (SAML 2.0) or SAMLIdentityAssertionAttributeMapper (SAML 1.1) instance, you use the WebLogic Server Administration Console to set the existing NameMapperClassName attribute to the class name of this SAML2IdentityAsserterAttributeMapper or SAMLIdentityAssertionAttributeMapper instance.

That is, you use the Console control for the name mapper class name attribute to specify the class name of the SAML2IdentityAsserterAttributeMapper or SAMLIdentityAssertionAttributeMapper instance in the active security realm.

To use a custom user name mapper with the WebLogic SAML Identity Asserter provider:

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

  2. On the Security Realms page, select the name of the realm you are configuring (for example, TestRealm).

  3. Expand Providers > Authentication and select the name of the SAML 2.0 Identity Asserter, or the SAML Identity Asserter Version 2.

  4. Select the Provider Specific tab.

  5. In the Name Mapper Class Name (SAML 2.0) or Default Name Mapper Class Name (SAML 1.1) field, enter the class name of your SAML2IdentityAsserterAttributeMapper or SAMLIdentityAssertionAttributeMapper implementation.

    The class name must be in the system classpath.

  6. Click Save.

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

For details about how to set a name mapper class name in the Administration Console, see "Configure a custom user name mapper" in the Oracle WebLogic Server Administration Console Help.