SAML APIs

8 SAML APIs

Oracle WebLogic Server supports the use of Security Assertion Markup Language (SAML) APIs. SAML is an XML-based protocol 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 2.0. The WebLogic Server implementation:

Supports the HTTP POST, HTTP Artifact, and HTTP Redirect bindings for the Web SSO profile for SAML 2.0.
Supports SAML authentication and attribute statements (does not support SAML authorization statements)

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 2.0 Credential Mapping Provider for SAML 2.0 in Administering Security for Oracle WebLogic Server.

For access to the SAML specifications, go to http://www.oasis-open.org. Also see the 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 chapter includes the following sections:

SAML API Description

Learn about the WebLogic SAML APIs that you can use to implement SAML in WebLogic Server.

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

Table 8-1 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.

Configuring SAML SSO Attribute Support

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. You can configure SAML SSO attributes to be used with SAML 2.0.

This section describes the following topics:

What Are SAML SSO Attributes?

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.

The SAML 2.0 Credential Mapping provider and Identity Assertion provider mechanisms 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.

APIs for SAML Attributes

Use the following SAML 2.0 attribute APIs:

Subsequent sections describe the use of these SAML attribute APIs.

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.

From the SAML credential mapping (Identity Provider) site:

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 WebLogic Remote Console to set the NameMapperClassName attribute to the class name of your SAML2CredentialAttributeMapper instance.
Use WebLogic Remote 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.
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.
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 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:

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 WebLogic Remote Console to set the NameMapperClassName attribute to the class name of your SAML2IdentityAsserterAttributeMapper instance.
Use WebLogic Remote 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.
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.
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 8-2.
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 8-1 shows an example of a single class that implements both the SAML2CredentialNameMapper interface and the SAML2CredentialAttributeMapper interface.

Example 8-1 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 WebLogic Remote 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 8-2 shows an example implementation of SAML2IdentityAsserterNameMapper and SAML2IdentityAsserterAttributeMapper.

Example 8-2 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 WebLogic Remote 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. 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.

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) instance, use WebLogic Remote Console to set the existing NameMapperClassName attribute to the class name of this SAML2CredentialAttributeMapper instance.

That is, you use the WebLogic Remote Console field for the name mapper class name attribute to specify the class name of the SAML2CredentialAttributeMapper instance in the active security realm.

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

In WebLogic Remote Console, go to the Edit Tree, then Security, then Realms, then myRealm, then Credential Mappers, select the name of a SAML Credential Mapping Version 2 provider.
On the SAML Credential Mapper V2 Parameters tab, in the Name Mapper Class Name field, enter the class name of your SAML2CredentialAttributeMapper implementation. The class name must be in the system classpath.
Click Save.

Make the Custom SAML Identity Asserter Class Available in the Console

To have the SAML Identity Assertion provider use this SAML2IdentityAsserterAttributeMapper (SAML 2.0) instance, you can use WebLogic Remote Console to set the existing NameMapperClassName attribute to the class name of this SAML2IdentityAsserterAttributeMapper instance.

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

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

In WebLogic Remote Console, go to the Edit Tree, then Security, then Realms, then myRealm, then Authentication Providers, select the name of a SAML Identity Asserter Version 2 provider.
On the SAML Identity Asserter V2 Parameters tab, in the Name Mapper Class Name field, enter the class name of your SAML2IdentityAsserterAttributeMapper implementation. The class name must be in the system classpath.
Click Save.