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.
Table of Contents |
---|
Separate Signing and Encryption Keys
...
Therefore, combining these issues, if you want to perform rollover of a single keypair for both signing and encryption, you can follow these steps:
Add a second private key to your SP configuration explicitly as a decryption key (
use="encryption"
).Publish the corresponding public key in your metadata and wait for propagation.
Switch the encryption usage constraint in the SP configuration from the new key to the old key.
Remove the old public key from the metadata and wait for propagation.
Remove the old private key from your SP configuration.
As an example, if you start here:
...
Code Block | ||
---|---|---|
| ||
<CredentialResolver type="File" key="new-key.pem" certificate="new-cert.pem"/> |
Note |
---|
The above examples are not meant to be taken literally. If your files go by different names, live in non-default locations, then you will obviously need to adjust. Also take care as to whether one or both of your private keys has been encrypted on disk. You may need to supply a |
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 use
attribute 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:
Configure both credentials together in a chain.
Add one or more
<RelyingParty>
elements in the appropriate spot with akeyName
property that matches the "CN" from the desired credential's certificate subject (or that matches a subjectAltName).
...
Example using certificate subject as keyName
Code Block | ||
---|---|---|
| ||
<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
Code Block | ||||
---|---|---|---|---|
| ||||
<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> |
...