test

Sun OpenSSO Enterprise 8.0 Developer's Guide

SAML v1.x

OpenSSO Enterprise contains SAML v1.x API collected in several Java packages. Administrators can use these packages to integrate the SAML v1.x functionality using XML messages into their applications and services. The API support all types of assertions and operate with OpenSSO Enterprise authorities to process external SAML v1.x requests and generate SAML v1.x responses. The packages include the following:

For more detailed information, including methods and their syntax and parameters, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

com.sun.identity.saml Package

This package contains the following classes.

AssertionManager Class

The AssertionManager class provides interfaces and methods to create and get assertions, authentication assertions, and assertion artifacts. This class is the connection between the SAML specification and OpenSSO Enterprise. Some of the methods include the following:

SAMLClient Class

The SAMLClient class provides methods to execute either the Web Browser Artifact Profile or the Web Browser POST Profile from within an application as opposed to a web browser. Its methods include the following:

com.sun.identity.saml.assertion Package

This package contains the classes needed to create, manage, and integrate an XML assertion into an application. The following code example illustrates how to use the Attribute class and getAttributeValue method to retrieve the value of an attribute. From an assertion, call the getStatement() method to retrieve a set of statements. If a statement is an attribute statement, call the getAttribute() method to get a list of attributes. From there, call getAttributeValue() to retrieve the attribute value.

Example 8–1 Sample Code to Obtain an Attribute Value


// get statement in the assertion
Set set = assertion.getStatement();
//assume there is one AttributeStatement
//should check null& instanceof
AttributeStatement statement = (AttributeStatement) set.iterator().next();
List attributes = statement.getAttribute();
// assume there is at least one Attribute
Attribute attribute = (Attribute) attributes.get(0);
List values = attribute.getAttributeValue();

com.sun.identity.saml.common Package

This package defines classes common to all SAML elements, including site ID, issuer name, and server host. The package also contains all SAML-related exceptions.

com.sun.identity.saml.plugins Package

The SAML v1.x framework provides service provider interfaces (SPIs), three of which have default implementations. The default implementations of these SPIs can be altered, or brand new ones written, based on the specifications of a particular customized service. The implementations are then used to integrate SAML into the custom service. Currently, the package includes the following.

ActionMapper Interface

ActionMapper is an interface used to obtain single sign-on information and to map partner actions to OpenSSO Enterprise authorization decisions. A default action mapper is provided if no other implementation is defined.

AttributeMapper Interface

AttributeMapper is an interface used in conjunction with an AttributeQuery class. When a site receives an attribute query, this mapper obtains the SSOToken or an assertion (containing an authentication statement) from the query. The retrieved information is used to convert the attributes in the query to the corresponding OpenSSO Enterprise attributes. A default attribute mapper is provided if no other implementation is defined.

NameIdentifierMapper Interface

NameIdentifierMapper is an interface that can be implemented by a site to map a user account to a name identifier in the subject of a SAML assertion. The implementation class is specified when configuring the site's Trusted Partners.

PartnerAccountMapper Interface

Caution – Caution –

The AccountMapper interface has been deprecated. Use the PartnerAccountMapper interface.

The PartnerAccountMapper interface needs to be implemented by each partner site. The implemented class maps the partner site's user accounts to user accounts configured in OpenSSO Enterprise for purposes of single sign-on. For example, if single sign-on is configured from site A to site B, a site-specific account mapper can be developed and defined in the Trusted Partners sub-attribute of site B's Trusted Partners profile. When site B processes the assertion received, it locates the corresponding account mapper by retrieving the source ID of the originating site. The PartnerAccountMapper takes the whole assertion as a parameter, enabling the partner to define user account mapping based on attributes inside the assertion. The default implementation is com.sun.identity.saml.plugin.DefaultAccountMapper. If a site-specific account mapper is not configured, this default mapper is used.

Note –

Turning on the Debug Service in the OpenSSO Enterprise configuration data store logs additional information about the account mapper, for example, the user name and organization to which the mapper has been mapped.

PartnerSiteAttributeMapper Interface

Caution – Caution –

The SiteAttributeMapper interface has been deprecated. Use the PartnerSiteAttributeMapper interface.

The PartnerSiteAttributeMapper interface needs to be implemented by each partner site. The implemented class defines a list of attributes to be returned as elements of the AttributeStatements in an authentication assertion. By default, when OpenSSO Enterprise creates an assertion and no mapper is specified, the authentication assertion only contains authentication statements. If a partner site wants to include attribute statements, it needs to implement this mapper which would be used to obtain attributes, create the attribute statement, and insert the statement inside the assertion. To set up a PartnerSiteAttributeMapper do the following:

  1. Implement a customized class based on the PartnerSiteAttributeMapper interface.

    This class will include user attributes in the SAML authentication assertion.

  2. Log in to the OpenSSO Enterprise console to configure the class in the Site Attribute Mapper attribute of the Trusted Partner configuration.

com.sun.identity.saml.protocol Package

This package contains classes that parse the request and response XML messages used to exchange assertions and their authentication, attribute, or authorization information.

AuthenticationQuery Class

The AuthenticationQuery class represents a query for an authentication assertion. When an identity attempts to access a trusted partner web site, a SAML 1.x request with an AuthenticationQuery inside is directed to the authority site.

The Subject of the AuthenticationQuery must contain a SubjectConfirmation element. In this element, ConfirmationMethod needs to be set to urn:com:sun:identity, and SubjectConfirmationData needs to be set to the SSOToken ID of the Subject. If the Subject contains a NameIdentifier, the value of the NameIdentifier should be the same as the one in the SSOToken.

AttributeQuery Class

The AttributeQuery class represents a query for an identity’s attributes. When an identity attempts to access a trusted partner web site, a SAML 1.x request with an AttributeQuery is directed to the authority site.

You can develop an attribute mapper to obtain an SSOToken, or an assertion that contains an AuthenticationStatement from the query. If no attribute mapper for the querying site is defined, the DefaultAttributeMapper will be used. To use the DefaultAttributeMapper, the query should have either the SSOToken or an assertion that contains an AuthenticationStatement in the SubjectConfirmationData element. If an SSOToken is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If an assertion is used, the assertion should be issued by the OpenSSO Enterprise instance processing the query or a server that is trusted by the OpenSSO Enterprise instance processing the query.

Note –

In the DefaultAttributeMapper, a subject’s attributes can be queried using another subject’s SSOToken if the SSOToken has the privilege to retrieve the attributes.

For a query using the DefaultAttributeMapper, any matching attributes found will be returned. If no AttributeDesignator is specified in the AttributeQuery, all attributes from the services defined under the userServiceNameList in amSAML.properties will be returned. The value of the userServiceNameList property is user service names separated by a comma.

AuthorizationDecisionQuery Class

The AuthorizationDecisionQuery class represents a query about a principal’s authority to access protected resources. When an identity attempts to access a trusted partner web site, a SAML request with an AuthorizationDecisionQuery is directed to the authority site.

You can develop an ActionMapper to obtain the SSOToken ID and retrieve the authentication decisions for the actions defined in the query. If no ActionMapper for the querying site is defined, the DefaultActionMapper will be used. To use the DefaultActionMapper, the query should have the SSOToken ID in the SubjectConfirmationData element of the Subject. If the SSOToken ID is used, the ConfirmationMethod must be set to urn:com:sun:identity:. If a NameIdentifier is present, the information in the SSOToken must be the same as the information in the NameIdentifier.

Note –

When using web agents, the DefaultActionMapper handles actions in the namespace urn:oasis:names:tc:SAML:1.0:ghpp only. Web agents serve the policy decisions for this action namespace.

The authentication information can also be passed through the Evidence element in the query. Evidence can contain an AssertionIDReference, an assertion containing an AuthenticationStatement issued by the OpenSSO Enterprise instance processing the query, or an assertion issued by a server that is trusted by the OpenSSO Enterprise instance processing the query. The Subject in the AuthenticationStatement of the Evidence element should be the same as the one in the query.

Note –

Policy conditions can be passed through AttributeStatements of assertion(s) inside the Evidence of a query. If the value of an attribute contains a TEXT node only, the condition is set as attributeName=attributeValueString. Otherwise, the condition is set as attributename=attributeValueElement.

The following example illustrates one of many ways to form an authorization decision query that will return a decision.

Example 8–2 AuthorizationDecisionQuery Code Sample


        // testing getAssertion(authZQuery): no SC, with ni, with
        // evidence(AssertionIDRef, authN, for this ni):
            String nameQualifier = "dc=iplanet,dc=com";
            String pName = "uid=amadmin,ou=people,dc=iplanet,dc=com";
            NameIdentifier ni = new NameIdentifier(pName, nameQualifier);
            Subject subject = new Subject(ni);
            String actionNamespace = "urn:test";
            // policy should be added to this resource with these
            // actions for the subject
            Action action1 = new Action(actionNamespace, "GET");
            Action action2 = new Action(actionNamespace, "POST");
            List actions = new ArrayList();
            actions.add(action1);
            actions.add(action2);
            String resource = "http://www.sun.com:80";
            eviSet = new HashSet();
            // this assertion should contain authentication assertion for
            // this subject and should be created by a trusted server
            eviSet.add(eviAssertionIDRef3);
            evidence = new Evidence(eviSet);
            authzQuery = new AuthorizationDecisionQuery(eviSubject1, actions,
                                evidence, resource);
            try {
                assertion = am.getAssertion(authzQuery, destID);
            } catch (SAMLException e) {
                out.println("--failed. Exception:" + e);
            }