diff --git a/docs/router/authentication-and-authorization.mdx b/docs/router/authentication-and-authorization.mdx index b472bf56..cd205f00 100644 --- a/docs/router/authentication-and-authorization.mdx +++ b/docs/router/authentication-and-authorization.mdx @@ -56,6 +56,54 @@ The router configuration facilitates the setup of multiple JWKS (JSON Web Key Se For more information on the attributes, visit the auth configuration parameter section page [here](/router/configuration#authentication). +### Disabling Authentication for Introspection Operations + +Cosmo Router supports bypassing authentication for introspection queries. + +This is useful, for example, when you want to configure client tooling from within a secured environment without requiring authentication tokens. +Instead of having to disable authentication altogether, this feature allows you to keep the configuration as close to production as possible while still using introspection queries easily. +Additionally, you can define a dedicated secret to authenticate introspection queries. + + +This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment. +By default, introspection queries are not excluded from authentication. + + +To enable this feature, add the following section to your router configuration: + + + ```yaml config.yaml + authentication: + ignore_introspection: true # default is false + # other auth settings here + ``` + + +Now, when you send an introspection query, you won't need to provide an authentication token. + +```bash +curl -X POST http://localhost:3002/graphql \ + --header "Content-Type: application/json" \ + --data '{"query": "{ __schema { types { name } } }"}' +``` + +Optionally, you can set a dedicated secret for introspection queries. + + + ```yaml config.yaml + introspection: + secret: 'dedicated_secret_for_introspection' + ``` + + +When a secret is set, you must include it in the `Authorization` header (without a Bearer prefix). + +```bash +curl -X POST http://localhost:3002/graphql \ + --header "Content-Type: application/json" \ + --header "Authorization: dedicated_secret_for_introspection" \ + --data '{"query": "{ __schema { types { name } } }"}' +``` ## Old Router configuration (\< 0.168.1) diff --git a/docs/router/configuration.mdx b/docs/router/configuration.mdx index cb5cb175..9608f5be 100644 --- a/docs/router/configuration.mdx +++ b/docs/router/configuration.mdx @@ -134,7 +134,7 @@ The following sections describe each configuration in detail with all available | CONTROLPLANE_URL | controlplane_url | | The controlplane url. Not required when a static execution config is provided. | https://cosmo-cp.wundergraph.com | | PLAYGROUND_ENABLED | playground_enabled | | Enables the GraphQL playground on (`$LISTEN_ADDR/`) | true | | PLAYGROUND_PATH | playground_path | | The path where the playground is served | "/" | -| INTROSPECTION_ENABLED | introspection_enabled | | Enables the GraphQL introspection | true | +| INTROSPECTION_ENABLED | introspection_enabled | | Enables the GraphQL introspection (deprecated, use `introspection.enabled` instead) | true | | QUERY_PLANS_ENABLED | query_plans_enabled | | The Router can return Query plans as part of the response, which might be useful to understand the execution. | true | | LOG_LEVEL | log_level | | The log level to use. Allowed levels are `"debug"`, `"info"`, `"warn"`, `"error"`, `"panic"`, `"fatal"`. | info | | JSON_LOG | json_log | | Render the log output in JSON format (true) or human readable (false) | true | @@ -173,6 +173,11 @@ liveness_check_path: "/health/live" router_config_path: "" ``` + + `introspection_enabled` is a deprecated flag. + Please use `introspection.enabled` instead. + + ## Config watcher hot reloading The router is capable of reloading itself using an updated config without a full process restart. You can trigger a reload in one of two ways: @@ -304,6 +309,25 @@ graph: token: "" ``` +## Introspection + +Overall configuration for managing introspection queries on this Router. + +| Environment Variable | YAML | Required | Description | Default Value | +| --------------------- | -------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| INTROSPECTION_ENABLED | enabled | | Enable or disable introspection queries | true | +| INTROSPECTION_SECRET | secret | | Optional, dedicated secret used for instrospection authentication. Only used when `authentication.ignore_introspection` is set to `true`. | | + +### Example YAML config: + +```yaml config.yaml +version: "1" + +introspection: + enabled: true + secret: "dedicated_secret_for_introspection" +``` + ## MCP (Model Context Protocol) The Model Context Protocol (MCP) server allows AI models to discover and interact with your GraphQL API in a secure way. @@ -1506,6 +1530,21 @@ authentication: name: X-Authorization ``` +### Bypass Introspection Authentication + +This is useful when you want to bypass authentication for introspection queries, +for example let certain tools introspect the schema without requiring authentication token. + + + This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment. + By default, introspection queries are not excluded from authentication. + Also consider setting `introspection.secret` for a static secret dedicated to introspection queries. + + +| Environment Variable | YAML | Required | Description | Default Value | +| -------------------- | -------------------- | ---------------------- | ----------------------------------- | ---------------- | +| | ignore_introspection | | Bypass introspection authentication | false | + ### Old Authentication Config (Router Version \< 0.XXX.X) ### Provider diff --git a/docs/router/security/hardening-guide.mdx b/docs/router/security/hardening-guide.mdx index 3cad2f47..eca7b0ab 100644 --- a/docs/router/security/hardening-guide.mdx +++ b/docs/router/security/hardening-guide.mdx @@ -12,7 +12,8 @@ By default introspection is enabled. The following configuration should be appli ```yaml router.yaml - introspection_enabled: false + introspection: + enabled: false ```