docs: make the jwt-auth and auth examples valid configs

[ndreno]

Summary

Copying an auth example from the docs mostly didn't work:

• 9 jwt-auth examples used keys the schema has never had (required, scopes, header, scheme, secret, public_key), so they fail compilation with E1023.
• 7 more set only issuer. jwt-auth verifies every token against public_key_jwk, so without one they reject every request with a 401.
• The jwt-auth guide itself said signature validation "is not yet implemented" and told readers to set skip_signature_validation: true "in production". The compiled plugin ignores that flag. The guide also listed HS256, which is rejected.
• Three more examples were broken the same way: an oidc-auth config with issuer/required instead of issuer_url, and two oauth2-auth configs missing required keys.

Changes

• The jwt-auth guide and the extensions reference show a working jwt-auth config with public_key_jwk. They cover which algorithms each key type verifies, the alg/use binding, that skip_signature_validation is test-only, that jwks_url/public_key_pem are accepted but unused, and a pointer to oidc-auth for JWKS.

• Examples whose point is "this operation needs auth" now use oidc-auth, which is what most deployments run:

  • issuer_url and audience;
  • required_scopes where the example meant scopes (scopes: ["admin:read"] becomes required_scopes: "admin:read");
  • allow_query_token on the WebSocket route, since browsers can't set headers there.

  This covers spec-configuration (operation, complete and AsyncAPI examples), extensions, dispatchers (WebSocket and S3), the middlewares index, authorization (cel, OPA) and the AI gateway guide.

• Operation-level examples get a security requirement, as E1057 demands. The complete example declares bearerAuth under components.securitySchemes, and the guide now has one sentence explaining E1057.

• Secrets guide: the file:// examples use real secret fields: oauth2-auth's client_secret and s3's secret_access_key. jwt-auth has no secret field, and its key is a JSON object, not a string a secret reference can hold.

Testing

I parsed every YAML block in docs/ and checked each auth and s3 config against its plugin's config-schema.json: required keys, unknown keys under closed objects, and value types. A jwt-auth config without public_key_jwk also counts as a failure.

• 41 configs checked, all valid.
• Not counted: the S3 config overview in the extensions reference, which lists types instead of values; and two name-only jwt-auth mentions in middleware-order illustrations, whose neighbors have no config either.
• oidc-auth writes context:auth.sub and x-auth-claims like jwt-auth does, so the rate-limit partition and OPA claims examples still hold.

Docs only, no code change.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• deep-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: barbacane-dev/barbacane/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 5010e4d1-6ba1-44dd-82a5-e5ab32620b3e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nicorp-pr-reviewer]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Invalid JWT Config Example The jwt-auth example in the documentation previously used invalid configuration keys such as required, scopes, header, scheme, secret, and public_key. These keys are not supported by the schema, causing compilation errors. The updated example now correctly uses public_key_jwk to define the verification key, which is required for token validation. issuer: "https://auth.example.com" # Optional: validate iss claim audience: "my-api" # Optional: validate aud claim groups_claim: "roles" # Optional: claim name for consumer groups public_key_jwk: # Key that verifies the signature kty: RSA alg: RS256 n: "0vx7agoebGcQSuu..." # base64url modulus e: AQAB Every token must carry a valid signature under public_key_jwk: without the key, tokens are rejected with 401 at the signature step. RSA keys verify RS256, RS384 and RS512; EC keys (crv, x, y) verify ES256 and ES384. HS256/HS384/HS512 and none are rejected. When the key sets alg or use, the token must match them. </details> <details><summary><a href='https://github.com/barbacane-dev/barbacane/pull/248/files#diff-3e4c07ceafe1f459ab51d733ec7f9b2f810f0d78c991326986510b714437e3cfR24-R29'><strong>Missing Signature Validation Key</strong></a> The previous `jwt-auth` example did not include a `public_key_jwk` configuration, which is necessary for signature validation. Without this key, all tokens would be rejected with a 401 error. The updated documentation now includes the required `public_key_jwk` to ensure valid token verification. </summary> ```markdown public_key_jwk: # Key that verifies the signature kty: RSA alg: RS256 n: "0vx7agoebGcQSuu..." # base64url modulus e: AQAB </details> <details><summary><a href='https://github.com/barbacane-dev/barbacane/pull/248/files#diff-8ee01ba8080c80b4c6bb46dcc9a0ff6d21034300debed08e5093f365c462f20aR168-R175'><strong>Incorrect Security Scheme Usage</strong></a> The operation-level examples previously used `jwt-auth` with `required: true` and `scopes`, which are not valid for the `jwt-auth` middleware. These configurations have been updated to use `oidc-auth` with proper `issuer_url`, `audience`, and `required_scopes` to align with the correct authentication flow. </summary> ```markdown security: - bearerAuth: [] x-barbacane-middlewares: - name: oidc-auth config: issuer_url: "https://auth.example.com" audience: "my-api" required_scopes: "admin:read"