Directive-based authorization in GraphQL

Introduction

Directive-based authorization helps control who can see or change data in a GraphQL API. It keeps data safe by checking permissions before giving access.

When you want only logged-in users to see certain data.

When some users should only read data but not change it.

When you want to hide sensitive information from some users.

When you want to check user roles before allowing actions.

When you want to keep your API secure without writing extra code everywhere.

Syntax

GraphQL

directive @auth(
  requires: Role = USER
) on OBJECT | FIELD_DEFINITION

enum Role {
  ADMIN
  USER
  GUEST
}

Directives start with @ and add rules to types or fields.

You define roles or permissions inside the directive to check user access.

Examples

This example only lets users with the ADMIN role see secretData.

GraphQL

type Query {
  secretData: String @auth(requires: ADMIN)
}

This example requires users to be logged in (USER role) to access the whole User type.

GraphQL

type User @auth(requires: USER) {
  id: ID!
  email: String
}

This shows how to define the @auth directive and roles for authorization.

GraphQL

directive @auth(requires: Role = USER) on OBJECT | FIELD_DEFINITION

enum Role {
  ADMIN
  USER
  GUEST
}

Sample Program

This GraphQL schema defines a directive @auth to protect fields. publicInfo is open to all. privateInfo needs a USER role. adminInfo needs ADMIN role.

GraphQL

directive @auth(requires: Role = USER) on OBJECT | FIELD_DEFINITION

enum Role {
  ADMIN
  USER
  GUEST
}

type Query {
  publicInfo: String
  privateInfo: String @auth(requires: USER)
  adminInfo: String @auth(requires: ADMIN)
}

Important Notes

Directive-based authorization keeps your schema clean and easy to read.

You still need server code to check the user's role when a query runs.

Use roles that match your app's needs for better security.

Summary

Directive-based authorization uses special tags to control access.

You add directives to types or fields to require user roles.

This method helps keep data safe and your API organized.

Practice

1. What is the main purpose of using directive-based authorization in GraphQL?

easy

A. To control who can access certain data or operations

B. To speed up query execution

C. To format the output data

D. To create new database tables

Solution

1. Step 1: Understand directive-based authorization

   Directive-based authorization adds rules to GraphQL fields or types to restrict access based on user roles or permissions.

2. Step 2: Identify the main goal

   The main goal is to control access to data or operations, ensuring only authorized users can see or change certain information.

3. Final Answer:

   To control who can access certain data or operations -> Option A

4. Quick Check:

   Authorization controls access = B [OK]

Hint: Authorization directives control access permissions [OK]

Common Mistakes:

• Confusing authorization with performance optimization
• Thinking directives format data output
• Assuming directives create database structures

2. Which of the following is the correct syntax to apply a directive named @auth requiring a role ADMIN on a GraphQL field?

easy

A. type Query { secretData: String @auth(role: ADMIN) }

B. type Query { secretData: String @auth(role: "ADMIN") }

C. type Query { secretData: String @auth(role=ADMIN) }

D. type Query { secretData: String @auth[role=ADMIN] }

Solution

1. Step 1: Recall directive syntax in GraphQL

   Directives use parentheses with named arguments and string values in quotes, e.g., @directiveName(argName: "value").

2. Step 2: Match the correct syntax

   type Query { secretData: String @auth(role: "ADMIN") } correctly uses @auth(role: "ADMIN") with quotes around the string role value.

3. Final Answer:

   type Query { secretData: String @auth(role: "ADMIN") } -> Option B

4. Quick Check:

   Directive args use parentheses and quotes = D [OK]

Hint: Directives use parentheses and quoted strings for arguments [OK]

Common Mistakes:

• Using square brackets instead of parentheses
• Omitting quotes around string values
• Using equals sign without quotes

3. Given the schema snippet:

type Query {
  userProfile: User @auth(role: "USER")
}

type User {
  id: ID!
  email: String
  secretNote: String @auth(role: "ADMIN")
}

What happens when a user with role USER queries userProfile { id email secretNote }?

medium

A. The query returns only id

B. The query returns all fields including secretNote

C. The query fails with an authorization error

D. The query returns id and email, but secretNote is blocked

Solution

1. Step 1: Analyze field-level directives

   The userProfile field requires role USER, so the user can access it. The secretNote field requires ADMIN role, which the user does not have.

2. Step 2: Determine accessible fields

   The user can see id and email but not secretNote because of the stricter ADMIN directive on that field.

3. Final Answer:

   The query returns id and email, but secretNote is blocked -> Option D

4. Quick Check:

   Field directives restrict access individually = C [OK]

Hint: Field directives override parent access; check each field's role [OK]

Common Mistakes:

• Assuming all fields inherit parent directive permissions
• Expecting full data without role ADMIN
• Thinking query fails instead of partial data

4. Consider this schema snippet:

type Query {
  adminData: String @auth(role: "ADMIN")
}

Which of the following fixes the error if the directive @auth is not recognized by the GraphQL server?

medium

A. Define the @auth directive in the schema with directive @auth(role: String) on FIELD_DEFINITION

B. Remove the @auth directive from the schema

C. Change @auth to @authorize without defining it

D. Rename the field adminData to adminInfo

Solution

1. Step 1: Understand directive registration

   GraphQL requires custom directives to be declared in the schema before use, specifying their name, arguments, and locations.

2. Step 2: Apply correct fix

   Define the @auth directive in the schema with directive @auth(role: String) on FIELD_DEFINITION correctly defines the @auth directive with a role argument and usage on field definitions, enabling the server to recognize it.

3. Final Answer:

   Define the @auth directive in the schema with directive @auth(role: String) on FIELD_DEFINITION -> Option A

4. Quick Check:

   Custom directives must be declared in schema = A [OK]

Hint: Declare custom directives in schema before use [OK]

Common Mistakes:

• Removing directives without replacing authorization
• Using undefined directive names
• Changing field names unrelated to directive errors

5. You want to restrict access so that only users with role EDITOR or ADMIN can update posts. Which directive usage correctly applies this logic on the updatePost mutation?

hard

A. type Mutation { updatePost(id: ID!, content: String!): Post @auth(role: "EDITOR") @auth(role: "ADMIN") }

B. type Mutation { updatePost(id: ID!, content: String!): Post @auth(roles: ["EDITOR", "ADMIN"]) }

C. type Mutation { updatePost(id: ID!, content: String!): Post @auth(role_in: ["EDITOR", "ADMIN"]) }

D. type Mutation { updatePost(id: ID!, content: String!): Post @auth(role: "EDITOR" OR "ADMIN") }

Solution

1. Step 1: Understand role list syntax in directives

   To allow multiple roles, the directive argument should accept a list (array) of roles, often named role_in or similar, depending on implementation.

2. Step 2: Evaluate options for correct syntax

   type Mutation { updatePost(id: ID!, content: String!): Post @auth(role_in: ["EDITOR", "ADMIN"]) } uses @auth(role_in: ["EDITOR", "ADMIN"]), which correctly passes an array of roles to check for authorization.

3. Final Answer:

   type Mutation { updatePost(id: ID!, content: String!): Post @auth(role_in: ["EDITOR", "ADMIN"]) } -> Option C

4. Quick Check:

   Use array argument for multiple roles = A [OK]

Hint: Use array argument to list multiple allowed roles [OK]

Common Mistakes:

• Stacking multiple @auth directives instead of one with list
• Using invalid OR syntax inside directive argument
• Using wrong argument name like roles instead of role_in