From 23dff40aa2865a52c37f32faae270fa71e8700f8 Mon Sep 17 00:00:00 2001 From: Ryan Hanchett Date: Tue, 7 May 2024 10:59:31 -0700 Subject: [PATCH] docs: expand on jwks docs Signed-off-by: Ryan Hanchett --- docs/auth/service-to-service-auth.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/auth/service-to-service-auth.md b/docs/auth/service-to-service-auth.md index b9cc6151af..9ecd39ba8f 100644 --- a/docs/auth/service-to-service-auth.md +++ b/docs/auth/service-to-service-auth.md @@ -83,9 +83,9 @@ Authorization: Bearer eZv5o+fW3KnR3kVabMW4ZcDNLPl8nmMW ## JWKS Token Auth -This access method allows for external caller token authentication using configured JWKS. -This is useful for callers that are authenticating to your instance of Backstage with -third-party tools, such as Auth0. +This access method allows for external caller token authentication using configured +JSON Web Key Sets (JWKS). This is useful for callers that are authenticating to our +instance of Backstage with third-party tools, such as Auth0. You can configure this access method by adding one or more entries of type `jwks` to the `backend.auth.externalAccess` app-config key: @@ -110,8 +110,22 @@ backend: - https://example.com ``` +The URI should point at an unauthenticated endpoint that returns the JWKS. + +Issuers specifies the issuer(s) of the JWT that the authenticating app will accept. +Passed JWTs must have an `iss` claim which matches one of the specified issuers. + +Algorithms specifies the algorithm(s) that are used to verify the JWT. The passed JWTs +must have been signed using one of the listed algorithms. + +Audiences speficies the intended audience(s) of the JWT. The passed JWTs must have an "aud" +claim that matches one of the audiences specified, or have no audience specified. + +For additional details regarding the JWKS configuration, please consult your authentication +provider's documentation. + The subject returned from the token verification will become part of the -credentials object that the request recipients get. +credentials object that the request recipient plugins get. ## Legacy Tokens