{"type":"doc","content":[{"type":"paragraph","content":[{"text":"There are a few typical reasons for supplying the SP with multiple keypairs, or \"credentials\", to use for authentication and encryption:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"separating signing/TLS and encryption keys","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"key \"rollover\"","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"federation or partner-dictated requirements to use particular certificates","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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\" ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"},{"type":"link","attrs":{"__confluenceMetadata":{"isRenamedTitle":true,"linkType":"page","contentTitle":"CredentialResolver","versionAtSave":"6"},"href":"/wiki/spaces/SP3/pages/2065334414"}}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"eccf2036-b5b1-4c8f-9e7a-792eb93b7aec"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}}}},{"type":"heading","attrs":{"level":3},"content":[{"text":"Separate Signing and Encryption Keys","type":"text"}]},{"type":"paragraph","content":[{"text":"This is the simplest case (but also not all that common until recently), and is handled by labeling the individual resolvers in the chain with a ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":" property, typically of \"signing\" or \"encryption\".","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"For this use case, no additional labeling or configuration should be necessary to get the right key selected.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Key Rollover","type":"text"}]},{"type":"paragraph","content":[{"text":"Typically with rolling over keys or certificates you have two separate concerns: migrating your signing/authentication keys and your encryption keys. On the authentication side, the solution is to publish the new key/certificate in your metadata and wait for that to propagate before switching your 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 topic's goal).","type":"text"}]},{"type":"paragraph","content":[{"text":"On the other hand, with encryption you have the opposite problem. Once you publish a new key in your metadata, your peers may start using it but not all of them will switch at the same time. So in this case, you ","type":"text"},{"text":"MUST","type":"text","marks":[{"type":"strong"}]},{"text":" configure both the old and new credentials into the SP so that either key can be available for decryption.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 from one credential for both to another for both.","type":"text"}]},{"type":"paragraph","content":[{"text":"Therefore, combining these issues, if you want to perform rollover of a single keypair for both signing and encryption, you can follow these steps:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add a second private key to your SP configuration explicitly as a decryption key (","type":"text"},{"text":"use=\"encryption\"","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Publish the corresponding public key in your metadata and wait for propagation.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Switch the encryption usage constraint in the SP configuration from the new key to the old key.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove the old public key from the metadata and wait for propagation.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove the old private key from your SP configuration.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"As an example, if you start here:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":"Then the configuration after step 1 might be:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"After step 3:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"And after step 5:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"password","type":"text","marks":[{"type":"code"}]},{"text":" attribute in your elements to load the key. In all cases ","type":"text"},{"text":"CHECK YOUR LOGS","type":"text","marks":[{"type":"strong"}]},{"text":" any time you are manipulating keys. You ","type":"text"},{"text":"MUST","type":"text","marks":[{"type":"strong"}]},{"text":" ensure that all keys are loading correctly and that no errors are being logged during normal use.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The above process is suitable for cases in which the metadata's ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements do not carry a ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":" XML attribute and there is no opportunity to introduce such a ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":"attribute into metadata. Other approaches may be more suitable for non-Shibboleth implementations.","type":"text"}]},{"type":"paragraph","content":[{"text":"Ultimately, the chosen process depends on how much control you have over your metadata. In many scenarios, the metadata is controlled by a 3rd party (such as a federation) so the SP operator's choices are often limited.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Multiple Certificate Scenarios","type":"text"}]},{"type":"paragraph","content":[{"text":"The most complex (and ill-advised) case is if you're trying to selectively apply different keys or certificates when interacting with different relying parties. The primary advice on this is \"don't\". Unfortunately, this isn't always possible, as some federations insist on imposing PKI-based constraints on their members. To accomodate this, the SP includes a mechanism for attaching \"names\" to credentials and then referencing the credentials in a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"},{"type":"link","attrs":{"__confluenceMetadata":{"isRenamedTitle":true,"linkType":"page","contentTitle":"RelyingParty","versionAtSave":"12"},"href":"/wiki/spaces/SP3/pages/2065334363"}}]},{"text":" element.","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Configure both credentials together in a chain.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add one or more ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" elements in the appropriate spot with a ","type":"text"},{"text":"keyName","type":"text","marks":[{"type":"code"}]},{"text":" property that matches the \"CN\" from the desired credential's certificate subject (or that matches a subjectAltName).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example using certificate subject as keyName","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n ...\n \n \n ...\n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"If you find that each candidate credential shares essentially the same certificate subject information, then you can use a locally-chosen name in your ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element and add the same value to a ","type":"text"},{"text":"keyName","type":"text","marks":[{"type":"code"}]},{"text":" attribute or ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element in the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"},{"type":"link","attrs":{"__confluenceMetadata":{"isRenamedTitle":true,"linkType":"page","contentTitle":"CredentialResolver","versionAtSave":"6"},"href":"/wiki/spaces/SP3/pages/2065334414"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Example using locally chosen keyName","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n ...\n \n \n ...\n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}