JWT Authentication in the Apollo Router
⚠️ This is an Enterprise feature of the Apollo Router. It requires an organization with a GraphOS Enterprise plan.
If your organization doesn't currently have an Enterprise plan, you can test out this functionality by signing up for a free Enterprise trial.
The Apollo Router supports request authentication and key rotation via the JSON Web Token (JWT) and JSON Web Key (JWK) standards. This support is compatible with popular identity providers (IdPs) like Okta and Auth0.
By enabling JWT authentication, you can block malicious traffic at the edge of your graph instead of relying on header forwarding to propagate tokens to your subgraphs.
⚠️ Under all circumstances, your subgraphs should be accessible only via the router—not directly by clients. This is especially true if you're relying on JWT authentication in the router. Make sure to secure your subgraphs.
To use this feature:
- You must have an identity provider (IdP) or similar service that issues JWTs to authenticated clients using one of the signature algorithms supported by the jsonwebtoken Rust library (most popular signing algorithms are supported).
- You must have a GraphOS Enterprise plan and connect your router to GraphOS.
If you issue JWTs via a popular third-party IdP (Auth0, Okta, PingOne, etc.), adding JWT authentication to your router is comparatively straightforward. If you use your own custom IdP, advanced configuration is required.
How it works
These are the high-level steps of JWT-based authentication with the Apollo Router:
Whenever a client authenticates with your system, your IdP issues that client a valid JSON Web Token (JWT).
In its subsequent requests to your router, the authenticated client provides its JWT in a designated HTTP header.
Whenever your router receives a client request, it extracts the JWT from the designated header (if present).
- If no JWT is present, the request proceeds. You can reject requests with no accompanying JWT at a later phase (see below).
Your router validates the extracted JWT using a corresponding JSON Web Key (JWK).
- Your router obtains all of its known JWKs from URLs that you specify in its configuration file. Each URL provides its keys within a single JSON object called a JWK Set (or a JWKS).
- If validation fails, the router rejects the request. This can occur if the JWT is malformed, or if it's been expired for more than 60 seconds (this window accounts for synchronization issues).
The router extracts all claims from the validated JWT and includes them in the request's context, making them available to your router customizations, such as Rhai scripts.
Your customizations can handle the request differently depending on the details of the extracted claims, and/or you can propagate the claims to subgraphs to enable more granular access control.
- For examples, see below.
Turning it on
You enable JWT authentication for your router with the following steps:
Set configuration options for JWT authentication in your router's YAML config file, under the
authentication
key:router.yamlauthentication:router:jwt:jwks: # This key is required.- url: https://dev-zzp5enui.us.auth0.com/.well-known/jwks.jsonissuer: <optional name of issuer># These keys are optional. Default values are shown.header_name: Authorizationheader_value_prefix: BearerThese options are documented below.
Pass all of the following to the
router
executable on startup:- The path to the router's YAML configuration file (via the
--config
option) - The graph ref for the GraphOS variant your router should use (via the
APOLLO_GRAPH_REF
environment variable) - A graph API key that enables the router to authenticate with GraphOS to fetch its supergraph schema (via the
APOLLO_KEY
environment variable)
APOLLO_GRAPH_REF=docs-example-graph@main APOLLO_KEY="..." ./router --config router.yaml- The path to the router's YAML configuration file (via the
When the router starts up, it displays a log message that confirms which jwks
are in use:
2023-02-03T14:05:28.018932Z INFO JWT authentication using JWKSets from jwks=[{ url: "file:///router/jwks.json" }]
Configuration options
The following configuration options are supported:
Option | Description |
---|---|
| Required. A list of JWK Set (JWKS) configuration options:
|
| The name of the HTTP header that client requests will use to provide their JWT to the router. Must be a valid name for an HTTP header. The default value is |
| The string that will always precede the JWT in the header value corresponding to The default value is |
Working with JWT claims
After the Apollo Router validates a client request's JWT, it adds that token's claims to the request's context at this key: apollo_authentication::JWT::claims
- If no JWT is present for a client request, this context value is the empty tuple,
()
. - If a JWT is present but validation of the JWT fails, the router rejects the request.
If unauthenticated requests should be rejected, the router can be configured like this:
authorization:require_authentication: true
Claims are the individual details of a JWT's scope. They might include details like the ID of the associated user, any roles assigned to that user, and the JWT's expiration time. See the spec.
Because claims are added to the context, you can define custom logic for handling each request based on the details of its claims. You can define this logic within a Rhai script or external coprocessor at the supergraph service level (for more on these options, see Customizations for the Apollo Router).
Below are 2 example Rhai script customizations that demonstrate actions the router can perform based on a request's claims.
Example: Forwarding claims to subgraphs as headers
Below is an example Rhai script that forwards a JWT's claims to individual subgraphs via HTTP headers (one header for each claim). This enables each subgraph to define logic to handle (or potentially reject) incoming requests based on claim details. This function should be imported and run in your main.rhai
file.
This script should be run in the router's SubgraphService
, which executes before the router sends a subquery to an individual subgraph. Learn more about router services.
⚠️ Explicitly listing claims and always setting headers for them is strongly recommended to avoid possible security issues when forwarding headers to subgraphs.
Example: Forwarding claims to subgraphs as GraphQL extensions
Below is an example Rhai script that forwards a JWT's claims to individual subgraphs via GraphQL extension. This enables each subgraph to define logic to handle (or potentially reject) incoming requests based on claim details. This function should be imported and run in your main.rhai
file.
This script should be run in the router's SubgraphService
, which executes before the router sends a subquery to an individual subgraph. Learn more about router services.
Example: Throwing errors for invalid claims
Below is an example Rhai script that throws distinct errors for different invalid JWT claim details. This function should be imported and run in your main.rhai
file.
This script should be run in the router's SupergraphService
, which executes before the router begins generating the query plan for an operation. Learn more about router services.
Example main.rhai
In order to use the above Rhai examples, you must import them into your main.rhai
like this:
Claim augmentation via coprocessors
You may require information beyond what your JSON web tokens provide. For example, a token's claims may include user IDs, which you then use to look up user roles. For situations like this, you can augment the claims from your JSON web tokens with coprocessors.
Creating your own JWKS (advanced)
⚠️ Most third-party IdP services create and host a JWKS for you. If you use a third-party IdP, consult its documentation to obtain the JWKS URL to pass to your router.
Read this section if you use a custom IdP that doesn't currently publish its JWKS at a router-accessible URL.
The Apollo Router obtains each JSON Web Key (JWK) that it uses from the URLs that you specify via the jwks
configuration option. Each URL must provide a set of valid JWKs in a single JSON object called a JWK Set (or JWKS).
To provide a JWKS to your router, configure your IdP service to do the following whenever its collection of valid JWKs changes (such as when a JWK expires or is rotated):
- Generate a valid JWKS object that includes the details of every JWK that the router requires to perform token validation.
- Write the JWKS object to a location that your router can reach via a
file://
orhttps://
URL.- ⚠️ If any of your JWKs uses a symmetric signature algorithm (such as
HS256
), always use afile://
URL. Symmetric signature algorithms use a shared key that should never be accessible over the network.
- ⚠️ If any of your JWKs uses a symmetric signature algorithm (such as
Again, make sure the IdP is configured to perform these steps every time its collection of JWKs changes!
JWKS format
A JWKS is a JSON object with a single top-level property: keys
. The value of keys
is an array of objects that each represent a single JWK:
{"keys": [{// These JWK properties are explained below."kty": "RSA","alg": "RS256","kid": "abc123","use": "sig","n": "0vx7agoebGcQSuu...","e": "AQAB"}]}
It's common for the keys
array to contain only a single JWK, or sometimes two if your IdP is in the process of rotating a key.
JWK object reference
JWK object properties fall into two categories:
- Universal properties. You include these in your JWK objects regardless of which signature algorithm you use.
- Algorithm-specific properties. You include these only for JWK objects that use a corresponding signature algorithm.
Universal properties
These properties apply to any JWK:
Option | Description |
---|---|
| Short for key type. The high-level type of cryptographic algorithm that the JWK uses (such as |
| Short for algorithm. The exact cryptographic algorithm to use with the JWK, including key size (such as |
| Short for key identifier. The JWK's unique identifier. Your IdP should generate each JWK's JWTs created with a particular key can include that key's identifier in their payload, which helps the router determine which JWK to use for validation. |
| Indicates how a JWK is used. Spec-defined values are For keys you're using to perform JWT authentication, this value should be |
Algorithm-specific properties
RSA
See also the JWA spec.
{// Universal properties"kty": "RSA","alg": "RS256","kid": "abc123",// Algorithm-specific properties"n": "0vx7agoebGcQSuu...", // Shortened for readability"e": "AQAB"}
Option | Description |
---|---|
| The RSA public key's modulus value, as the base64-encoded value of the unsigned integer. |
| The RSA public key's exponent value, as the base64-encoded value of the unsigned integer. This value is often |
EC (elliptic curve)
See also the JWA spec.
{// Universal properties"kty": "EC","alg": "ES256","kid": "afda85e09a320cf748177874592de64d","use": "sig",// Algorithm-specific properties"crv": "P-256","x": "opFUViwCYVZLmsbG2cJTA9uPvOF5Gg8W7uNhrcorGhI","y": "bPxvCFKmlqTdEFc34OekvpviUUyelGrbi020dlgIsqo"}
Option | Description |
---|---|
| Indicates which cryptographic curve is used with this public key. Spec-defined curves include:
|
| The x-coordinate of the elliptic curve point for this public key, as the base64-encoded value of the coordinate's octet string representation. |
| The y-coordinate of the elliptic curve point for this public key, as the base64-encoded value of the coordinate's octet string representation. |
Symmetric key algorithms (such as HMAC)
{// Universal properties"kty": "oct","alg": "HS256","kid": "key1","use": "sig",// Symmetric-algorithm-specific property"k": "c2VjcmV0Cg==" // ⚠️ This is a base64-encoded shared secret! ⚠️}
Option | Description |
---|---|
| The value of the shared symmetric key, as the base64-encoded value of the key's octet sequence representation. ⚠️ If your JWK uses a symmetric signature algorithm, always provide your JWKS to the router via a |
JWK matching
To match an incoming JWT with its corresponding JWK, the router proceeds through descending "specificity levels" of match criteria until it identifies the first compatible JWK from its JWK Sets:
- The JWT and JWK match both
kid
andalg
exactly. - The JWT and JWK match
kid
, and the JWT'salg
is compatible with the JWK'skty
. - The JWT and JWK match
alg
exactly. - The JWT's
alg
is compatible with the JWK'skty
.
This matching strategy is necessary because some identity providers (IdPs) don't specify alg
or kid
values in their JWKS. However, they always specify a kty
, because that value is required by the JWK specification.
Forwarding JWTs to subgraphs
Because the Apollo Router handles validating incoming JWTs, you rarely need to pass those JWTs to individual subgraphs in their entirety. Instead, you usually want to pass JWT claims to subgraphs to enable fine-grained access control.
If you do need to pass entire JWTs to subgraphs, you can do so via the Apollo Router's general-purpose HTTP header propagation settings.
Observability
If your router enables tracing, the JWT authentication plugin has its own tracing span: authentication_plugin
If your router enables metrics collection via Prometheus, the JWT authentication plugin provides and exports the following metrics:
apollo_authentication_failure_count
apollo_authentication_success_count
Those metrics have the following shapes:
# HELP apollo_authentication_failure_count apollo_authentication_failure_count# TYPE apollo_authentication_failure_count counterapollo_authentication_failure_count{kind="JWT",service_name="apollo-router"} 1# HELP apollo_authentication_success_count apollo_authentication_success_count# TYPE apollo_authentication_success_count counterapollo_authentication_success_count{kind="JWT",service_name="apollo-router"} 11