Document signing key rotation impact for SAML/WS-Fed IdP (IPS-6615)

main/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests.mdx

@@ -238,6 +238,46 @@ exports.onExecutePostLogin = async (event, api) => {
 
 To learn how to turn the private key and certificate files into strings that you can use in a rule, see [Work with Certificates and Keys and Strings](/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings).
 
+#### Rotate the tenant signing key
+
+<Warning>
+* Auth0 signs SAML assertions and responses with your tenant's signing key, rotating the key will affect all service providers that validate signatures against the certificate it trusts.
+* Service provider that do not trust the new certificate will reject Auth0's signed responses, and its users will not be able to log in.
+</Warning>
+
+To learn about rotating signing keys, read [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys). 
+
+To configure SAML service providers to seamlessly trust the `next` certificate **before** you rotate, depends on whether each service provider can hold more than one identity provider signing certificate at a time.
+
+Before rotating, get the **NEXT IN QUEUE** certificate:
+
+1. Go to [Dashboard > Settings > Signing Keys](https://manage.auth0.com/#/tenant/signing_keys) and scroll to **List of Valid Keys**.
+2. Locate the **NEXT IN QUEUE** valid key.
+3.  Select **Download Signing Certificate** from the ellipsis menu (...).
+
+You can also make a `GET` request to the Management API [Get all Application Signing Keys](/docs/api/management/v2/keys/get-signing-keys) endpoint, the response includes a `"next": true` valid key `"cert"`. 
+
+**Service providers that support multiple signing certificates**
+
+To enable **zero downtime**, many service providers are able to accept several IdP signing certificates. Add the `next` valid certificate alongside the current one so both are trusted simultaneously, when Auth0 starts using it.
+
+1. Upload the next certificate to the service provider as an *additional* trusted signing certificate. Do not remove or replace the current certificate yet.
+2. Confirm the service provider lists both the current and the next certificate as trusted.
+3. Once every service provider trusts both certificates, rotate the key. Remove the old certificate from your service providers only after you confirm that logins succeed.
+
+**Service providers that support only a single signing certificate**
+
+Some service providers accept only one identity provider signing certificate at a time. You need to coordinate the signing key rotation with those service providers during the same maintenance window. 
+
+1. Coordinate with the service provider to schedule the change during a low-traffic or maintenance window.
+2. Rotate the signing key in Auth0 and replace the service provider's trusted certificate with the next certificate **as close together as possible**. Between these two actions, logins through that service provider will fail signature validation.
+3. Once the service provider has the new certificate, verify that logins succeed.
+
+Consult with your service provider, if they are able to support multiple or single signing certificates to plan accordingly. 
+
+
+
+
 ### Receive signed SAML authentication requests
 
 If Auth0 is the SAML identity provider, it can receive requests signed with the service provider's private key. Auth0 uses the public key/certificate to validate the signature.

main/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys.mdx

@@ -22,6 +22,8 @@ To allow you time to update your application with the new signing key, all token
 
 </Warning>
 
+Before rotating, review the [Key rotation impact](#key-rotation-impact) to understand how the change affects your applications, APIs, and identity provider integrations.
+
 You can rotate your tenant's application signing key using the <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip tip="Management API: A product to allow customers to perform administrative tasks." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>.
 
 ## Use the Dashboard
@@ -176,9 +178,9 @@ puts response.read_body
 
 Most middleware and API gateways leverage the JSON web key set (JWKS) endpoint to retrieve the current and future signing keys at a certain interval. If your middleware and/or API gateways **do not** support this endpoint and require you to manually configure a `*.cer` file, you will need to coordinate the signing key rotation in Auth0 with the reconfiguration of your middleware and gateways.
 
-### Regular web applications
+### Auth0 as a SAML or WS-Fed IdP
 
-When rotating the signing key in Auth0, you will need to coordinate the reconfiguration of your applications which leverage <Tooltip tip="Web Service Federation (WS-Fed): Protocol for managing user identities across domains." cta="View Glossary" href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> or <Tooltip tip="Web Service Federation (WS-Fed): Protocol for managing user identities across domains." cta="View Glossary" href="/docs/glossary?term=SAML">SAML</Tooltip>. This typically happens when you upload the new public certificate or reconfigure the application by entering the WS-Fed/SAML metadata URL. This will change the JWKS key, which is used by applications to validate tokens, make sure your implementation does not assume JWKS keys don’t change.
+When Auth0 acts as a <Tooltip tip="Security Assertion Markup Language (SAML): Standardized protocol allowing two parties to exchange authentication information without a password." cta="View Glossary" href="/docs/glossary?term=SAML">SAML</Tooltip> or <Tooltip tip="Web Service Federation (WS-Fed): Protocol for managing user identities across domains." cta="View Glossary" href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> identity provider, rotating the signing key changes the key used to sign responses. You must update each of your service providers with the new certificate so it can keep validating Auth0's signed responses. To update your service providers to trust the next certificate before rotating the signing keys, read [Rotate the tenant signing key](/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests#rotate-the-tenant-signing-key).
 
 ## Learn more