From 039cb0981565fb4d44c89e418916fa77af61b048 Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Tue, 25 Nov 2025 15:43:01 +0000 Subject: [PATCH 1/3] Add a little bit of explanation to the documentation about keys --- docs/reference/configuration.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index f614791dd..ac70432cc 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -196,7 +196,7 @@ secrets: # Signing keys keys: - # It needs at least an RSA key to work properly + # At least one RSA key must be configured - key_file: keys/rsa_key - kid: "iv1aShae" key: | @@ -238,9 +238,21 @@ The following key formats are supported: - PKCS#8 PEM or DER-encoded RSA or ECDSA private key, encrypted or not - SEC1 PEM or DER-encoded ECDSA private key +The signing keys are used for signing ID Tokens (as returned in the [Token Endpoint] +at `/oauth2/token`) and for signing the response of the [UserInfo Endpoint] at +`/oauth2/userinfo` if the client requests a signed response. + +At a minimum, an RSA key must be configured in order to be compliant with the +[OpenID Connect Core specification][oidc-core-rs256] which specifies the RS256 algorithm +as mandatory to implement by servers for interoperability reasons. + The keys can be given as a directory path via `secrets.keys_dir` or, alternatively, as an inline configuration list via `secrets.keys`. +[Token Endpoint]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint +[UserInfo Endpoint]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo +[oidc-core-rs256]: https://openid.net/specs/openid-connect-core-1_0.html#ServerMTI + #### `secrets.keys_dir` Path to the directory containing MAS signing key files. From f662b0b13227ede3803e670b9e1577517d423651 Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Tue, 25 Nov 2025 16:59:21 +0000 Subject: [PATCH 2/3] drive-by: Singing -> Signing --- docs/reference/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index ac70432cc..5b40e8370 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -222,7 +222,7 @@ The secret is not updated when the content of the file changes. > Changing the encryption secret afterwards will lead to a loss of all encrypted > information in the database. -### Singing Keys +### Signing Keys The service can use a number of key types for signing. The following key types are supported: From 262e235c755ac4317840900b386b17a06eef9c6a Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Tue, 2 Dec 2025 12:22:33 +0000 Subject: [PATCH 3/3] Convert use case list to bullet points and note the niche private_key_jwt method --- docs/reference/configuration.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 5b40e8370..2f2956451 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -238,9 +238,12 @@ The following key formats are supported: - PKCS#8 PEM or DER-encoded RSA or ECDSA private key, encrypted or not - SEC1 PEM or DER-encoded ECDSA private key -The signing keys are used for signing ID Tokens (as returned in the [Token Endpoint] -at `/oauth2/token`) and for signing the response of the [UserInfo Endpoint] at -`/oauth2/userinfo` if the client requests a signed response. +The signing keys are used for: +- signing ID Tokens (as returned in the [Token Endpoint] at `/oauth2/token`); +- signing the response of the [UserInfo Endpoint] at `/oauth2/userinfo` if the + client requests a signed response; +- (niche) signing a JWT for authenticating to an upstream OAuth provider when + the `private_key_jwt` client auth method is configured. At a minimum, an RSA key must be configured in order to be compliant with the [OpenID Connect Core specification][oidc-core-rs256] which specifies the RS256 algorithm