Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Authorization in the Apollo Router

Strengthen subgraph security with a centralized governance layer


This feature is only available with a GraphOS Dedicated or Enterprise plan.
To compare GraphOS feature support across all plan types, see the pricing page.

APIs provide access to business-critical data. Unrestricted access can result in data breaches, monetary losses, or potential denial of service. Even for internal services, checks can be essential to limit data to authorized parties.

Services may have their own access controls, but enforcing authorization in the Apollo Router is valuable for a few reasons:

  • Optimal query execution: Validating authorization before processing requests enables the early termination of unauthorized requests. Stopping unauthorized requests at the edge of your reduces the load on your services and enhances performance.

    ❌ Subquery
    ❌ Subquery
    ⚠️Unauthorized
    request
    Apollo Router
    Users
    API
    Posts
    API
    Client

    • If every in a particular sub requires authorization, the 's query planner can eliminate entire subgraph requests for unauthorized requests. For example, a request may have permission to view a particular user's posts on a social media platform but not have permission to view any of that user's personally identifiable information (PII). Check out How it works to learn more.

    ✅ Authorized
    subquery
    ❌ Unauthorized
    subquery
    ⚠️ Partially authorized
    request
    Apollo Router
    Users
    API
    Posts
    API
    Client

    • Also, query deduplication groups requested based on their required authorization. Entire groups can be eliminated from the if they don't have the correct authorization.
  • Declarative access rules: You define access controls at the field level, and composes them across your services. These rules create graph-native governance without the need for an extra orchestration layer.

  • Principled architecture: Through , the router centralizes authorization logic while allowing for auditing at the service level. This centralized authorization is an initial checkpoint that other service layers can reinforce.


    🔐 Router layer                                                   
    🔐 Service layer
    Subquery
    Subquery
    Request
    Apollo Router
    Users
    API
    Posts
    API
    Client

💡 TIP

To learn more about why authorization is ideal at the router layer, watch Andrew Carlson's talk at Austin API Summit 2024: Centralize Data Access Control with GraphQL.

How access control works

The Apollo provides access controls via authorization directives that define access to specific fields and types across your :

For example, imagine you're building a social media platform that includes a Users . You can use the @requiresScopes directive to declare that viewing other users' information requires the read:user scope:

type Query {
users: [User!]! @requiresScopes(scopes: [["read:users"]])
}

You can use the @authenticated directive to declare that users must be logged in to update their own information:

type Mutation {
updateUser(input: UpdateUserInput!): User! @authenticated
}

You can define both directivestogether or separatelyat the field level to fine-tune your access controls. When are declared both on a field and the field's type, they will all be tried, and the field will be removed if any of them does not authorize it. GraphOS composes restrictions into the so that each subgraph's restrictions are respected. The router then enforces these directives on all incoming requests.

Prerequisites

NOTE

Only the Apollo Router supports authorization directives@apollo/gateway does not. Check out the migration guide if you'd like to use them.

Before using the authorization directives in your , you must:

Configure request claims

Claims are the individual details of a request's authentication and scope. They might include details like the ID of the user making the request and any authorization scopesfor example, read:profiles assigned to that user. The authorization directives use a request's claims to evaluate which fields and types are authorized.

To provide the router with the claims it needs, you must either configure JSON Web Token (JWT) authentication or add an external coprocessor that adds claims to a request's context. In some cases (explained below), you may require both.

  • JWT authentication configuration: If you configure JWT authentication, the Apollo Router automatically adds a JWT token's claims to the request's context at the apollo_authentication::JWT::claims key.
  • Adding claims via coprocessor: If you can't use JWT authentication, you can add claims with a coprocessor. Coprocessors let you hook into the Apollo Router's request-handling lifecycle with custom code.
  • Augmenting JWT claims via coprocessor: Your authorization policies 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.

Authorization directives

Authorization directives are turned on by default. To disable them, include the following in your router's YAML config file:

router.yaml
authorization:
directives:
enabled: false

@requiresScopes
Since 1.29.1

The @requiresScopes directive marks fields and types as restricted based on required scopes. The directive includes a scopes with an array of the required scopes to declare which scopes are required:

@requiresScopes(scopes: [["scope1", "scope2", "scope3"]])

💡 TIP

Use @requiresScopes when access to a field or type depends only on claims associated with a claims object or access token.

If your authorization validation logic or data are more complexsuch as checking specific values in headers or looking up data from other sources such as databasesand aren't solely based on a claims object or access token, use @policy instead.

Depending on the scopes present on the request, the router filters out unauthorized fields and types.

You can use Boolean logic to define the required scopes. See Combining required scopes for details.

The directive validates the required scopes by loading the claims object at the apollo_authentication::JWT::claims key in a request's context. The claims object's scope key's value should be a space-separated string of scopes in the format defined by the OAuth2 RFC for access token scopes.

claims = context["apollo_authentication::JWT::claims"]
claims["scope"] = "scope1 scope2 scope3"

Usage

To use the @requiresScopes directive in a subgraph, you can import it from the @link directive like so:

extend schema
@link(
url: "https://specs.apollo.dev/federation/v2.5",
import: [..., "@requiresScopes"])

It is defined as follows:

scalar federation__Scope
directive @requiresScopes(scopes: [[federation__Scope!]!]!) on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

Combining required scopes with AND/OR logic

A request must include all elements in the inner-level scopes array to resolve the associated field or type. In other words, the authorization validation uses AND logic between the elements in the inner-level scopes array.

@requiresScopes(scopes: [["scope1", "scope2", "scope3"]])

For the preceding example, a request would need scope1 AND scope2 AND scope3 to be authorized.

You can use nested arrays to introduce OR logic:

@requiresScopes(scopes: [["scope1"], ["scope2"], ["scope3"]])

For the preceding example, a request would need scope1 OR scope2 OR scope3 to be authorized.

You can nest arrays and elements as needed to achieve your desired logic. For example:

@requiresScopes(scopes: [["scope1", "scope2"], ["scope3"]])

This syntax requires requests to have either (scope1 AND scope2) OR just scope3 to be authorized.

Example @requiresScopes use case

Imagine the social media platform you're building lets users view other users' information only if they have the required permissions. Your schema may look like this:

type Query {
user(id: ID!): User @requiresScopes(scopes: [["read:others"]])
users: [User!]! @requiresScopes(scopes: [["read:others"]])
post(id: ID!): Post
}
type User {
id: ID!
username: String
email: String @requiresScopes(scopes: [["read:email"]])
profileImage: String
posts: [Post!]!
}
type Post {
id: ID!
author: User!
title: String!
content: String!
}

Depending on a request's attached scopes, the router executes the following query differently. If the request includes only the read:others scope, then the router executes the following filtered query:

Raw query to router
query {
users {
username
profileImage
email
}
}
Scopes: 'read:others'
query {
users {
username
profileImage
}
}

The response would include an error at the /users/@/email path since that field requires the read:emails scope. The router can execute the entire query successfully if the request includes the read:others read:emails scope set.

The router returns null for unauthorized fields and applies the standard GraphQL null propagation rules.

Unauthorized request response
{
"data": {
"me": null,
"post": {
"title": "Securing supergraphs",
}
},
"errors": [
{
"message": "Unauthorized field or type",
"path": [
"me"
],
"extensions": {
"code": "UNAUTHORIZED_FIELD_OR_TYPE"
}
},
{
"message": "Unauthorized field or type",
"path": [
"post",
"views"
],
"extensions": {
"code": "UNAUTHORIZED_FIELD_OR_TYPE"
}
}
]
}

@authenticated
Since 1.29.1

The @authenticated directive marks specific fields and types as requiring authentication. It works by checking for the apollo_authentication::JWT::claims key in a request's context, that is added either by the JWT authentication plugin, when the request contains a valid JWT, or by an authentication coprocessor. If the key exists, it means the request is authenticated, and the router executes the query in its entirety. If the request is unauthenticated, the router removes @authenticated fields before planning the query and only executes the parts of the query that don't require authentication.

Usage

To use the @authenticated directive in a subgraph, you can import it from the @link directive like so:

extend schema
@link(
url: "https://specs.apollo.dev/federation/v2.5",
import: [..., "@authenticated"])

It is defined as follows:

directive @authenticated on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

Example @authenticated use case

Diving deeper into the social media example: let's say unauthenticated users can view a post's title, author, and content. However, you only want authenticated users to see the number of views a post has received. You also need to be able to query for an authenticated user's information.

The relevant part of your schema may look like this:

type Query {
me: User @authenticated
post(id: ID!): Post
}
type User {
id: ID!
username: String
email: String @requiresScopes(scopes: [["read:email"]])
posts: [Post!]!
}
type Post {
id: ID!
author: User!
title: String!
content: String!
views: Int @authenticated
}

Consider the following query:

Sample query
query {
me {
username
}
post(id: "1234") {
title
views
}
}

The router would execute the entire query for an authenticated request. For an unauthenticated request, the router would remove the @authenticated fields and execute the filtered query.

Query executed for an authenticated request
query {
me {
username
}
post(id: "1234") {
title
views
}
}
Query executed for an unauthenticated request
query {
post(id: "1234") {
title
}
}

For an unauthenticated request, the router doesn't attempt to resolve the top-level me query, nor the views for the post with id: "1234". The response retains the initial request's shape but returns null for unauthorized fields and applies the standard GraphQL null propagation rules.

Unauthenticated request response
{
"data": {
"me": null,
"post": {
"title": "Securing supergraphs",
}
},
"errors": [
{
"message": "Unauthorized field or type",
"path": [
"me"
],
"extensions": {
"code": "UNAUTHORIZED_FIELD_OR_TYPE"
}
},
{
"message": "Unauthorized field or type",
"path": [
"post",
"views"
],
"extensions": {
"code": "UNAUTHORIZED_FIELD_OR_TYPE"
}
}
]
}

If every requested field requires authentication and a request is unauthenticated, the router generates an error indicating that the query is unauthorized.

@policy
Since 1.35.0

The @policy directive marks fields and types as restricted based on authorization policies evaluated in a Rhai script or coprocessor. This enables custom authorization validation beyond authentication and scopes. It is useful when we need more complex policy evaluation than verifying the presence of a claim value in a list (example: checking specific values in headers).

💡 TIP

If access to a field or type is restricted solely by the claims associated with a claims object or access token, consider using @requiresScopes instead.

The @policy directive includes a policies argument that defines an array of the required policies that are a list of strings with no formatting constraints. In general you can use the strings as arguments for any format you like. The following example shows a policy that might require the support role:

@policy(policies: [["roles:support"]])

Using the @policy directive requires a Supergraph plugin to evaluate the authorization policies. This is useful to bridge router authorization with an existing authorization stack or link policy execution with lookups in a database.

An overview of how @policy is processed through the router's request lifecycle:

  • At the RouterService level, the Apollo Router extracts the list of policies relevant to a request from the schema and then stores them in the request's context in apollo_authorization::policies::required as a map policy -> null|true|false.

  • At the SupergraphService level, you must provide a Rhai script or coprocessor to evaluate the map. If the policy is validated, the script or coprocessor should set its value to true or otherwise set it to false. If the value is left to null, it will be treated as false by the router. Afterward, the router filters the requests' types and fields to only those where the policy is true.

  • If no field of a subgraph query passes its authorization policies, the router stops further processing of the query and precludes unauthorized subgraph requests. This efficiency gain is a key benefit of the @policy and other authorization directives.

Usage

To use the @policy directive in a subgraph, you can import it from the @link directive like so:

extend schema
@link(
url: "https://specs.apollo.dev/federation/v2.6",
import: [..., "@policy"])

The @policy directive is defined as follows:

scalar federation__Policy
directive @policy(policies: [[federation__Policy!]!]!) on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

Using the @policy directive requires a Supergraph plugin to evaluate the authorization policies. You can do this with a Rhai script or coprocessor. Refer to the following example use case for more information. (Although a native plugin can also evaluate authorization policies, we don't recommend using it.)

Combining policies with AND/OR logic

Authorization validation uses AND logic between the elements in the inner-level policies array, where a request must include all elements in the inner-level policies array to resolve the associated field or type. For the following example, a request would need policy1 AND policy2 AND policy3 to be authorized:

@policy(policies: [["policy1", "policy2", "policy3"]])

Alternatively, to introduce OR logic you can use nested arrays. For the following example, a request would need policy1 OR policy2 OR policy3 to be authorized:

@policy(policies: [["policy1"], ["policy2"], ["policy3"]])

You can nest arrays and elements as needed to achieve your desired logic. For the following example, its syntax requires requests to have either (policy1 AND policy2) OR just policy3 to be authorized:

@policy(policies: [["policy1", "policy2"], ["policy3"]])

Example @policy use case

Usage with a coprocessor

Diving even deeper into the social media example: suppose you want only a user to have access to their own profile and credit card information. Of the available authorization directives, you use @policy instead of @requiresScopes because the validation logic relies on more than the scopes of an access token.

You can add the authorization policies read_profile and read_credit_card. The relevant part of your schema may look like this:

type Query {
me: User @authenticated @policy(policies: [["read_profile"]])
post(id: ID!): Post
}
type User {
id: ID!
username: String
email: String @requiresScopes(scopes: [["read:email"]])
posts: [Post!]!
credit_card: String @policy(policies: [["read_credit_card"]])
}
type Post {
id: ID!
author: User!
title: String!
content: String!
views: Int @authenticated
}

You can use a coprocessor called at the request stage to receive and execute the list of policies.

If you configure your router like this:

router.yaml
coprocessor:
url: http://127.0.0.1:8081
supergraph:
request:
context: true

A coprocessor can then receive a request with this format:

{
"version": 1,
"stage": "SupergraphRequest",
"control": "continue",
"id": "d0a8245df0efe8aa38a80dba1147fb2e",
"context": {
"entries": {
"apollo_authentication::JWT::claims": {
"exp": 10000000000,
"sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
},
"apollo_authorization::policies::required": {
"read_profile": null,
"read_credit_card": null
}
}
},
"method": "POST"
}

A user can read their own profile, so read_profile will succeed. But only the billing system should be able to see the credit card, so read_credit_card will fail. The coprocessor will then return:

{
"version": 1,
"stage": "SupergraphRequest",
"control": "continue",
"id": "d0a8245df0efe8aa38a80dba1147fb2e",
"context": {
"entries": {
"apollo_authentication::JWT::claims": {
"exp": 10000000000,
"sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
},
"apollo_authorization::policies::required": {
"read_profile": true,
"read_credit_card": false
}
}
}
}
Usage with a Rhai script

For another example, suppose that you want to restrict access for posts to a support user. Given that the policies argument is a string, you can set it as a "<key>:<value>" format that a Rhai script can parse and evaluate.

The relevant part of your schema may look like this:

type Query {
me: User @policy(policies: [["kind:user"]])
}
type User {
id: ID!
username: String @policy(policies: [["roles:support"]])
}

You can then use the following Rhai script to parse and evaluate the policies string:

fn supergraph_service(service) {
let request_callback = |request| {
let claims = request.context["apollo_authentication::JWT::claims"];
let policies = request.context["apollo_authorization::policies::required"];
if policies != () {
for key in policies.keys() {
let array = key.split(":");
if array.len == 2 {
switch array[0] {
"kind" => {
policies[key] = claims[`kind`] == array[1];
}
"roles" => {
policies[key] = claims[`roles`].contains(array[1]);
}
_ => {}
}
}
}
}
request.context["apollo_authorization::policies::required"] = policies;
};
service.map_request(request_callback);
}

Special case for subscriptions

When using along with @policy authorization, events restart from the execution service, which means that if the authorization status of the subscription session changed, then it cannot go through query planning again, and the session should be closed. To that end, the policies should be evaluated again at the execution service level, and if they changed, an error should be returned to stop the subscription.

Composition and federation

GraphOS's composition strategy for authorization directives is intentionally accumulative. When you define authorization directives on fields and types in , GraphOS composes them into the supergraph schema. In other words, if subgraph fields or types include @requiresScopes, @authenticated, or @policy directives, they are set on the supergraph too.

Composition with AND/OR logic

If shared subgraph fields include multiple directives, composition merges them. For example, suppose the me query requires @authentication in one subgraph:

Subgraph A
type Query {
me: User @authenticated
}
type User {
id: ID!
username: String
email: String
}

and the read:user scope in another subgraph:

Subgraph B
type Query {
me: User @requiresScopes(scopes: [["read:user"]])
}
type User {
id: ID!
username: String
email: String
}

A request would need to both be authenticated AND have the required scope. Recall that the @authenticated directive only checks for the existence of the apollo_authentication::JWT::claims key in a request's context, so authentication is guaranteed if the request includes scopes.

If multiple shared subgraph fields include @requiresScopes, the supergraph schema merges them with the same logic used to combine scopes for a single use of @requiresScopes. For example, if one subgraph requires the read:others scope on the users query:

Subgraph A
type Query {
users: [User!]! @requiresScopes(scopes: [["read:others"]])
}

and another subgraph requires the read:profiles scope on users query:

Subgraph B
type Query {
users: [User!]! @requiresScopes(scopes: [["read:profiles"]])
}

Then the supergraph schema would require both scopes for it.

Supergraph
type Query {
users: [User!]! @requiresScopes(scopes: [["read:others", "read:profiles"]])
}

As with combining scopes for a single use of @requiresScopes, you can use nested arrays to introduce OR logic:

Subgraph A
type Query {
users: [User!]! @requiresScopes(scopes: [["read:others", "read:users"]])
}
Subgraph B
type Query {
users: [User!]! @requiresScopes(scopes: [["read:profiles"]])
}

Since both scopes arrays are nested arrays, they would be composed using OR logic into the supergraph schema:

Supergraph
type Query {
users: [User!]! @requiresScopes(scopes: [["read:others", "read:users"], ["read:profiles"]])
}

This syntax means a request needs either (read:others AND read:users) scopes OR just the read:profiles scope to be authorized.

Authorization and @key fields

The @key directive lets you create an whose fields resolve across multiple subgraphs. If you use authorization directives on fields defined in @key directives, Apollo still uses those fields to compose entities between the subgraphs, but the client cannot query them directly.

Consider these example subgraph schemas:

Product subgraph
type Query {
product: Product
}
type Product @key(fields: "id") {
id: ID! @authenticated
name: String!
price: Int @authenticated
}
Inventory subgraph
type Query {
product: Product
}
type Product @key(fields: "id") {
id: ID! @authenticated
inStock: Boolean!
}

An unauthenticated request would successfully execute this query:

query {
product {
name
inStock
}
}

Specifically, under the hood, the router would use the id field to resolve the Product entity, but it wouldn't return it.

For the following query, an unauthenticated request would resolve null for id. And since id is a non-nullable field, product would return null.

query {
product {
id
username
}
}

This behavior resembles what you can create with contracts and the @inaccessible directive.

Authorization and interfaces

If a type implementing an interface requires authorization, unauthorized requests can query the interface, but not any parts of the type that require authorization.

For example, consider this schema where the Post interface doesn't require authentication, but the PrivateBlog type, which implements Post, does:

type Query {
posts: [Post!]!
}
type User {
id: ID!
username: String
posts: [Post!]!
}
interface Post {
id: ID!
author: User!
title: String!
content: String!
}
type PrivateBlog implements Post @authenticated {
id: ID!
author: User!
title: String!
content: String!
publishAt: String
allowedViewers: [User!]!
}

If an unauthenticated request were to make this query:

query {
posts {
id
author
title
... on PrivateBlog {
allowedViewers
}
}
}

The router would filter the query as follows:

query {
posts {
id
author
title
}
}

The response would include an "UNAUTHORIZED_FIELD_OR_TYPE" error at the /posts/@/allowedViewers path.

Query deduplication

You can enable query deduplication in the router to reduce redundant requests to a subgraph. The router does this by buffering similar queries and reusing the result.

Query deduplication takes authorization into account. First, the router groups unauthenticated queries together. Then it groups authenticated queries by their required scope set. It uses these groups to execute queries efficiently when fulfilling requests.

Introspection

is turned off in the router by default, as is best production practice. If you've chosen to enable it, keep in mind that authorization directives don't affect introspection. All fields that require authorization remain visible. However, directives applied to fields aren't visible. If might reveal too much information about internal types, then be sure it hasn't been enabled in your router configuration.

With introspection turned off, you can use GraphOS's schema registry to explore your supergraph schema and empower your teammates to do the same. If you want to completely remove fields from a graph rather than just preventing access (even with introspection on), consider building a contract graph.

Configuration options

The behavior of the authorization plugin can be modified with various options.

reject_unauthorized

The reject_unauthorized option configures whether to reject an entire query if any authorization directive failed, or any part of the query was filtered by authorization directives. When enabled, a response contains the list of paths that are affected.

router.yaml
authorization:
directives:
enabled: true
reject_unauthorized: true # default: false

errors

By default, when part of a query is filtered by authorization, the list of filtered paths is added to the response and logged by the router. This behavior can be customized for your needs.

log

By enabling the log option, you can choose if query filtering will result in a log event being output.

router.yaml
authorization:
directives:
errors:
log: false # default: true

NOTE

The log option should be disabled if filtering parts of queries according to the client's rights is approved as normal by platform operators.

response

You can configure response to define what part of the response should include filtered paths:

  • errors (default) : place filtered paths in GraphQL errors
  • extensions: place filtered paths in . Useful to suppress exceptions on the client side while still giving information that parts of the query were filtered
  • disabled: suppress all information that the query was filtered.
router.yaml
authorization:
directives:
errors:
response: "errors" # possible values: "errors" (default), "extensions", "disabled"

dry_run

The dry_run option allows you to execute authorization directives without modifying a query, and evaluate the impact of authorization policies without interfering with existing traffic. It generates and returns the list of unauthorized paths as part of the response.

router.yaml
authorization:
directives:
enabled: true
dry_run: true # default: false
Previous
JWT Authentication
Next
Subgraph Authentication