Authentication in GraphQL APIs

# CHAPTER 15

Authentication in GraphQL APIs #

1. Introduction #

2. Learning Objectives #

• Explain how Authentication fits into the GraphQL architecture.

• Understand the role of HTTP Headers in securing requests.

• Implement a login Mutation to generate JSON Web Tokens (JWT).

• Inject the authenticated user into the GraphQL $context object in PHP.

3. Beginner-Friendly Explanation #

In GraphQL, because there is only one door (the /graphql endpoint), the bouncer stands right in front of it. Before the server even looks at your query, it checks your HTTP Headers for a Token. If the token is valid, the server attaches your "User ID" to a special backpack called the $context. As your query moves through the library (the Resolvers), every librarian (Resolver) can look in the backpack, see who you are, and decide if they should give you the data.

4. Real-World Examples #

• Mobile App Login: A user opens an app and logs in. The GraphQL server verifies the password and sends back a JWT. The app saves this JWT. On every subsequent query (fetching posts, liking photos), the app attaches the JWT to the HTTP request.

• Public vs Private Data: A blog API allows anyone to query getPosts. But if a user queries myProfile, the resolver checks the $context. If there is no user in the context, it throws a "Not Authenticated" error.

5. The Login Mutation #

The Schema:

type AuthPayload {
  token: String!
  user: User!
}

type Mutation {
  login(email: String!, password: String!): AuthPayload
}

The Query from the Client:

mutation UserLogin($email: String!, $pass: String!) {
  login(email: $email, password: $pass) {
    token
    user {
      username
    }
  }
}

*Note: The resolver for login will check the database, verify the password hash, generate a JWT string, and return it.*

6. Sending the Token (The Client Side) #

Using Javascript (Fetch API):

fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // The wristband!
    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE'
  },
  body: JSON.stringify({ query: '{ myProfile { name } }' })
})

7. Verifying the Token (The PHP Server Side) #

<?php
// 1. Get the HTTP Header
$headers = apache_request_headers();
$token = isset($headers[&#039;Authorization']) ? str_replace('Bearer ', '', $headers['Authorization']) : null;

$currentUser = null;

// 2. Validate the JWT
if ($token) {
    // (Assume decodeJWT returns a user ID if valid)
    $userId = decodeJWT($token); 
    if ($userId) {
        $currentUser = fetchUserFromDatabase($userId);
    }
}

// 3. Inject into the GraphQL Context!
$context = [
    &#039;user' => $currentUser,
    &#039;db' => $pdoConnection
];

// 4. Execute the Query
$result = GraphQL::executeQuery($schema, $query, null, $context, $variables);
?>

8. Using Context in Resolvers #

'myProfile' => [
    'type' => $userType,
    'resolve' => function ($root, $args, $context) {
        // Look in the backpack!
        if (!$context['user']) {
            throw new \Exception("You must be logged in to view this.");
        }
        
        return $context['user'];
    }
]

9. Best Practices #

• Do Authentication Outside GraphQL: Validating the HTTP header and decoding the JWT should happen in your core PHP/Node application *before* you hand the request to the GraphQL engine.

• Use standard JWTs: JSON Web Tokens are stateless, secure, and the industry standard for GraphQL authentication.

• Never store sensitive data in the schema: Never return passwords, password hashes, or salt strings in your GraphQL Schema types.

10. Common Mistakes #

• Putting Login logic in HTTP parameters: Do not pass passwords via GET parameters. Always use a GraphQL POST Mutation over an HTTPS connection.

• Confusing Authentication with Authorization: *Authentication* is proving who you are (logging in). *Authorization* is proving what you are allowed to do (admin vs user). We will cover Authorization next!

11. Mini Exercises #

1. 1. What HTTP header is standard for sending authentication tokens?

1. 2. Which of the 4 resolver arguments is used to pass the authenticated user down to all resolvers?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the flow of Authentication in a GraphQL application from the moment the user clicks "Login" to their next subsequent query.

• Q: Why do we populate the user data into the $context object instead of having every resolver check the HTTP headers themselves?

• Q: Is GraphQL responsible for Authentication, or is it handled by the HTTP transport layer?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #