Phase 2: APIs & Databases

Authentication & authorization in the GraphQL layer

Intermediate ~3 min read
Think of it this way A friendly analogy. Read this if the technical version feels dense. Show Hide

Imagine a huge, super cool digital library – not with physical books, but with all sorts of information and tools that apps and websites use. This is kind of what an API (Application Programming Interface) is like, and GraphQL is a special way to ask for things from that library. Just like a real library, we can't let just anyone walk in and grab any book, or change how the library works! We need to make sure the right people get the right access. That's where two important helpers come in: Authentication (say: "aw-then-ti-KAY-shun") and Authorization (say: "aw-thor-i-ZAY-shun"). They work like the front desk and section librarians of our digital library.

First, Authentication is all about figuring out who you are. Think of it like walking into our big digital library. Before you can even look at any books, a friendly librarian at the front desk asks for your library card. You show your card, and they quickly check two things: "Is this a real, valid library card?" and "Are you the person whose name is on this card?" If everything checks out, they nod, confirm your name, and maybe even make a mental note (or a quick entry on their computer) about what type of card you have – maybe you have a "standard reader" card, or maybe a "special researcher" card. This process of identifying you at the entrance is Authentication.

Now that the librarian knows who you are and what type of card you have, we move to Authorization. This is about deciding what you are allowed to do. As you wander through the library and ask for different books, every librarian you meet (or every part of the library system you interact with) already knows about your library card from the front desk's check. If you ask for a regular storybook, they see your "standard reader" card and say, "Sure, here you go!" But if you try to get into the "Rare Books Archive" section, the librarian there looks at your card info and sees you only have a "standard reader" card, not the "special researcher" card needed for that section. So, they politely say, "Sorry, you don't have the special permission for these books." This system ensures you can only access what your card allows.

So, if you wanted to build an app for our digital library, you would use these ideas to protect everyone's information. For example, if you're building a feature that lets users update their own profile (like changing their address), you'd use Authentication to make sure it's really them logged in. Then, you'd use Authorization to make sure they can only change their own address, and not someone else's! This is how websites and apps keep things safe and organized, making sure only authorized users can view or change specific data. This means you can create secure and personalized experiences where everyone gets exactly what they need, and nothing more.

Authentication and authorization are fundamental security layers for any API, and GraphQL is no exception. However, unlike traditional REST APIs where HTTP status codes and endpoint structures might inherently suggest security boundaries, the GraphQL specification itself does not prescribe how authentication (who is the user?) or authorization (what can the user do?) should be handled. Instead, these crucial security mechanisms are implemented within your GraphQL server's application logic, typically as middleware that processes incoming requests before they reach your data-fetching resolvers.

Practically, authentication usually occurs at the request level, before any GraphQL query or mutation is executed. Your GraphQL server (e.g., built with Apollo Server, GraphQL-Yoga, or similar frameworks) will intercept incoming HTTP requests, looking for an authentication token (like a JWT) in the Authorization header. This token is then validated, and if valid, the decoded user information (e.g., user ID, roles, permissions) is attached to the context object. This context object is a special parameter passed to every single resolver in your GraphQL schema, making the authenticated user's identity readily available throughout your GraphQL execution pipeline.

Once a user is authenticated, authorization comes into play within your individual resolvers. Each resolver is responsible for deciding whether the authenticated user has the necessary permissions to access or modify the specific data it handles. This is done by checking the user information available in the context object. For example, a resolver for an adminDashboard query might check context.user.role === 'ADMIN'. Authorization can be implemented imperatively (with if statements inside resolvers) or declaratively using custom GraphQL directives (e.g., @auth(roles: ["ADMIN"])), which can offer a more reusable and schema-driven approach to applying access control logic across multiple fields or types. Granular authorization, down to specific fields within a type, is crucial for robust API security.

Key Takeaways

  • GraphQL itself doesn't define auth/authz; you implement it in your server.
  • Authentication happens pre-resolver, attaching user info to the context object.
  • Authorization logic resides within resolvers, checking context.user for permissions.
  • Custom GraphQL directives can provide a declarative way to manage authorization.
  • Implement granular authorization, ideally at the field level, for robust security.

Code Example

javascript
Preview

How this code works

This code demonstrates how to secure a GraphQL API by controlling access to sensitive data, specifically the internalReports query. Its job is to ensure that only authenticated users with the correct permissions can view these reports.

The internalReports function inside the Query resolver is where this protection happens. It receives a context object, which typically contains information about the current request, including the authenticated user. First, an Authentication check (if (!context.user)) verifies if there is any logged-in user; if not, an error is thrown. Next, an Authorization check (if (context.user.role !== 'MANAGER')) determines if the logged-in user has the required 'MANAGER' role. A subtle but important detail is the order: authentication must occur before authorization, as the authorization check depends on a context.user object existing. Only if both checks pass does the code proceed to return the protected list of reports.

Resources

Related Articles

Hand-picked reads to go deeper on graphql.

Back to Backend Developer Roadmap