Skip Headers

Oracle® Security Developer Tools Reference 10g Release 3 (10.1.3) B25372-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 9 Oracle SAML

This chapter provides information about using the Oracle Security Assertions Markup Language (SAML) Software Development Kit (SDK). Oracle SAML allows Java developers to develop cross-domain single sign-on and federated access control solutions that conform to the SAML 1.0/1.1 specifications.

This chapter contains the following topics:

- Oracle SAML Features and Benefits

- Setting Up Your Oracle SAML Environment

- Core Classes and Interfaces

- The Oracle SAML Java API Reference

## 9.1 Oracle SAML Features and Benefits

The Oracle SAML SDK provides a Java API with supporting tools, documentation, and sample programs to assist developers of SAML-compliant Java security services. Oracle SAML can be integrated into existing Java solutions, including applets, applications, EJBs, servlets, and JSPs.

Oracle SAML provides the following features:

- Support for the SAML 1.0/1.1 specifications

- Support for SAML-based single sign-on and federated identity profiles, such as those specified by the Liberty Alliance Project

See Also: For more information and links to these specifications and related documents, see Appendix A, "References".

### 9.1.1 Oracle SAML Packages

The Oracle SAML Java API contains the following packages for creating SAML-compliant Java applications:

`oracle.security.xmlsec.saml`

This package contains classes that support SAML assertions.

`oracle.security.xmlsec.samlp`

This package contains classes that support the SAML request and response protocol (SAMLP).

## 9.2 Setting Up Your Oracle SAML Environment

The Oracle Security Developer Tools are installed with Oracle Application Server in `ORACLE_HOME`.

This section explains how to set up your environment for Oracle SAML. It contains these topics:

- System Requirements for Oracle SAML

- Setting the CLASSPATH Environment Variable

### 9.2.1 System Requirements for Oracle SAML

In order to use Oracle SAML, your system must have the Java Development Kit (JDK) version 1.2.2 or higher.

### 9.2.2 Setting the CLASSPATH Environment Variable

Your `CLASSPATH` environment variable must contain the full path and file names to all of the required jar and class files. Make sure the following items are included in your `CLASSPATH`:

- `osdt_core.jar`

- `osdt_cert.jar`

- `osdt_xmlsec.jar`

- `osdt_saml.jar`

- The `jaxen.jar` file (Jaxen XPath engine, included with your Oracle XML Security distribution)

- The jar files for your chosen XML parser and XSLT processor (for example, `xalan.jar` and `xercesImpl.jar` if using Apache Xalan-Java)

#### 9.2.2.1 Setting the CLASSPATH on Windows

To set the `CLASSPATH` on Windows:

1. In your Windows Control Panel, select System.

2. In the System Properties dialog, select the Advanced tab.

3. Click Environment Variables.

4. In the User Variables section, click New to add a `CLASSPATH` environment variable for your user profile. If a `CLASSPATH` environment variable already exists, select it and click Edit.

5. Add the full path and file names for all of the required jar files to the `CLASSPATH`.

   For example, your `CLASSPATH` might look like this:

       %CLASSPATH%;C:\ORACLE_HOME\jlib\osdt_core.jar;
       C:\ORACLE_HOME\jlib\osdt_cert.jar;
       C:\ORACLE_HOME\jlib\osdt_xmlsec.jar;
       C:\ORACLE_HOME\jlib\osdt_saml.jar;
       C:\ORACLE_HOME\jlib\jaxen.jar;
       C:\xalan-j_2_6_0\bin\xalan.jar;C:\xalan-j_2_6_0\bin\xercesImpl.jar

6. Click OK.

#### 9.2.2.2 Setting the CLASSPATH on UNIX

On UNIX, set your `CLASSPATH` environment variable to include the full path and file name of all of the required jar and class files. For example:

    setenv CLASSPATH $CLASSPATH:$ORACLE_HOME/jlib/osdt_core.jar:\
    $ORACLE_HOME/jlib/osdt_cert.jar:\
    $ORACLE_HOME/jlib/osdt_xmlsec.jar:\
    $ORACLE_HOME/jlib/osdt_saml.jar:\
    $ORACLE_HOME/jlib/jaxen.jar:\
    /usr/lib/xalan-j_2_6_0/bin/xalan.jar:/usr/lib/xalan-j_2_6_0/bin/xercesImpl.jar

## 9.3 Core Classes and Interfaces

This section provides information and code samples for using the key classes and interfaces of Oracle SAML. The core classes are:

- The oracle.security.xmlsec.saml.SAMLInitializer Class

- The oracle.security.xmlsec.saml.Assertion Class

- The oracle.security.xmlsec.samlp.Request Class

- The oracle.security.xmlsec.samlp.Response Class

The supporting classes and interfaces are:

- The oracle.security.xmlsec.saml.SAMLURI Interface (interface)

- The oracle.security.xmlsec.saml.SAMLMessage Class

### 9.3.1 Core Classes

This section provides a brief overview of the core SAML and SAMLP classes with some brief code examples.

#### 9.3.1.1 The oracle.security.xmlsec.saml.SAMLInitializer Class

This class initializes the Oracle SAML toolkit. By default Oracle SAML is automatically initialized for SAML v1.0. You can also initialize Oracle SAML for a specific version of the SAML specification. When the `initialize` method is called for a specific version, previously initialized versions will remain initialized. Example 9-1 shows how to initialize the SAML toolkit for SAML v1.0 and SAML v1.1.

Example 9-1 Initializing the Oracle SAML Toolkit

    // initializes for SAML v1.1
    SAMLInitializer.initialize(1, 1);
    // initializes for SAML v1.0, done by default
    SAMLInitializer.initialize(1, 0);

#### 9.3.1.2 The oracle.security.xmlsec.saml.Assertion Class

This class represents the `Assertion` element of the SAML Assertion schema.

Example 9-2 shows how to create a new `Assertion` element and append it to an existing XML document.

Example 9-2 Creating an Assertion Element and Appending to an XML Document

    Document doc = Instance of org.w3c.dom.Document;
    Assertion assertion = new Assertion(doc);
    doc.getDocumentElement().appendChild(assertion);

Example 9-3 shows how to obtain `Assertion` elements from an XML document.

Example 9-3 Obtaining Assertion Elements From an XML Document

    Document doc = Instance of org.w3c.dom.Document;

    // Get a list of all Assertion elements in the document

    NodeList assrtList =
        doc.getElementsByTagNameNS(SAMLURI.ns_saml, "Assertion");
    if (assrtList.getLength() == 0)
        System.err.println("No Assertion elements found.");

    // Convert each org.w3c.dom.Node object to a
    // oracle.security.xmlsec.saml.Assertion object and process

    for (int s = 0, n = assrtList.getLength(); s < n; ++s)
    {
        Assertion assertion = new Assertion((Element)assrtList.item(s));
        // Process Assertion element
        ...
    }

#### 9.3.1.3 The oracle.security.xmlsec.samlp.Request Class

This class represents the `Request` element of the SAML Protocol schema.

Example 9-4 shows how to create a new `Request` element and append it to an existing XML document.

Example 9-4 Creating a Request Element and Appending to an XML Document

    Document doc = Instance of org.w3c.dom.Document;
    Request request = new Request(doc);
    doc.getDocumentElement().appendChild(request);

Example 9-5 shows how to obtain `Request` elements from an existing XML document.

Example 9-5 Obtaining Request Elements From an XML Document

    Document doc = Instance of org.w3c.dom.Document;

    // Get a list of all Request elements in the document

    NodeList reqList =
        doc.getElementsByTagNameNS(SAMLURI.ns_samlp, "Request");
    if (reqList.getLength() == 0)
        System.err.println("No Request elements found.");

    // Convert each org.w3c.dom.Node object to a
    // oracle.security.xmlsec.samlp.Request object and process

    for (int s = 0, n = reqList.getLength(); s < n; ++s)
    {
        Request request = new Request((Element)reqList.item(s));
        // Process Request element
        ...
    }

#### 9.3.1.4 The oracle.security.xmlsec.samlp.Response Class

This class represents the `Response` element of the SAML Protocol schema. See the `CreateAuthDecisionResponse.java` example program provided in the `examples` directory of your Oracle SAML distribution for a complete example of creating a SAMLP Response message.

Example 9-6 shows how to create a `Response` element and append it to an existing XML document.

Example 9-6 Creating a Response Element and Appending to an XML Document

    Document doc = Instance of org.w3c.dom.Document;
    Response response = new Response(doc);
    doc.getDocumentElement().appendChild(response);

Example 9-7 shows how to obtain Response elements from an existing XML document.

Example 9-7 Obtaining Response Elements From an XML Document

    Document doc = Instance of org.w3c.dom.Document;

    // Get a list of all Response elements in the document

    NodeList respList =
        doc.getElementsByTagNameNS(SAMLURI.ns_samlp, "Response");
    if (respList.getLength() == 0)
        System.err.println("No Response elements found.");

    // Convert each org.w3c.dom.Node object to a
    // oracle.security.xmlsec.samlp.Response object and process

    for (int s = 0, n = respList.getLength(); s < n; ++s)
    {
        Response response = new Response((Element)respList.item(s));
        // Process Response element
        ...
    }

### 9.3.2 Supporting Classes and Interfaces

This section provides an overview of the supporting classes and interfaces of Oracle SAML.

#### 9.3.2.1 The oracle.security.xmlsec.saml.SAMLURI Interface

This interface defines URI string constants for algorithms, namespaces, and objects. The following naming conventions are used:

- Action Namespace URIs defined in the SAML 1.0 specifications begin with `action_` .

- Authentication Method Namespace URIs defined in the SAML 1.0 specifications begin with `authentication_method_` .

- Confirmation Method Namespace URIs defined in the SAML 1.0 specifications begin with `confirmation_method_` .

- Namespace URIs begin with `ns_` .

#### 9.3.2.2 The oracle.security.xmlsec.saml.SAMLMessage Class

This is the base class for all the SAML and SAML extension messages that may be signed and contain an XML-DSIG (digital signature) structure.

## 9.4 The Oracle SAML Java API Reference

The Oracle SAML Java API reference (Javadoc) is available at:

Oracle Security Developer Tools SAML Java API Reference