...
Migrating
...
a
...
Certificate
...
in
...
SP
...
Metadata
...
This
...
article
...
is
...
for
...
site
...
administrators
...
and
...
delegated
...
administrators
...
wishing
...
to
...
migrate
...
an
...
old
...
certificate
...
out
...
of
...
SP
...
metadata.
...
Please
...
read
...
the
...
more
...
general
...
topic
...
on
...
...
...
before
...
continuing.
| Warning | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| =
|
|
|
|
|
| ||||||||
| }
Before [ |Key Generation], take a moment to consider how best to handle the all-important private key. {warning} In Federation |
In Federation metadata,
...
a
...
certificate
...
in
...
SP
...
metadata
...
is
...
contained
...
in
...
an
...
<md:KeyDescriptor>
...
element
...
(with
...
no
...
use
...
XML
...
attribute).
...
Such
...
a
...
certificate
...
may
...
be
...
used
...
for
...
signing,
...
TLS,
...
and/or
...
encryption.
...
Thus
...
there
...
is
...
a
...
single
...
key
...
descriptor
...
contained
...
in
...
the
...
<md:SPSSODescriptor>
...
element
...
(except
...
during
...
migration).
| Note | ||||||
|---|---|---|---|---|---|---|
| =
|
| ||||
| }
This procedure ultimately requires two decryption keys to be configured in the SP software at one time. Some software implementations do not permit multiple decryption keys to be configured (which is an implementation bug). Check your software documentation for further instructions. |
Regardless of the SP implementation used, the general migration process is as follows.
Preconditions:
- There is a single
<md:KeyDescriptor>element (with nouseXML attribute) in SP metadata. - The software is configured to use a single private key as a signing key, as an TLS key, and/or as a decryption key.
Procedure:
- Configure the SP software as follows:
- Continue to use the old key as a signing key, an TLS key, and/or a decryption key
- In addition, use the new key as a decryption key only
- Update the SP metadata as follows:
- Add a new
<md:KeyDescriptor>element (with nouseXML attribute) - Change the old
<md:KeyDescriptor>element to an<md:KeyDescriptor use="signing">element
- Add a new
- Wait for the newly updated metadata to propagate throughout the Federation.
- Configure the SP software as follows:
- Use the new key as a signing key, an TLS key, and/or a decryption key
- Discontinue use of the old key
- Remove the old
<md:KeyDescriptor use="signing">element from SP metadata.
Procedural details:
Step 1 requires the new key to be configured as a decryption key only. In particular, the new key must not be configured as a signing key or TLS key at this time (but see step 4). At the end of step 1, your software will have two decryption keys configured. Which one gets used depends on what metadata the IdP has available when the assertion is encrypted.
| Info | ||
|---|---|---|
| ||
The new decryption key should be listed first in the SP implementation. This is because the new key is the only encryption key listed in SP metadata. By listing the new key first in the configuration, fewer failed decryption attempts will occur. |
| Wiki Markup |
|---|
{note} Regardless of the SP implementation used, the general migration process is as follows. Preconditions: * There is a single {{<md:KeyDescriptor>}} element (with no {{use}} XML attribute) in SP metadata. * The software is configured to use a single private key as a signing key, as an TLS key, and/or as a decryption key. Procedure: # Configure the SP software as follows: ## Continue to use the old key as a signing key, an TLS key, and/or a decryption key ## In addition, use the new key as a decryption key only # Update the SP metadata as follows: ## Add a new {{<md:KeyDescriptor>}} element (with no {{use}} XML attribute) ## Change the old {{<md:KeyDescriptor>}} element to an {{<md:KeyDescriptor use="signing">}} element # Wait for the newly updated metadata to propagate throughout the Federation. # Configure the SP software as follows: ## Use the new key as a signing key, an TLS key, and/or a decryption key ## Discontinue use of the old key # Remove the old {{<md:KeyDescriptor use="signing">}} element from SP metadata. Procedural details: Step 1 requires the new key to be configured as a decryption key only. In particular, the new key must *not* be configured as a signing key or TLS key at this time (but see step 4). At the end of step 1, your software will have two decryption keys configured. Which one gets used depends on what metadata the IdP has available when the assertion is encrypted. {info:title=Key Order in the Configuration} The new decryption key should be listed first in the SP implementation. This is because the new key is the only encryption key listed in SP metadata. By listing the new key first in the configuration, fewer failed decryption attempts will occur. {info} {div:style=float:right;margin-left:1em;margin-bottom:1ex}!edit-x509-certs.png|thumbnail!{div} At step 2, log into the [Federation Manager] and bind a new certificate to the {{<md:SPSSODescriptor>}} element by adding a new {{<md:KeyDescriptor>}} element with no {{use}} XML attribute. That is, bind the new key to metadata as a "Signing and Encryption" key. Simultaneously change the old {{<md:KeyDescriptor>}} element to an {{<md:KeyDescriptor |
At step 2, log into the Federation Manager and bind a new certificate to the <md:SPSSODescriptor> element by adding a new <md:KeyDescriptor> element with no use XML attribute. That is, bind the new key to metadata as a "Signing and Encryption" key. Simultaneously change the old <md:KeyDescriptor> element to an <md:KeyDescriptor use="signing">
...
element,
...
that
...
is,
...
a
...
"Signing
...
Only"
...
key.
...
(Click
...
the
...
image
...
on
...
the
...
right
...
to
...
see
...
how
...
this
...
is
...
done
...
in
...
the
...
Federation
...
Manager.)
...
After
...
doing
...
so,
...
your
...
SP's
...
metadata
...
will
...
contain
...
two
...
(2)
...
key
...
descriptors,
...
one
...
of
...
which
...
is
...
new.
...
After
...
waiting
...
sufficiently
...
long,
...
completely
...
remove
...
the
...
old
...
key
...
from
...
the
...
configuration
...
at step 4. At the end of this step, only the new key will be configured in the software, as a signing key, an TLS key, and/or a decryption key. The old key will no longer be configured.
Finally, in conjunction with step 4, log into the Federation Manager at step 5 and remove the old key descriptor—the one with the use="signing" XML attribute—from the metadata. Leave the new <md:KeyDescriptor> element—the one with no use XML attribute—in the metadata.
This completes the migration process.
Implementation-Specific Details for SP Deployers
The key rollover process for a Shibboleth 2.x SP is fully documented in the Shib wiki.
| Note |
|---|
The migration process documented in the Shib wiki is different than the above process. The latter avoids having two encryption certificates in metadata at the same time, which is known to have interoperability issues with some IdP software (such as Microsoft AD FS 2.0). |
If you have questions about Shibboleth, please consult the Shib mailing lists.
Resources
...