From b2585b0006b5e55e157753e7fc439573fd5da70f Mon Sep 17 00:00:00 2001 From: Gerard Guillemas Martos Date: Tue, 20 Aug 2024 16:32:29 +0200 Subject: [PATCH] Clarify how JWKS works and where to learn more (#777) --- .../version-latest/surrealql/statements/define/access/jwt.mdx | 4 ++++ .../surrealql/statements/define/access/record.mdx | 2 ++ 2 files changed, 6 insertions(+) diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/jwt.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/jwt.mdx index f368cc73a..1abc8dab1 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/jwt.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/jwt.mdx @@ -99,6 +99,10 @@ iCTjhbIDEBHySSSc/pQ4ftHQmhToTlQeOdEy4LYiaEIgl1X+hzRH1hBYvWlNKe4EY1nMCKcjgt0= With JWKS, a set of JWK (JSON Web Key) objects will be dynamically fetched from a remote location and used to verify tokens following the [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517) specification. When defining a JWKS token verification method, its value should contain a valid URL that is reachable by SurrealDB and allowed by the configured network [capabilities](/docs/surrealdb/security/capabilities). This URL should point to a valid JWKS object (as described in [Section 5 of RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517#section-5)) in the form of a JSON document. This is the recommended method to integrate with authentication providers that support JWKS. Providers like [Google](https://developers.google.com/identity/openid-connect/openid-connect#discovery), [AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html#amazon-cognito-user-pools-using-tokens-manually-inspect), [Azure Active Directory](https://azure.github.io/azure-workload-identity/docs/installation/self-managed-clusters/oidc-issuer/jwks.html), [Auth0](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets), [Keycloak](https://documentation.cloud-iam.com/how-to-guides/configure-remote-jkws.html) or [OneLogin](https://developers.onelogin.com/authentication/tools/jwt) provide JWKS endpoints to verify tokens issued by their services. +:::note + Note: As the JWKS functionality requires establishing a network connection in order to download the JWKS object, you will require running the SurrealDB server with the network capability. For the strongest security, provide the specific hostname hosting the JWKS object when starting SurrealDB with --allow-net. For example: --allow-net example.com. +::: + The following example shows the definition of a token using a JWKS. ```surql diff --git a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/record.mdx b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/record.mdx index a91365cb3..001b3f3d7 100644 --- a/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/record.mdx +++ b/doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/record.mdx @@ -58,6 +58,8 @@ Since the origin of the claims in the JWT is verified, those claims can be used Bear in mind that table and field permissions only apply to [record users](/docs/surrealdb/security/authentication#record-users), which must use tokens that are verified by a `RECORD` access method. Access provided by namespace and database tokens defined in a `JWT` access method is equivalent to access from [system users](/docs/surrealdb/security/authentication#system-users), which is above fine-grained permissions. When application users will be the ones directly authenticating with JWT, defining a `RECORD` access method `WITH JWT` is most likely the right choice. +Reference [the JWT access method](/docs/surrealdb/surrealql/statements/define/access/jwt) documentation for additional information about how JWT tokens can be used in SurrealDB, including verification through [JWKS](/docs/surrealdb/surrealql/statements/define/access/jwt#json-web-key-set-jwks). + The following example shows how record access with a token can be used to grant authorization either by verifying that the `id` claim in the token (which is used to populate the [`$auth`](/docs/surrealdb/surrealql/parameters#auth) reserved parameter) matches the record that is being queried from the `user` table or if the `privileged` claim is set to `true` in the token: ```surql