The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

NativeSPCredentialResolver

Owned by ndk@internet2.edu
Last updated: Apr 11, 2012 by Scott CantorVersion comment
4 min read

The <CredentialResolver> element configures the component that provides the SP with access to public and private keys and certificates, or credentials. Keys are used to sign messages sent to IdPs and to decrypt data sent to the SP.

The credentials used by an SP MUST correspond to those supplied to relying parties and federations in the SP's metadata, or trust failures will result.

The SP web server manages its own keys and certificates to establish TLS/SSL connections with browser users. While it is technically possible for the SP software to use the same keypair and certificate used by the web server itself, this is generally not a good idea. Also note that in the current implementation, only the shibd process needs to access the SP's credentials, so the web server does not need any special access.

Common Attributes

  • type (string)
    • Plugin type name.

Filesystem Credential Resolver

Indicated by type="File", loads keys and certificates stored in files using common formats. PEM, DER, and PKCS#12 are supported.

The following two examples are equivalent:

<CredentialResolver type="File" key="/etc/shibboleth/sp.key" certificate="/etc/shibboleth/sp.crt"/>

<CredentialResolver type="File">
    <Key>
        <Path>/etc/shibboleth/sp.key</Path>
    </Key>
    <Certificate>
        <Path>/etc/shibboleth/sp.crt</Path>
    </Certificate>
</CredentialResolver>

Attributes

  • certificate (local pathname)
    • Shorthand for a <Certificate> element (see below) whose <Path> element contains the value of the attribute.
  • key (local pathname)
    • Shorthand for a <Key> element (see below) whose <Path> element contains the value of the attribute.
  • password (string)
    • Optional password for decrypting the private key if the key shorthand attribute is used.
  • keyName (string)
    • Optional "alias" for the key if the key shorthand attribute is used. See the <Name> element below.
  • use (one of "signing", "encryption", or "TLS")
    • Optional setting that limits the application of the credential to the designated purpose. Note that "signing" implies "TLS" (it's a superset).
  • keyInfoMask (integer bitmask) (defaults to 15) (Version 2.1 and Above)
    • Optional bitmask controlling the content of generated KeyInfo information. By default, various combinations of the key value, name(s), X.509 certificate, and X.509 subject name are included. Certificate issuer and serial number are not, because of known bugs in non-Shibboleth software. The actual output in any given case depends on the underlying implementation.
  • extractNames (boolean) (defaults to true) (Version 2.3.1 and Above)
    • Optional flag to disable the default extraction of "key names" based on the supplied certificate. Allows deployer to maximize control over the exact names, if any, that will be available to match against a compared key in a signature or encrypted key block. Normally left on except in specialized cases.

Child Elements

  • <Key>
    • References a private key. The following attributes and elements can appear in it:
      • password (string)
        • Optional password for decrypting the private key.
      • format ("PEM", "DER", or "PKCS12")
        • Optional indicator of key file format. Will be auto-detected in most cases.
      • <Path>
        • Element containing pathname of key file. Required prior to version 2.2.
      • <Name> (zero or more)
        • Attaches an "alias" to the key to allow for selection of the key based on its name. Also adds the name to the <ds:KeyInfo> element included in XML messages to assist relying parties in identifying which key was used.
  • <Certificate>
    • References one or more X.509 certificates. The following attributes and elements can appear in it:
      • password (string)
        • Optional password for decrypting the certificate.
      • format ("PEM", "DER", or "PKCS12")
        • Optional indicator of certificate file format. Will be auto-detected in most cases.
      • <Path>
        • Element containing pathname of certificate file. Required prior to version 2.2. As of version 2.2 and above, additional certificates can be supplied using multiple <Path> elements.
      • <CAPath> (zero or more)
        • Element containing pathname of an intermediate CA file. Deprecated as of version 2.2.
  • <CRL>
    • References a certificate revocation list. This is generally not used as part of a local credential belonging to the SP, but is typically used as part of a credential supplied to certain kinds of plugins involved in metadata verification. The following attributes and elements can appear in it:
      • format ("PEM", "DER")
        • Optional indicator of CRL file format. Will be auto-detected in most cases.
      • <Path>
        • Element containing pathname of CRL. Required prior to version 2.2. As of version 2.2 and above, additional CRLs can be supplied using multiple <Path> elements.

Version 2.2 and Above

As of version 2.2, the plugin has been rewritten and enhanced with additional capabilities for reloading file-based credentials after changes, and loading remote URLs to disk before use. The following additional attributes and elements can be used on each of the <Key>, <Certificate>, and <CRL> child elements above.

  • backingFilePath (local pathname)
    • If the <URL> element below is used, this attribute is required in order to provide a location at which the resource at the URL will be stored.
  • reloadChanges (boolean, defaults to "true")
    • If the <Path> element is used, controls whether changes to the file are detected in order to reload the information.
  • reloadInterval (time in seconds, defaults to zero)
    • If non-zero, and the <URL> element below is used, indicates the maximum elapsed time in seconds after which the URL will be downloaded again.
  • <URL> (zero or more)
    • Alternative to Path element containing the URL at which the credential information can be found.

In the case of certificates and CRLs, multiple <Path> and <URL> elements can appear, including a mixture of the two, as required.

Chaining Credential Resolver

Indicated by type="Chaining", allows multiple sources of credentials to be queried in sequence.

With V2.4 and above, this is implied by any configuration with multiple <CredentialResolver> elements, so is no longer explicitly needed.

Primarily used to allow different keys and certificates to be used based on the identity provider. While this works in some situations, it can be complex to get working, and it's strongly advisable for SPs to maintain a single set of credentials to use for all interactions.

When chaining Filesystem resolvers, you will need to assign "names" to each keypair using the keyName attribute or <Name> element for later selection using the <RelyingParty>'s keyName attribute. Generally this should be the "CN" from the X.509 Subject, or a subjectAltName value, that uniquely differentiates the certificates.

A simple example follows, but for more details, see the NativeSPMultipleCredentials topic.

<CredentialResolver type="Chaining">
     <CredentialResolver type="File" key="sp.key" certificate="sp.crt" keyName="default.example.org"/>
     <CredentialResolver type="File" key="special.key" certificate="special.crt" keyName="special.example.org"/>
</CredentialResolver>

Child Elements

  • <CredentialResolver> (one or more)
    • Embedded credential resolver plugins to chain together.