Merge pull request #24681 from ryan-hanchett/feat/add-jwks-access-type-1

feat: add jwks access type to external token handler

docs/auth/service-to-service-auth.md

@@ -80,6 +80,55 @@ header:
 Authorization: Bearer eZv5o+fW3KnR3kVabMW4ZcDNLPl8nmMW
 ```
 
+## JWKS Token Auth
+
+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:
+
+```yaml title="in e.g. app-config.production.yaml"
+backend:
+  auth:
+    externalAccess:
+      - type: jwks
+        options:
+          url: https://example.com/.well-known/jwks.json
+          issuers:
+            - https://example.com
+          algorithms:
+            - RS256
+          audiences:
+            - example
+          subjectPrefix: custom-prefix
+      - type: jwks
+        options:
+          url: https://another-example.com/.well-known/jwks.json
+          issuers:
+            - https://example.com
+```
+
+The URL 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 specify 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 recipient plugins get. All subjects will have the prefix
+`external:`, but you can also provide a custom subjectPrefix which will get appended before the
+subject returned from your JWKS service (ex. `external:custom-prefix:sub`).
+
 ## Legacy Tokens
 
 Plugins and backends that are _not_ on the new backend system use a legacy token