Date: Fri, 29 Mar 2024 06:35:28 +0000 (UTC) Message-ID: <544244025.3.1711694128060@170d30bec080> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_2_1360613828.1711694128059" ------=_Part_2_1360613828.1711694128059 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
There are a few typical reasons for supplying the SP with multip= le keypairs, or "credentials", to use for authentication and encryption:
These scenarios are discussed in more detail below, with examples explai=
ning how to configure the SP in each case. In each scenario, the common fac=
tor is the use of a "Chaining" <=
;CredentialResolver>
to "wrap" two or more individual resolve=
rs (usually of type "File") and enable each credential to be loaded and use=
d. The varying part pertains to how credentials are labeled so that the sel=
ection 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.
This is the simplest (but also not all that common) case, and is handled=
by labeling the individual resolvers in the chain with a use
=
property, typically of "signing" or "encryption".
<Cred= entialResolver type=3D"Chaining"> <CredentialResolver type=3D"File" key=3D"signing.key" certificate= =3D"signing.crt" use=3D"signing"/> <CredentialResolver type=3D"File" key=3D"decrypt.key" certificate= =3D"decrypt.crt" use=3D"encryption"/> </CredentialResolver>
For this use case, no additional labeling or configuration should be nec= essary to get the right key selected.
Typically with rolling over keys or certificates you have two separate c= oncerns: migrating your signing/authentication keys and your encryption key= s. On the authentication side, the solution is to publish the new key/certi= ficate in your metadata and wait for that to propagate before switching you= r SP from the old credential to the new one. In that scenario, you need not= ever configure both within the SP itself (i.e., it's different from this t= opic's goal).
On the other hand, with encryption you have the opposite problem. Once y= ou publish a new key in your metadata, your peers may start using it but no= t all of them will switch at the same time. So in this case, you MU= ST configure both the old and new credentials into the SP so that = either key can be available for decryption.
It's likely the case that both of these scenarios apply; often, a single= credential is used for both signing and encryption and the migration is fr= om one credential for both to another for both.
Therefore, combining these issues, if you want to perform rollover of a = single keypair for both signing and encryption, you can follow these steps:=
use=3D"encryption"
).As an example, if you start here:
<Cred= entialResolver type=3D"File" key=3D"sp-key.pem" certificate=3D"sp-cert.pem"= />
Then the configuration after step 1 might be:
<Cred= entialResolver type=3D"Chaining"> <CredentialResolver type=3D"File" key=3D"new-key.pem" certificate= =3D"new-cert.pem" use=3D"encryption"/> <CredentialResolver type=3D"File" key=3D"sp-key.pem" certificate=3D= "sp-cert.pem"/> </CredentialResolver>
After step 3:
<Cred= entialResolver type=3D"Chaining"> <CredentialResolver type=3D"File" key=3D"new-key.pem" certificate= =3D"new-cert.pem"/> <CredentialResolver type=3D"File" key=3D"sp-key.pem" certificate=3D= "sp-cert.pem" use=3D"encryption"/> </CredentialResolver>
And after step 5:
<Cred= entialResolver type=3D"File" key=3D"new-key.pem" certificate=3D"new-cert.pe= m"/>
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 k=
eys has been encrypted on disk. You may need to supply a passwor=
d
attribute in your elements to load the key. In all cases C=
HECK YOUR LOGS any time you are manipulating keys. You MUS=
T ensure that all keys are loading correctly and that no errors ar=
e being logged during normal use.
The above process is suitable for cases in which the metadata's &l=
t;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-Shib=
boleth implementations.
Ultimately, the chosen process depends on how much control you have over= your metadata. In many scenarios, the metadata is controlled by a 3rd part= y (such as a federation) so the SP operator's choices are often limited.
The most complex (and ill-advised) case is if you're trying to selective=
ly apply different keys or certificates when interacting with different rel=
ying parties. The primary advice on this is "don't". Unfortunately, this is=
n't always possible, as some federations insist on imposing PKI-based const=
raints on their members. To accomodate this, the SP includes a mechanism fo=
r attaching "names" to credentials and then referencing the credentials in =
a <RelyingParty>
elemen=
t.
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 w= ill typically do the following:
<RelyingParty>
elements in the appro=
priate spot with a keyName
property that matches the "CN" from=
the desired credential's certificate subject (or that matches a subjectAlt=
Name).<Appl= icationDefaults ...> ... <Errors .../> <RelyingParty Name=3D"https://idp.example.org/idp/shibboleth" keyNam= e=3D"trusted.example.org"/> ... <CredentialResolver type=3D"Chaining"> <CredentialResolver type=3D"File" key=3D"sp-key.pem" certificate= =3D"sp-cert.pem"/> <CredentialResolver type=3D"File" key=3D"trusted-key.pem" certif= icate=3D"trusted-cert.pem"/> </CredentialResolver> </ApplicationDefaults>
If you find that each candidate credential shares essentially the same c=
ertificate subject information, then you can use a locally-chosen name in y=
our <RelyingParty>
element and add the same value to a <=
code>keyName attribute or <Name>
element in the <=
a href=3D"/wiki/spaces/SHIB2/pages/2577072312/NativeSPCredentialResolver" d=
ata-linked-resource-id=3D"2577072312" data-linked-resource-version=3D"24" d=
ata-linked-resource-type=3D"page"><CredentialResolver>
=
a>.
<Appl= icationDefaults ...> ... <Errors .../> <RelyingParty Name=3D"https://idp.example.org/idp/shibboleth" keyNam= e=3D"Special"/> ... <CredentialResolver type=3D"Chaining"> <CredentialResolver type=3D"File" key=3D"sp-key.pem" certificate= =3D"sp-cert.pem"/> <CredentialResolver type=3D"File" key=3D"trusted-key.pem" certif= icate=3D"trusted-cert.pem" keyName=3D"Special"/> </CredentialResolver> </ApplicationDefaults>