docs: improve JWT configuration page

[hgiasac]

Description 📝

Many JWT configurations in Hasura v2 are no longer valid in Hasura DDN. This PR rewrites the JWT configuration page to improve the correctness.

Quick Links 🚀

https://fix-jwt-auth-configuration.v3-docs-eny.pages.dev/auth/jwt/jwt-configuration/

Assertion Tests 🤖

[hasura-bot]

@hgiasac Thanks for your PR! I've assigned @seanparkross to review it.

[hasura-bot]

DX: Assertion Testing

✅ Diff

The PR introduces a detailed, structured configuration example using YAML, which is in line with modern practices and tends to be easier for users to understand than JSON. Replacing 'stringified_json' with 'StringifiedJson' improves consistency in naming conventions. The splitting of claims_namespace and related fields into claimsConfig with namespace and locations adds clarity to the configuration structure. However, a minor point of feedback is to consistently use either singular or plural for 'claims' and 'namespace' across the documentation to avoid confusion.

✅ Integrated

The PR’s updated YAML configuration is consistent with the rest of the documentation and maintains the same level of detail and clarity seen in other sections. It introduces additional security measures by providing a defaults example for new required fields like audience and issuer, improving the overall usability of JWT configuration in the documentation. Also, the transition from loosely defined key types to specific fixed and jwkFromUrl key configurations simplifies the user's decision-making process and helps prevent potential misconfigurations. The integrated changes create a more straightforward, user-friendly guide that is beneficial for new and existing users.

[seanparkross]

@hgiasac So this section has changed to be about the AuthConfig definition rather than the JWT token definition. Do we not need a JWT payload definition also?

[hgiasac]

No. That JWT definition is a JSON string in v2 when configuring the HASURA_GRAPHQL_JWT_SECRET env variable. In Hasura DDN, JWT is just an auth mode of AuthConfig and the syntax is different from v2.

We can link the definition to the JWT section in AuthConfig reference instead.

[cloudflare-workers-and-pages]

Deploying ddn-docs with    Cloudflare Pages

Latest commit:	127d57c
Status:	⚡️  Build in progress...

View logs