Skip to content

docs: clarify SAML signing requirements and add section on OIDC and SAML key sharing #1213

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maartenba merged 2 commits into from
Sep 4, 2026
Merged

docs: clarify SAML signing requirements and add section on OIDC and SAML key sharing #1213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abb8cfc
docs: clarify SAML signing requirements and add section on OIDC and S…
maartenba Sep 2, 2026
14d08c0
Apply batched suggestions from code review
maartenba Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions astro/src/content/docs/identityserver/fundamentals/key-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,33 @@ an `AllowedTokenSigningAlgorithm` property to override the default on a per
resource and client basis.
:::

### Using The Same Signing Keys For OIDC And SAML

When SAML is enabled, IdentityServer uses the same signing credentials for OIDC tokens and SAML messages. This gives both
protocols one rotation schedule and one key store. The active key signs new JWTs and SAML messages, while current and
recently rotated public keys are published through the OIDC JWKS endpoint and SAML IdP metadata during rollover.

SAML metadata requires X.509 certificates. Automatic Key Management creates RSA keys by default, and the SAML component
automatically wraps those managed RSA keys in self-signed X.509 certificates that contain the RSA public key. You do not
need to set `UseX509Certificate` just to enable SAML. These generated certificates are containers for signing-key
material, not PKI identity certificates. Service Providers should establish trust from the IdP metadata and refresh it
during rotation rather than rely on the certificate subject or validity dates.

If you use Static Key Management, configure an X.509 signing certificate with a private key. SAML cannot automatically
wrap a manually registered raw RSA key, including one registered by `AddDeveloperSigningCredential()`.

:::caution
The default SAML signing service supports RSA signing credentials. `UseX509Certificate` is not supported for EC keys.
Use a custom [`ISamlSigningService`](/identityserver/saml/extensibility.md#isamlsigningservice) if SAML needs a different
certificate, an independent rotation schedule, or integration with an external key system.
:::

`PropagationTime` determines how long a new managed key is published before IdentityServer starts using it. Set this
long enough for every Service Provider to refresh the IdP metadata. `RetentionDuration` keeps the previous certificate in
metadata while Service Providers may still be validating SAML messages signed with the previous key and previously
issued OIDC tokens remain valid. Service Providers that use a statically configured certificate must be updated as part
of every rotation.

## Static Key Management

Instead of using [Automatic Key Management](#automatic-key-management), IdentityServer's signing keys can be set
Expand Down
6 changes: 3 additions & 3 deletions astro/src/content/docs/identityserver/saml/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,9 @@ Available options:
The default is `SignAssertion` for backward compatibility with existing deployments and SPs that expect only the assertion to be signed. For new deployments, `SignResponse` is recommended because it signs the entire SAML response (including the assertion), providing integrity protection over the full message. See [`SamlSigningBehavior`](#samlsigningbehavior) for details on each option.

:::note
SAML signing requires an X509 certificate. When you use automatic key management or `AddDeveloperSigningCredential()` (which provide RSA keys without a certificate), IdentityServer automatically generates an X509 container that wraps your existing RSA key material. You do not need to create or provide a certificate manually.
SAML signing requires an X.509 certificate. When you use Automatic Key Management with RSA keys, IdentityServer automatically generates an X.509 container that wraps the managed key material. You do not need to create or provide a certificate manually. Manually registered raw RSA keys, including keys registered by `AddDeveloperSigningCredential()`, cannot be wrapped automatically; use an X.509 certificate with a private key instead.

See [Using The Same Signing Keys For OIDC And SAML](/identityserver/fundamentals/key-management.md#using-the-same-signing-keys-for-oidc-and-saml) for rotation, metadata refresh, and custom key requirements.
:::

* **`MaxRelayStateLength`**
Expand Down Expand Up @@ -435,5 +437,3 @@ Only enable IdP-initiated SSO after careful security considerations and only for
:::

For a working example, see the [SAML 2.0 IdP-Initiated sample](/identityserver/samples/saml.mdx).


Loading