From d7310ed4ff2cb4642b37114d4368c3fd0f388e3b Mon Sep 17 00:00:00 2001 From: Dominik Korittki <23359034+dkorittki@users.noreply.github.com> Date: Mon, 8 Sep 2025 17:21:41 +0200 Subject: [PATCH 1/4] feat: add docs for introspection auth bypass --- .../authentication-and-authorization.mdx | 49 +++++++++++++++++++ docs/router/security/hardening-guide.mdx | 3 +- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/router/authentication-and-authorization.mdx b/docs/router/authentication-and-authorization.mdx index 495c11c3..bf08ffbc 100644 --- a/docs/router/authentication-and-authorization.mdx +++ b/docs/router/authentication-and-authorization.mdx @@ -51,6 +51,55 @@ 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 valid 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. + + +This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment. +It is disabled by default. + + +To enable this feature, add the following configuration to your router configuration: + + + ```yaml config.yaml + introspection: + enabled: true # Introspection is enabled by default (explicitly shown here) + skip_authentication: true # Bypass authentication for introspection queries (default: false) + ``` + + +Now when you make an introspection query, you will not 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 token for introspection queries. + + + ```yaml config.yaml + introspection: + enabled: true + skip_authentication: true + token: "dedicated_secret_for_introspection" # Optional, set a dedicated secret for introspection queries + ``` + + +With the secret set, you will need to provide it via 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/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 ``` From 701ea1888dd48d5c920d4b8dae12eb5204f19146 Mon Sep 17 00:00:00 2001 From: Dominik Korittki <23359034+dkorittki@users.noreply.github.com> Date: Tue, 9 Sep 2025 15:18:30 +0200 Subject: [PATCH 2/4] fix: use better wording to describe default behaviour --- docs/router/authentication-and-authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/router/authentication-and-authorization.mdx b/docs/router/authentication-and-authorization.mdx index bf08ffbc..3bd0bdf1 100644 --- a/docs/router/authentication-and-authorization.mdx +++ b/docs/router/authentication-and-authorization.mdx @@ -60,7 +60,7 @@ Instead of having to disable authentication altogether, this feature allows you This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment. -It is disabled by default. +By default introspection queries are not excluded from authentication, if authentication is enabled in the router. To enable this feature, add the following configuration to your router configuration: From f78c2c57b2bfcd7d4142cab19c0ef88549534204 Mon Sep 17 00:00:00 2001 From: Dominik Korittki <23359034+dkorittki@users.noreply.github.com> Date: Tue, 28 Oct 2025 15:09:27 +0100 Subject: [PATCH 3/4] chore: update docs to latest feature changes + improve wording --- .../authentication-and-authorization.mdx | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/router/authentication-and-authorization.mdx b/docs/router/authentication-and-authorization.mdx index 046ed1e1..cd205f00 100644 --- a/docs/router/authentication-and-authorization.mdx +++ b/docs/router/authentication-and-authorization.mdx @@ -60,25 +60,26 @@ For more information on the attributes, visit the auth configuration parameter s 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 valid authentication tokens. +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, if authentication is enabled in the router. +By default, introspection queries are not excluded from authentication. -To enable this feature, add the following configuration to your router configuration: +To enable this feature, add the following section to your router configuration: ```yaml config.yaml - introspection: - enabled: true # Introspection is enabled by default (explicitly shown here) - skip_authentication: true # Bypass authentication for introspection queries (default: false) + authentication: + ignore_introspection: true # default is false + # other auth settings here ``` -Now when you make an introspection query, you will not need to provide an authentication token. +Now, when you send an introspection query, you won't need to provide an authentication token. ```bash curl -X POST http://localhost:3002/graphql \ @@ -86,18 +87,16 @@ curl -X POST http://localhost:3002/graphql \ --data '{"query": "{ __schema { types { name } } }"}' ``` -Optionally, you can set a dedicated token for introspection queries. +Optionally, you can set a dedicated secret for introspection queries. ```yaml config.yaml introspection: - enabled: true - skip_authentication: true - token: "dedicated_secret_for_introspection" # Optional, set a dedicated secret for introspection queries + secret: 'dedicated_secret_for_introspection' ``` -With the secret set, you will need to provide it via the `Authorization` header, without a Bearer prefix. +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 \ From 3e6240022f615ab2e38cd8d5d1ebd267303e27ae Mon Sep 17 00:00:00 2001 From: Dominik Korittki <23359034+dkorittki@users.noreply.github.com> Date: Tue, 28 Oct 2025 17:42:18 +0100 Subject: [PATCH 4/4] chore: add new config settings to global config --- docs/router/configuration.mdx | 41 ++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) 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