What's OpenSAML

OpenSAML is a dependency library that facilitates the use of SAML messages. Its main functions include:

1. Create SAML messages;
2. Parsing SAML objects and exporting them to XML format;
3. Signature and encryption;
4. Encoding and transmitting SAML messages.

At present, OpenSAML library provides Java and C++ implementations. It should be noted that although OpenSAML is mostly used in SSO (single sign-on) development, the library itself does not provide any identity and authorization functions, but only implements related operations for SAML messages.

SAML

SAML is an XML framework for exchanging security information, which defines the protocol and format of communication required according to security specifications.

SAML is a centralized authentication mechanism, which defines two entities communicating with each other:

• Service Provider(SP): An entity that provides a formal business service to a user usually needs to authenticate the identity of a user.
• Identity Provider(IDP): Provides user identification to ensure that the user is his declared identity;

Important uses of SAML:

• Single Sign-on (SSO);
• Federated Identity;
• SAML is used in other architectures, such as WS-Security.

For more information on SAML, see SAML 2.0 Introduction Guide

SAML related definitions

Assertions are information.

Assertions are used in SAML to describe the authenticated objects, including when and how a user is authenticated. They can also include extended information, such as the user's Email address and phone number.

Here is an example of an assertion:

2. Protocol is communication

The agreement specifies how to perform different actions. These actions are refined into columns of Request and Response objects, and these requests and corresponding objects contain information that the behavior needs in particular. For example, the AuthnRequest Protocol specifies how an SP requests to obtain an authenticated user.

<saml2p:AuthnRequest
    AssertionConsumerServiceURL=http://localhost:8080/webprofile-refproject/sp/consumer
    Destination="http://localhost:8080/webprofile-refproject/idp/singleSignOnService"
    ID="_52c9839568ff2e5a10456dfefaad0555"
    IssueInstant="2014-05-13T17:34:37.810Z"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTPArtifact"
    Version="2.0">
    <saml2:Issuer>
        TestSP
    </saml2:Issuer>
    <saml2p:NameID
        PolicyAllowCreate="true"
        Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
    <saml2p:RequestedAuthnContext Comparison="minimum">
        <saml2:AuthnContextClassRef>
            urn:oasis:names:tc:SAML:2.0:ac:classes:Password
        </saml2:AuthnContextClassRef>
    </saml2p:RequestedAuthnContext>
</saml2p:AuthnRequest>

3. Binding is transmission

Binding defines how SAML information is transmitted using communication protocols. For example, HTTP redirection bindings, which declare that SAML information will be transmitted through HTTP redirection messages, and SAML SOAP bindings, which declare that SAML messages will be transmitted through SOAP.

Profiles are synthesis

Configuration defines how to organize the above information and describes assertions, protocols and bindings at a higher level to solve a specific situation. For example, the SSO configuration of a Web browser describes how a user can use the browser to be authenticated.

MetaData

The metadata of SAML is configuration data, which contains information about all parties in SAML communication, such as the ID of the other party, the IP address of Web Service, the type of binding supported, and the practical key in communication, etc.

Protocol flow of SAML through Web browser

SSO is implemented by HTTP protocol binding:

1. Users try to gain privileges

The process starts with a non-authenticated user who tries to gain access from a protected SP. A filter in some way is set on the access path to detect whether the user is authorized (the servlet class in J2ee is a good example). This part is not really part of the SAML protocol, but it decides whether to be authorized or not.

2. Users are redirected to IDP

When the filter set on the access path finds that the user is not authenticated, it will automatically orient the user from IDP to verify the user's identity.

3. Users are authenticated

In this step, the user is authenticated. Note that there is no SP interaction involved here. In a secure way, IDP has full responsibility for authenticating users.

4. Authenticated users are directed back to SP

When the user is authenticated successfully, the user will be directed back to SP with SAML artifact. Such SAML products can also be said to be the identification of authentication information, because sensitive information in authentication information can not be transmitted directly through browsers, so here is just the sending of identification.

5. Require authentication information

When SAML products are received, SP sends them back to IDP, which finds authentication information based on SAML products and sends them back to SP via SAML Artifact Response.

The SAML Artifact Response mentioned above contains the SAML assertion, which is the evidence of authentication. The most important data in an assertion is when and how the user is authenticated.

OpenSAML Quick Start

@ (Unified Identity Authentication) [saml | Unified Identity Authentication | Third Party Login]
Having said so many theoretical processes, let's start with the composition and use of OpenSAML.

How to add OpenSAML Library

OpenSAML libraries are available on OpenSAML homepages, and Maven users can rely directly on the following links:
https://build.shibboleth.net/nexus/content/repositories/releases/org/opensaml/

OpenSAML3 is a multi-module library organized by Maven, each module has different functions. As project functions become more and more abundant, it is impossible for current users to refer to all their functions through a single dependency. Each module needs to add its own reference. The latest version of OpenSAML module list is as follows:

• opensaml-core
• opensaml-profile-api
• opensaml-profile-impl
• opensaml-soap-api
• opensaml-soap-impl
• opensaml-saml-api
• opensaml-saml-impl
• opensaml-xacml-api
• opensaml-xacml-impl
• opensaml-xacml-saml-api
• opensaml-xacml-saml-impl
• opensaml-messaging-api
• opensaml-messaging-impl
• opensaml-storage-api
• opensaml-storage-impl
• opensaml-security-api
• opensaml-security-impl
• opensaml-xmlsec-api
• opensaml-xmlsec-impl

Users can add their own modules according to their own projects. The information cited in Maven is as follows:

<dependencies>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-core</artifactId>
        <version>3.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-saml-api</artifactId>
        <version>3.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-saml-impl</artifactId>
        <version>3.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-messaging-api</artifactId>
        <version>3.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-messaging-impl</artifactId>
        <version>3.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-soap-api</artifactId>
        <version>3.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.opensaml</groupId>
        <artifactId>opensaml-soap-impl</artifactId>
        <version>3.2.0</version>
    </dependency>
</dependencies>
<repositories>
    <repository>
        <id>Shibboleth repo</id>
        <url>
        https://build.shibboleth.net/nexus/content/repositories/releases
        </url>
    </repository>
</repositories>

Guarantee the correctness of JCE implementation

OpenSAML uses JCE to provide cryptographic function modules. Because of some
The implementation of JCE does not cover all the functions required by OpenSAML, so it is recommended to use the JCE implementation of Bouncy Castle.

To help users confirm whether the JCE implementation is correct, the following functions can be used:

JavaCryptoValidationInitializer javaCryptoValidationInitializer = 
    new JavaCryptoValidationInitializer();
javaCryptoValidationInitializer.init();

This method should be invoked at OpenSAML initialization to ensure that the current environment meets the requirements.

The following method can be used to print all JCE provider s that are currently installed:

for (Provider jceProvider : Security.getProviders()) {
    logger.info(jceProvider.getInfo());
}

When using Maven to refer to OpenSAML, Bouncy Castle
provider will be automatically referenced. If you download OpenSAML source dependencies manually, Bouncy Castle is already included.
provider, but you need to add it manually to the class path.

Log Printing

OpenSAML uses SLF4J to manage log information. Although SLF4J itself does not have any ability to print logs, it relies on other logging implementations for log management. The OpenSAML team chose to use Logback to implement the logging function (other implementations are also possible).

In order to use LogBack, you need to add dependency packages:

• logback-core
• logback-classic
• apache commons logging

The download links are as follows:
http://logback.qos.ch/download.html,
https://commons.apache.org/proper/commons-logging/

Or add Maven dependencies directly:

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-core</artifactId>
    <version>1.0.13</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.0.13</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.0.13</version>
</dependency>
<dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.2</version>
</dependency>

OpenSAML initialization process

The initialization of OpenSAML depends on a number of columns of configuration files. OpenSAML already has a default configuration that meets most of the usage requirements and can be modified if necessary.

Configuration files must be loaded before OpenSAML is used. The methods needed to load the default configuration are as follows:

InitializationService.initialize();

After that, OpenSAML libraries can be used properly.

Create SAML objects

The creation of SAML objects uses factory mode and builder mode, involving chain configuration and type substitution.

The methods for creating SAML assertion objects are as follows:

XMLObjectBuilderFactory builderFactory =
    XMLObjectProviderRegistrySupport.getBuilderFactory();
Assertion assertion = (Assertion) builderFactory
    .getBuilder(Assertion.DEFAULT_ELEMENT_NAME)
    .buildObject(Assertion.DEFAULT_ELEMENT_NAME);

To avoid a lot of unnecessary code, it's a good idea to use generic tools. Different types of objects can be generated by:

public static <T> T buildSAMLObject(final Class<T> clazz) {
    XMLObjectBuilderFactory builderFactory =
        XMLObjectProviderRegistrySupport.getBuilderFactory();
    QName defaultElementName = (QName) clazz.getDeclaredField(
    "DEFAULT_ELEMENT_NAME").get(null);
    T object = (T) builderFactory.getBuilder(defaultElementName)
        .buildObject(defaultElementName);
    return object;
}

By using the above method, you can simplify the code that generates the assertion object into one line.

OpenSAMLUtils.buildSAMLObject(Assertion.class);

Example project

In order to facilitate readers'understanding and interpretation of subsequent articles, here is an example project: a very simple web site, which acts as SP; at the same time, the project also includes a very simple IDP;
The interaction between SAML protocol and SAML protocol will be developed.

Project address:
https://github.com/sunrongxin7666/OpenSAML-ref-project-demo-v3.git

This project is an experimental project based on Bitbucket. https://bitbucket.org/srasmusson/webprofile-ref-project-v3
It's built using Apache Maveng itself, and the startup project needs to be executed

mvn tomcat:run

Tomcat embedded in the project will start, and when it runs successfully, it will have the following information:

INFO: Starting Coyote HTTP/1.1 on http-8080

After my modification, the project can be opened in IntelliJ Idea in engineering mode with the operation mode set to mvn and the command is tomcat:run. This will facilitate reader debugging and modification.

After the project is launched, visit the following websites:
http://localhost:8080/webprofile-ref-project/app/appservlet
This is a SP simulation, the first visit to the site will jump to IDP, authentication process.

Clicking on the "Authenticate" button will authenticate and redirect back to SP.

So far, the whole process of SAML protocol has been completed, and the related log information will be output in the console.