Chapter 11. PicketLink Subsystem

11.1. Overview

The PicketLink Subsystem extends JBoss Application Server to introduce some new capabilities, providing a infrastructure to deploy and manage PicketLink deployments and services. Currently, only JBoss Enterprise Application Platform 6.1 is supported.

In a nutshell, the most important capabilities are:

A rich domain model supporting the configuration of PicketLink Federation (specially SAML-based applications) deployments and Identity Management services.
Minimal configuration for deployments. Part of the configuration is done automatically with some hooks for customizations.
Minimal dependencies for deployments. All PicketLink dependencies are automatically set from modules.
Configuration management using JBoss Application Server Management API. It can be managed in different ways: HTTP/JSON, CLI, Native DMR, etc.
Identity Management Services are exposed in JNDI and are fully integrated with CDI. You can use PicketLink Identity Management without requiring the base module dependencies.
Applications don't need to change when moving between different environments such as development, testing, staging or production. All the configuration is defined outside the application.
Users need to learn a single and consolidated schema.

Important

The subsystem is not available yet in JBoss Enterprise Application Platform 6. While it is not updated with the PicketLink modules and subsystem you must follow the instructions on the next sections to get it up and running.

11.2. Installation and Configuration

To get the PicketLink subsystem properly installed you only need to use the PicketLink Installer.

Note

This step may no longer be required once the subsystem is available in a future version of JBoss Enterprise Application Platform.

Once the subsystem is properly installed you need to change your standalone/domain.xml, inside your EAP installation, with the following extension and subsystem:


<extensions>

  ...



  <!-- Add the PicketLink extension -->

  <extension module="org.picketlink.as.extension" />



</extensions>

<profile>



  <!-- Add the PicketLink Subsystem -->

  <subsystem xmlns="urn:jboss:domain:picketlink:1.0" />



  ...

</profile>

11.3. Configuring the PicketLink Dependencies for your Deployment

One your JBoss Application Server is properly configured with all PicketLink libraries and their respective modules, you can add a META-INF/jboss-deployment-structure.xml file inside the root directory of your deployment to configure the dependencies as follows:


<jboss-deployment-structure>

  <deployment>

      <dependencies>

        <!-- This will enable PicketLink Authentication/Authorization and IDM dependencies to your deployment. -->

      <module name="org.picketlink.core" />

        </dependencies>

  </deployment>

</jboss-deployment-structure>


<jboss-deployment-structure>

  <deployment>

      <dependencies>

        <!-- This will enable only the IDM dependencies to your deployment. -->

      <module name="org.picketlink.idm" />

        </dependencies>

  </deployment>

</jboss-deployment-structure>

It is strongly recommended that you use the PicketLink libraries from your JBoss Application Server modules. When using this way, you don't need to add any additional library to your deployments and you can easily manage the PicketLink libraries without requiring changes to your deployments.

Considering that you no longer need the PicketLink libraries inside your deployment, you must change your Maven dependencies to use the PicketLink dependencies with scope provided:


<dependency>

  <groupId>org.picketlink</groupId>

  <artifactId>picketlink-api</artifactId>

  <scope>provided</scope>

</dependency>



<dependency>

  <groupId>org.picketlink</groupId>

  <artifactId>picketlink-idm-api</artifactId>

  <scope>provided</scope>

</dependency>

11.4. Domain Model

The subsystem provides a domain model that allows you to configure the PicketLink Federation and Identity Management services using the standalone/domain.xml inside your EAP installation. The domain model is very easy to understand if you are already familiar with the PicketLink configuration.


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

  <!-- An example of the PicketLink Federation configuration -->

  <federation alias="federation-with-signatures">

    <saml token-timeout="4000" clock-skew="0"/>

    <key-store url="/jbid_test_keystore.jks" passwd="changeit" sign-key-alias="localhost" sign-key-passwd="changeit"/>

    <identity-provider url="http://localhost:8080/idp-sig/" alias="idp-sig.war" security-domain="idp" supportsSignatures="true" strict-post-binding="false">

      <trust>

        <trust-domain name="localhost" cert-alias="localhost"/>

        <trust-domain name="127.0.0.1" cert-alias="localhost"/>

      </trust>

    </identity-provider>

    <service-providers>

      <service-provider alias="sales-post-sig.war" security-domain="sp" url="http://localhost:8080/sales-post-sig/" post-binding="true" supportsSignatures="true"/>

      <service-provider alias="sales-redirect-sig.war" security-domain="sp" url="http://localhost:8080/sales-redirect-sig/" post-binding="false" supportsSignatures="true" strict-post-binding="false"/>

    </service-providers>

  </federation>



  <!-- An example of the PicketLink Identity Management configuration -->

  <identity-management jndi-name="picketlink/JPAPartitionManager" alias="jpa.partition.manager">

    <identity-configuration name="jpa.store.config">

      <jpa-store data-source="jboss/datasources/ExampleDS">

        <supportedTypes supportsAll="true"/>

      </jpa-store>

    </identity-configuration>

  </identity-management>

</subsystem>

Note

The domain model XML schema can be obtained from https://github.com/picketlink/picketlink-as-subsystem/blob/master/src/main/resources/schema/jboss-picketlink_1_0.xsd.

11.5. Identity Management

The subsystem provides a domain model that allows you to configure PicketLink Identity Management Services using the standalone/domain.xml. Basically, what the subsystem does is parse the configuration, automatically build a org.picketlink.idm.PartitionManager and expose it via JNDI for further access.

With the subsystem you can :

Externalize and centralize the IDM configuration for deployments.
Define multiple configuration for identity management services.
Expose the PartitionManager via JNDI for further access.
If using CDI, inject the PartitionManager instances using the Resource annotation.
If using CDI, use the PicketLink IDM alone without requiring the base module dependencies. In this case you can provide your own configuration without using the subsystem's domain model.

The IDM domain model is an abstraction for all PicketLink IDM configuration, providing a single schema from which all configurations can be defined. If you're already familiar with the Configuration API, you'll find the domain pretty simple and intuitive.


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

  <identity-management jndi-name="picketlink/FileBasedPartitionManager" alias="file.based.partition.manager">

    <identity-configuration name="file.config">

      <file-store working-dir="/tmp/pl-idm-complete" always-create-files="true" async-write="true"

                  async-write-thread-pool="10">

        <supportedTypes supportsAll="true"/>

      </file-store>

    </identity-configuration>

  </identity-management>



  <identity-management jndi-name="picketlink/JPADSBasedPartitionManager" alias="jpa.ds.based.partition.manager">

    <identity-configuration name="jpa.config">

      <jpa-store data-source="jboss/datasources/ExampleDS">

        <supportedTypes supportsAll="true"/>

      </jpa-store>

    </identity-configuration>

  </identity-management>

</subsystem>

Note

If you are looking for more examples about how to use the domain model, take a look at https://github.com/picketlink/picketlink-as-subsystem/blob/master/src/test/resources/picketlink-subsystem.xml.

Most of the configuration are known if you are familiar with the PicketLink IDM configuration. But the domain model provides some additional configuration in order to allow deployments to access the configured identity management services. Basically, each configuration must have a:

jndi-url, that defines where the PartitionManager should be published in the JNDI tree for further access.
alias, an alias for the configuration to allow other subsystems to inject the Identity Management Services using the MSC injection infrastructure.

The rest of the configuration is very similar with how you use the Configuration API to programmaticaly build the IDM configuration. For a complete description of the domain model elements, please take a look at the XML Schema.

11.5.1. `JPAIdentityStore`

In order to provide a better and easy integration with the container, the JPAIdentityStore configuration provides some additional configuration to let you configure how the EntityManagerFactory is built or used by the JPAIdentityStore.

11.5.1.1. Using a DataSource JNDI Url

When you specify a DataSource JNDI url, the subsystem will automatically build a EntityManagerFactory using a default configuration. This is the fast way to get a JPA Identity Store configuration.

The DataSource JNDI url can be specified using the data-source attribute as follows:


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

  <identity-management jndi-name="picketlink/JPADSBasedPartitionManager" alias="jpa.ds.based.partition.manager">

    <identity-configuration name="jpa.config">

      <jpa-store data-source="jboss/datasources/ExampleDS">

        <supportedTypes supportsAll="true"/>

      </jpa-store>

    </identity-configuration>

  </identity-management>

</subsystem>

This configuration option is very handy if you want to use the basic IDM model provided by PicketLink.

11.5.1.2. Using a `EntityManagerFactory` JNDI Url

Sometimes you may need more control over the JPA Persistence Unit configuration. In this case you can use the entity-manager-factory attribute to specify where your previously built EntityManagerFactory is located.


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

  <identity-management jndi-name="picketlink/JPAEMFBasedPartitionManager" alias="jpa.emf.based.partition.manager">

    <identity-configuration name="jpa.config">

      <jpa-store entity-manager-factory="jboss/PicketLinkEMF">

        <supportedTypes>

          <supportedType class="org.picketlink.idm.model.Partition"/>

          <supportedType class="org.picketlink.idm.model.IdentityType"/>

          <supportedType class="org.picketlink.idm.model.Relationship"/>

        </supportedTypes>

      </jpa-store>

    </identity-configuration>

  </identity-management>

</subsystem>

This configuration option is very useful if you want to support custom types.

11.5.1.3. Using a JBoss Module

The JPA Identity Store configuration allows you to specify a JBoss Module from where the JPA Persistence Unit and mapped entities will be loaded from.

This configuration can be done using two attributes:

entity-module, the module name where the JPA Persistence Unit and all mapped entities are located.
entity-module-unit-name, the name of the JPA Persistence Unit name. If you don't provide a name the subsystem will use identity.


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

    <identity-management jndi-name="picketlink/JPACustomEntityBasedPartitionManager" alias="jpa.custom.entity.based.partition.manager">

      <identity-configuration name="jpa.config">

        <jpa-store entity-module="org.picketlink.test" entity-module-unit-name="custom-pu" module="org.picketlink.test">

          <supportedTypes>

            <supportedType class="org.picketlink.idm.model.Partition"/>

            <supportedType class="org.picketlink.idm.model.IdentityType"/>

            <supportedType class="org.picketlink.idm.model.Relationship"/>

          </supportedTypes>

          <credential-handlers>

            <credential-handler class="test.org.picketlink.as.subsystem.module.idm.SaleAgentPasswordCredentialHandler"/>

          </credential-handlers>

        </jpa-store>

      </identity-configuration>

    </identity-management>

  </subsystem>

11.5.2. Usage Examples

If you want to have your deployment properly configured with the PicketLink Identity Management Services, you should add a META-INF/jboss-deployment-structure.xml file to your deployment as follows:


<jboss-deployment-structure>

  <deployment>

    <dependencies>

      <module name="org.picketlink.idm" />



        <!-- We only need this dependency because we want to use the built-in schema -->

        <module name="org.picketlink.idm.schema" />

    </dependencies>

  </deployment>

  </jboss-deployment-structure>

Note

When you're configuring the PicketLink dependencies using the META-INF/jboss-deployment-structure.xml file you don't need to ship the libraries inside your deployment. All the necessary dependencies are automatically resolved and configured.

11.5.2.1. Injecting a `PartitionManager` using `Resource` annotation


@Resource(mappedName="picketlink/JPADSBasedPartitionManager")

  private PartitionManager jpaDSBasedPartitionManager;

11.5.2.2. Producing your own configuration


@ApplicationScoped

  public static class MyIdentityConfigurationProducer {



  @Produces

  public IdentityConfiguration produceIdentityConfiguration() {

    return new IdentityConfigurationBuilder().named("default").stores().file().supportAllFeatures().build();

  }



  }

11.6. Federation

All the configuration is external from applications where there is no need to add or change configuration files inside the application being deployed. The subsystem is responsible for during deployment time properly configure the applications being deployed, according with the configurations defined in the domain model:

The configurations in picketlink.xml are automatically created. No need to have this file inside your deployment.
The PicketLink Authenticators (Apache Tomcat Valves) for Identity Providers and Service Providers are automatically registered. No need to have a jboss-web.xml file inside your deployment.
The PicketLink dependencies are automatically configured. No need to have a META-INF/jboss-deployment-structure.xml inside your deployment defining the org.picketlink module as a dependency.
The Security Domain is automatically configured using the configurations defined in the domain model. No need to have a WEB-INF/jboss-web.xml file inside your deployment.

The table bellow summarizes the main differences between the traditional configuration and the subsystem configuration for PicketLink applications:

Configuration	Old Configuration	Subsystem Configuration
WEB-INF/picketlink.xml	Required	Not required. If present it will be considered instead of the configurations defined in the domain model.
WEB-INF/jboss-web.xml	Required	Not required. The PicketLink Authenticators (Tomcat Valves) and the Security Domain is read from the domain model.
META-INF/jboss-deployment-structure.xml	Required	Not required. When the PicketLink Extension/Subsystem is enabled, the dependency to the org.picketlink module is automatically configured.

11.6.1. The Federation concept (Circle of Trust)

When using the PicketLink subsystem to configure and deploy your identity providers and service providers, all of them are grouped in a Federation.

A Federation can be understood as a Circle of Trust (CoT) from which applications share common configurations (certificates, saml specific configurations, etc) and where each participating domain is trusted to accurately document the processes used to identify a user, the type of authentication system used, and any policies associated with the resulting authentication credentials.

Each federation has one Identity Provider and many Service Providers. You do not need to specify for each SP the IDP that it trusts, because this is defined by the federation.

11.6.2. Federation Domain Model

The domain model is an abstraction for all PicketLink Federation configuration, providing a single schema from which all configurations can be defined for Identity Providers or Service Providers, for example.

The example bellow shows how the domain model can used to configure an Identity Provider and a Service Provider.


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

  <federation alias="federation-without-signatures">



    <saml token-timeout="4000" clock-skew="0" />



    <identity-provider alias="idp.war" security-domain="idp" supportsSignatures="false" url="http://localhost:8080/idp/">

        <trust>

            <trust-domain name="localhost" />

            <trust-domain name="mycompany.com2" />

            <trust-domain name="mycompany.com3" />

            <trust-domain name="mycompany.com4" />

        </trust>

        <handlers>

            <handler class="com.mycompany.CustomHandler">

                <handler-parameter name="param1" value="paramValue1"/>

                <handler-parameter name="param2" value="paramValue2"/>

                <handler-parameter name="param3" value="paramValue3"/>

            </handler>

        </handlers>

    </identity-provider>



    <service-providers>

        <service-provider alias="sales.war" post-binding="true" security-domain="sp" url="http://localhost:8080/sales/" supportsSignatures="false">

            <handlers>

                <handler class="com.mycompany.CustomHandler">

                    <handler-parameter name="param1" value="paramValue1"/>

                    <handler-parameter name="param2" value="paramValue2"/>

                    <handler-parameter name="param3" value="paramValue3"/>

                </handler>

            </handlers>

        </service-provider>

        <service-provider alias="employee.war" post-binding="true" security-domain="sp" url="http://localhost:8080/employee/" supportsSignatures="false" />

    </service-providers>

  </federation>

</subsystem>

Note

If you are looking for more examples about how to use the domain model, take a look at https://github.com/picketlink/picketlink-as-subsystem/blob/master/src/test/resources/picketlink-subsystem.xml.

11.6.3. Usage Examples

This section will guide you through the basic steps to get an Identity Provider and a Service Provider working using the subsystem configuration.

Download the PicketLink Federation Quickstarts from https://repository.jboss.org/nexus/content/groups/public/org/picketlink/quickstarts/picketlink-quickstarts/2.1.8.Final/picketlink-quickstarts-2.1.8.Final-webapps-jboss-as7.zip.

Extract the file and copy the idp.war and sales-post.war to${JBOSS.HOME.dir}/standalone/deployments.

Open both files (idp.war and sales-post.war) and remove the following configuration files:

WEB-INF/picketlink.xml
META-INF/jboss-deployment-structure.xml
WEB-INF/jboss-web.xml

Important

Don't forget to configure the security domains for both applications.

Open the standalone.xml and add the following configuration for the PicketLink subsystem:


<subsystem xmlns="urn:jboss:domain:picketlink:1.0">

  <federation alias="example-federation">

      <!-- Identity Provider configuration -->

      <identity-provider alias="idp.war" security-domain="idp" supportsSignatures="false" url="http://localhost:8080/idp/">

          <trust>

              <trust-domain name="localhost" />

          </trust>

      </identity-provider>



      <!-- Service Provider configuration -->

      <service-providers>

          <service-provider alias="sales-post.war" post-binding="false" security-domain="sp" url="http://localhost:8080/sales-post/" supportsSignatures="false" />

      </service-providers>

  </federation>

</subsystem>

To make sure that everything is ok, please start JBoss AS and try to access the sales application. You should be redirected to the idp application.

11.6.4. Metrics and Statistics

Metrics and statistics can be collected from applications deployed using the PicketLink subsystem. This means you can get some useful information about how your Identity Providers and Service providers are working.

How many SAML assertions were issued by your identity provider ?
How many times your identity provider respond to service providers ?
How many SAML assertions were expired ?
How many authentications are done by your identity provider ?
How many errors happened ? Trusted Domain errors, signing errors, etc.

To query those metrics and statistics you can use JBoss CLI as follows:


[standalone@localhost:9999 federation=example-federation] ./identity-provider=idp.war:read-resource(include-runtime=true)

{

    "outcome" => "success",

    "result" => {

         "alias" => "idp.war",

         "created-assertions-count" => "1",

         "error-response-to-sp-count" => "0",

         "error-sign-validation-count" => "0",

         "error-trusted-domain-count" => "0",

         "expired-assertions-count" => "0",

         "external" => false,

         "handler" => undefined,

         "login-complete-count" => "0",

         "login-init-count" => "0",

         "response-to-sp-count" => "3",

         "security-domain" => "idp",

         "strict-post-binding" => false,

         "supportsSignatures" => false,

         "url" => "http://localhost:8080/idp",

         "trust-domain" =>{"localhost" => undefined}

    }

}

11.7. Management Capabilities

One of the benefits about using the PicketLink subsystem to deploy your applications is that they can be managed in different ways:

PicketLink Console

The console provides a UI, based on the AS7 Administration Console, to help manage your PicketLink deployments. Basically, all the configuration defined in the domain model can be managed using the console.
JBoss AS7 CLI Interface (Native Interface)

The CLI interface provides a command line tool from where you can query and change all the configuration defined for your applications.
JBoss AS7 HTTP Interface

JBoss AS7 allows you to manage your running installations using the HTTP protocol with a JSON encoded protocol and a de-typed RPC style API.

Note

Currently the PicketLink Console supports only the federation domain model.