Metadata and trust subsystems in Guanxi

From Guanxi

Introduction

This section details the metadata and trust subsystems in Guanxi, which mainly apply to the Engine. The IdP has a very limited trust capability as the Shibboleth profile itself is limited in this respect, therefore the main emphasis on metadata/trust handling is with respect to the SP Engine.

Packages

The entity management classes are in the Guanxi::Common package:

org.guanxi.common.entity
org.guanxi.common.entity.impl

The metadata classes are in the Guanxi::Common package:

org.guanxi.common.metadata
org.guanxi.common.metadata.impl

while the trust classes are in the Guanxi::Common package:

org.guanxi.common.trust
org.guanxi.common.trust.impl

Metadata management in the Engine

Metadata can come from anywhere, from the internet to the local filesystem. It can describe one entity or multiple entities but more importantly, some metadata comes with in-built rules for trust verification. If we take the UK Access Management Federation as an example, this uses the Shibboleth SAML2 metadata extension, shibmeta:KeyAuthority, which lists all the root Certificate Authorities (CA) which can be used as trust anchors. If an entity's chain resolves to an un-trusted CA, then it must be rejected. However, the exact same metadata describing the exact same entity may exist in another federation, which does include that CA in its shibmeta:KeyAuthority section. So in that case, the entity may be trusted. Trust is therefore dependent on federation context but this is an alien concept to the software. To keep federations out of the application, the concept of metadata sources is used to segregate entity collections and their specific trust anchors.

Metadata is either injected directly via the registration form, loaded from the local store, or loaded via an application job. The first two cases are the essentially the same thing. Injected metadata is added to the local store and is eventually loaded from there on the next restart but the rules for processing it are the same, whether it's just been injected or a restart has occurred and it's been loaded from the local store. So we have two specific cases of "federations". A local federation of locally registered entities and an external federation, defined by metadata produced by, for example, the UK Access Management Federation. The two federations have different trust rules. The local federation does not require the use of trust anchors as the Engine will trust those entities which have been locally registered. The external federation does have the notion of trust anchors and it's conceivable that the same entity may appear in both federations.

To keep each federation separate, an EntityFarm is used, which is responsible for creating an EntityManager that will encompass metadata and trust for one source of entity metadata. Each EntityManager will provide metadata on its entities and also a TrustEngine which can be used for that collection of entities.

Local metadata

Metadata is considered local where an entity, such as an IdP has been registerd with the Engine via its registration interface:

https://localhost:8443/samlengine/register/idp

This results in a single entity metadata file. Validation of this metadata is performed by direct verification via an X509Certificate in the metadata. An incoming SAML Reponse, usually containing an AuthenticationStatement is subjected to a two part process. The digital signature on the SAML Response is first verified, then the X509Certificate from the signature is compared with the X509Certificate in the metadata. If they equate then the IdP is trusted.

Federation metadata

A multiple entity metadata file is considered a federation metadata file and is validated via either the single entity, local method detailed above, or the more complex PKIX path validation method, depending on the metadata format for an entity within the collection of entities. Details of the validation processes are described here.

Trust management

As described above, each collection of entities has its own trust rules, which are implemented by the specific TrustEngine that is associated with an EntityManager. This works in conjunction with the metadata that is also associated with that EntityManager.

Wiring it all together

To build the default metadata and trust subsystem for the Engine, just use the default spring config file:

ENGINE_HOME/WEB-INF/guanxi_sp_engine/config/spring/application/entity.xml

this file wires up all the necessary classes to provide the default Shibboleth metadata and trust functionality:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

  <bean id="spEntityFarm" class="org.guanxi.common.entity.impl.GuanxiEntityFarmImpl">
    <property name="entityManagers">
      <map>
        <!-- This is for locally registered entity metadata -->
        <entry key="local-metadata" value-ref="spSAML2EntityManager"/>
        <!-- This is for the UK Access Management Federation metadata -->
        <entry key="http://metadata.ukfederation.org.uk/ukfederation-metadata.xml" value-ref="spSAML2EntityManager"/>
      </map>
    </property>
  </bean>

  <!-- This entity manager looks after Guards. They have the same metadata format as entities in
       a SAML federation but have different trust requirements. -->
  <bean id="spLocalSAML2EntityManager" class="org.guanxi.common.entity.impl.GuanxiEntityManagerImpl"
        init-method="init" scope="prototype">
    <property name="entityHandlerClass"><value>org.guanxi.common.metadata.impl.GuanxiSAML2MetadataImpl</value></property>
    <property name="trustEngine"><ref bean="spLocalTrustEngine"/></property>
  </bean>

  <!-- This entity manager looks after SAML entities in a federation -->
  <bean id="spSAML2EntityManager" class="org.guanxi.common.entity.impl.GuanxiEntityManagerImpl"
        init-method="init" scope="prototype">
    <property name="entityHandlerClass"><value>org.guanxi.common.metadata.impl.GuanxiSAML2MetadataImpl</value></property>
    <property name="trustEngine"><ref bean="spShibbolethTrustEngine"/></property>
  </bean>

  <!-- Trust engine for use with local Guards -->
  <bean id="spLocalTrustEngine" class="org.guanxi.sp.engine.trust.impl.GuanxiLocalTrustEngineImpl" scope="prototype" />

  <!-- Trust engine for use with a Shibboleth federation -->
  <bean id="spShibbolethTrustEngine" class="org.guanxi.common.trust.impl.ShibbolethTrustEngineImpl" scope="prototype" />

</beans>

the default setup has an entity farm that contains two entity managers that look after two separate sources of metadata:

local-metadata - this is locally registered entities, registered via the Engine's registration page
http://metadata.ukfederation.org.uk/ukfederation-metadata.xml - this is for the UK Access Management Federation

each source of metadata is handled by different instances of the same class:

org.guanxi.common.entity.impl.GuanxiEntityManagerImpl

and each metadata handler delegates to a different instance of the same trust engine implementation:

org.guanxi.common.trust.impl.ShibbolethTrustEngineImpl

If you don't use either of these sources of metadata or you if you need another source, either plug the new one in and reuse existing metadata and trust handlers or develop your own and define them in this file.