Page Comparison

There are a few typical reasons for supplying the SP with multiple keypairs, or "credentials", to use for authentication and encryption:

• separating signing/TLS and encryption keys

• key "rollover"

• federation or partner-dictated requirements to use particular certificates

These scenarios are discussed in more detail below, with examples explaining how to configure the SP in each case. In each scenario, the common factor is the use of a "Chaining"  <CredentialResolver> to "wrap" two or more individual resolvers (usually of type "File") and enable each credential to be loaded and used. The varying part pertains to how credentials are labeled so that the selection process works as intended in each case.

Note also that the use of encryption in this context is specific to XML Encryption, and for the present, limited to use of SAML 2.0.

Separate Signing and Encryption Keys

This is the simplest case (but also not all that common until recently) case, and is handled by labeling the individual resolvers in the chain with a use property, typically of "signing" or "encryption".

...

Therefore, combining these issues, if you want to perform rollover of a single keypair for both signing and encryption, you can follow these steps:

1. Add a second private key to your SP configuration explicitly as a decryption key (use="encryption").

2. Publish the corresponding public key in your metadata and wait for propagation.

3. Switch the encryption usage constraint in the SP configuration from the new key to the old key.

4. Remove the old public key from the metadata and wait for propagation.

5. Remove the old private key from your SP configuration.

As an example, if you start here:

...

<CredentialResolver type="File" key="new-key.pem" certificate="new-cert.pem"/>

The above process is suitable for cases in which the metadata's <md:KeyDescriptor> elements do not carry a use XML attribute and there is no opportunity to introduce such a useattribute into metadata. Other approaches may be more suitable for non-Shibboleth implementations.

...

Assuming a scenario in which you want to use one credential by default, but a second credential when dealing with a particular relying party, you will typically do the following:

1. Configure both credentials together in a chain.

2. Add one or more <RelyingParty> elements in the appropriate spot with a keyName property that matches the "CN" from the desired credential's certificate subject (or that matches a subjectAltName).

...

...

Example using certificate subject as keyName

<ApplicationDefaults ...>
    ...
    <Errors .../>
    <RelyingParty Name="https://idp.example.org/idp/shibboleth" keyName="trusted.example.org"/>
    ...
    <CredentialResolver type="Chaining">
        <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
        <CredentialResolver type="File" key="trusted-key.pem" certificate="trusted-cert.pem"/>
    </CredentialResolver>
</ApplicationDefaults>

If you find that each candidate credential shares essentially the same certificate subject information, then you can use a locally-chosen name in your <RelyingParty> element and add the same value to a keyName attribute or <Name> element in the <CredentialResolver>.

Example using locally chosen keyName

<ApplicationDefaults ...>
    ...
    <Errors .../>
    <RelyingParty Name="https://idp.example.org/idp/shibboleth" keyName="Special"/>
    ...
    <CredentialResolver type="Chaining">
        <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
        <CredentialResolver type="File" key="trusted-key.pem" certificate="trusted-cert.pem" keyName="Special"/>
    </CredentialResolver>
</ApplicationDefaults>

...