Defining a new Trust Engine

Trust engines are the heart of the IdP's security system. Misconfiguring a trust engine can lead to serious vulnerabilities. You should not change any of the trust engine definitions that ship with the IdP unless you are very sure you understand everything about how these components, XML digital signatures, and client certificate authentication operate.

The IdP has two types of trust engines. Signature trust engines which are used to validate a digital signature and ensure that the credentials used to create the signature are trusted, and credential trust engines which are used to ensure that the credentials used by a service provider to connect to the IdP are valid and trusted. What it means to be trusted depends on the exact trust engine used.

All trust engines are defined in the IdP's relying-party.xml configuration file after any credentials and before any defined security policies.

Signature Trust Engines

Signature trust engines are, themselves, subdivided into two groups. Static engines which evaluate a signature against static information explicitly provided at configuration time and metadata engines which use SAML metadata, which may change over time, to lookup or derive the needed security information.

Static Signature Trust Engines

Explicit Key Static Signature Trust Engine

The explicit key static signature trust engine is the simplest trust engine. A signature evaluated by this trust engine is considered valid and trusted if the signature validates with the key defined in this engine.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:StaticExplicitKeySignature"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine.

Additionally the trust engine contains one or more IdP credentials.

Example Explicit Key Static Signature Trust Engine

<security:TrustEngine xsi:type="security:StaticExplicitKeySignature"
                      id="UNIQUE_ID">

    <Credential xsi:type="X509Filesystem" xmlns="urn:mace:shibboleth:2.0:security"
                id="MyCredential">
        <KeyName>key.example.org</KeyName>
        <PrivateKey password="myKeyPa$$word">/path/to/my/private.key</PrivateKey>
        <Certificate>/path/to/my/public.crt</Certificate>
    </Credential>

</security:TrustEngine>

StaticPKIXSignature

The static PKIX signature trust engine validates the signature with a certificate embedded within the signature. It then evaluates the trustworthiness of the certificate through PKIX validation. It is assumed that certificates which pass this validation should be trusted.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:StaticPKIXSignature"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine

The trust engine then may contain zero or more TrustedName elements.

The trust engine must then contain one, or more ValidatonInfo elements.

The trust engine may then contain a single, optional ValidationOptions element.

Example Static PKIX Signature Trust Engine

<security:TrustEngine xsi:type="security:StaticPKIXSignature"
                      id="UNIQUE_ID">

    <TrustedName>CN=idp.example.org,DC=example,DC=org</TrustedName>
    <TrustedName>idp.example.org</TrustedName>
    <TrustedName>https://sp.example.org/shibboleth</TrustedName>

    <ValidationInfo id="UNIQUE_ID" VerifyDepth="5" xsi:type="PKIXFilesystem" xmlns="urn:mace:shibboleth:2.0:security">
        <Certificate>/path/to/trusted/cert1</Certificate>
        <Certificate>/path/to/trusted/cert2</Certificate>
        <CRL>/path/to/trusted/crl</CRL>
    </ValidationInfo>

</security:TrustEngine>

Metadata Signature Trust Engines

Explicit Key Metadata Signature

This metadata based signature trust engine evaluates trustworthiness by looking to an entity's role metadata. If a key with either no usage indicator, or a signing usage indicator, validates the signature then the signature is trusted. This is because that any loaded metadata is considered to represent trusted information.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:MetadataExplicitKeySignature"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine
metadataProviderRef - the ID of the metadata provider that contains the trusted metadata

Example Explicit Key Metadata Signature

<security:TrustEngine xsi:type="security:MetadataExplicitKeySignature"
                      id="UNIQUE_ID"
                      metadataProviderRef="METADATA_PROVIDER_ID" />

PKIX Metadata Signature Trust Engine

This trust engine is similar to the explicit key metadata trust engine except that it also performs PKIX validation using information located within the metadata. This information is a shibboleth-specific extension to the SAML metadata.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:MetadataPKIXSignature"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine
metadataProviderRef - the ID of the metadata provider that contains the trusted metadata

The trust engine may then contain a single, optional ValidationOptions element.

Example PKIX Metadata Signature Trust Engine

<security:TrustEngine xsi:type="security:MetadataPKIXSignature"
                      id="UNIQUE_ID"
                      metadataProviderRef="METADATA_PROVIDER_ID" />

X.509 Credential Trust Engines

X.509 credential trust engines are used to determine if an X.509 credential, provided by a client as a means of authentication, is valid and trustworthy. Currently this is only used when the service provider is issuing an attribute query to the IdP, but in the future other messages might use this.

Like the signature trust engines, the X.509 credential trust engines come are divided into two groups. Static engines which evaluate an X.509 credential against static information explicitly provided at configuration time and metadata engines which use SAML metadata, which may change over time, to lookup or derive the needed security information.

Static X.509 Credential Trust Engine

Explicit Key Static X.509 Credential Trust Engine

The explicit key static X.509 credential trust engine find a credential valid if it matches the credential within the trust engine's configuration.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:StaticExplicitKey"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine.

Additionally the trust engine contains one or more IdP credentials.

Example Static X.509 Credential Trust Engine

<security:TrustEngine xsi:type="security:StaticExplicitKey"
                      id="UNIQUE_ID">

    <Credential xsi:type="X509Filesystem" xmlns="urn:mace:shibboleth:2.0:security"
                id="MyCredential">
        <KeyName>key.example.org</KeyName>
        <PrivateKey password="myKeyPa$$word">/path/to/my/private.key</PrivateKey>
        <Certificate>/path/to/my/public.crt</Certificate>
    </Credential>

</security:TrustEngine>

PKIX Static X.509 Credential Trust Engine

The static PKIX X.509 credential trust engine validates an X.509 certificate through PKIX validation. It is assumed that certificates which pass this validation should be trusted.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:StaticPKIXX509Credential"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine

The trust engine then may contain zero or more TrustedName elements.

The trust engine must then contain one, or more ValidatonInfo elements.

The trust engine may then contain a single, optional ValidationOptions element.

Example Static PKIX X.509 Trust Engine

<security:TrustEngine xsi:type="security:StaticPKIXX509Credential"
                      id="UNIQUE_ID">

    <TrustedName>CN=idp.example.org,DC=example,DC=org</TrustedName>
    <TrustedName>idp.example.org</TrustedName>
    <TrustedName>https://sp.example.org/shibboleth</TrustedName>

    <ValidationInfo id="UNIQUE_ID" VerifyDepth="5" xsi:type="PKIXFilesystem" xmlns="urn:mace:shibboleth:2.0:security">
        <Certificate>/path/to/trusted/cert1</Certificate>
        <Certificate>/path/to/trusted/cert2</Certificate>
        <CRL>/path/to/trusted/crl</CRL>
    </ValidationInfo>

</security:TrustEngine>

Metadata X.509 Credential Trust Engine

Explicit Key Metadata X.509 Credential Trust Engine

This metadata based X.509 credential trust engine evaluates trustworthiness by looking to an entity's role metadata. If a key with either no usage indicator, or a signing usage indicator, is the credential provide by the peer then it is trusted. This is because that any loaded metadata is considered to represent trusted information.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:MetadataExplicitKey"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine
metadataProviderRef - the ID of the metadata provider that contains the trusted metadata

Example Explicit Key Metadata X.509 Credential Trust Engine

<security:TrustEngine xsi:type="security:MetadataExplicitKey"
                      id="UNIQUE_ID"
                      metadataProviderRef="METADATA_PROVIDER_ID" />

PKIX Metadata X.509 Credential Trust Engine

This trust engine is similar to the explicit key metadata X.509 credential trust engine except that it also performs PKIX validation using information located within the metadata. This information is a shibboleth-specific extension to the SAML metadata.

The trust engine is defined by the element <security:TrustEngine xsi:type="security:MetadataPKIXX509Credential"> with the required attribute:

id - gives the trust engine a unique, within the relying party configuration, identifier which may be used by other components to refer to the engine
metadataProviderRef - the ID of the metadata provider that contains the trusted metadata

The trust engine may then contain a single, optional ValidationOptions element.

Example PKIX Metadata X.509 Credential Trust Engine

<security:TrustEngine xsi:type="security:MetadataPKIXX509Credential"
                      id="UNIQUE_ID"
                      metadataProviderRef="METADATA_PROVIDER_ID" />

Browser not supported