Authorization Patterns in GraphQL

Rate this content

As it says in the GraphQL documentation: "Delegate authorization logic to the business logic layer". Is that really everything you need to know? This advice is coming from a good place, but it relies on you knowing how you would go about doing authorization in the first place — and this isn't a widely solved problem! On top of that, many of the approaches used in traditional applications don't quite carry over. In this talk, you'll get a crash course in authorization and how to implement it for GraphQL APIs."

20 min
08 Dec, 2022

AI Generated Video Summary

This talk introduces the theory and practice of authorization in GraphQL, highlighting the importance of proper authorization in ensuring application functionality and security. Delegating authorization to the business logic layer is a golden rule in GraphQL, ensuring consistency and avoiding duplication of logic. Authorization can be done in the resolver layer, but it is recommended to combine it with filtering at the database level. Abstracting authorization behind an API centralizes logic and makes it easier to manage. Custom directives and permissions fields can reduce the tedium of ensuring correct authorization in every resolver.

1. Introduction to Authorization in GraphQL

Short description:

This talk introduces the theory and practice of authorization in GraphQL. The speaker provides definitions of authentication and authorization, emphasizing the importance of application authorization. They give examples of robust authorization systems in GitHub and AWS IAM, as well as less obvious examples like Google Docs and Notion. The talk highlights the significance of proper authorization in ensuring the functionality and security of an application.

All good talks need to start with a quote, right? So, you know how they say, in theory, there's no difference between theory and practice, but in practice there is? Well, that's what this talk is about. I'm going to talk to you about the theory of authorization in GraphQL, and then if and how this matches practice. So, I'm Sam, I'm the cofounder and CTO at Oso, and we build authorization for developers. And as someone who did a PhD in cryptography and sort of gradually slid more and more into the practical world, I'm pretty familiar with the distinction between theory and practice.

So, strap yourselves in and learn a little about patterns in GraphQL, both theoretical and practical. So, I know there's a lot of confusion out there around the difference between authentication and authorization, so I'll start out with a few definitions. Authentication is all about identity, you know, who is the user? It may be you identify them through username and password, you may do single sign on, you may have two-factor authentication, that's all authentication. Authorization is the piece that comes next. Now that you know who the user is, what can they do? And I'm going to be talking about application authorization. So, specifically, what can they do inside your application?

To give you a few examples, GitHub, this is a great example. It's got a pretty robust authorization system. It allows you to do roles at the organizational level, like owner and member, and which of those can create repositories. You can also have roles at a more granular level. I can invite you as a collaborator to my repository and give you a role that grants you different access. Now, I really like GitHub as an example, because they also have a GraphQL API, so we'll be able to see not just authorization generically, but also in the context of GraphQL. For a bit more of a complex authorization example, take AWS IAM. And with AWS IAM, you can sort of write your own authorization, logic, and policies to determine who is allowed to do what inside of this ginormous platform. It's a pretty complex one. But there are some application authorization that you might not think about so much. Take something like Google Docs or Notion, where part of the core workflow is inviting people to collaborate on documents, or maybe invite them to an entire folder and say where they can view, edit or comment on those documents. That's all authorization. GitHub, AWS, Google Docs, Notion, these are all fantastic examples of application authorization.

So before we start getting into the technical details, why is this an important topic to talk about? Well, first of all, if you don't have authorization and application, your product is entirely broken. You sort of have anarchy. Anybody can go in and do anything. They can go and delete other users, they can delete other people's data, they can do anything. But on the other hand, if your authorization is broken, people can't get access to anything. Your app doesn't work. If your authorization is buggy, then users start getting annoyed. We've all been in that situation where the authorization logic in an app is so broken and frustrating that you just say, you know what, I'm going to go make everybody an admin.

2. Authorization Patterns in the Business Logic Layer

Short description:

The first pattern discussed is authorization in the business logic layer. Delegating authorization to the business logic layer is a golden rule in GraphQL. The business logic layer handles mapping client requests to the application's internal processes. It gathers relevant data, computes fields, and performs transformations. The persistence layer, on the other hand, deals with reading and writing data to the database.

I don't want to deal with this permission system. So that can be what the implications are of doing authorization wrong or even just poorly.

Okay, so getting into the authorization patterns. The first pattern I want to talk about is authorization in the business logic layer. Now, if you're like me, and you're coming to a new topic, probably the first thing you do is just go ahead and Google it. Now you type in GraphQL authorization. The first hit happens to be It has this beautiful conceptual overview on authorization in GraphQL. And it starts with this one kind of golden rule. It says, delegate authorization to the business logic layer. Now, there's potentially two new concepts in this that you haven't thought about before. One, what does it mean to delegate authorization? And two, what is this business logic layer? So the term business logic layer also comes from another page. This page is around thinking in graphs. And it sort of lays out this kind of like architectural diagram of layers of how to think about where GraphQL fits into your application. I have my own version of this diagram so that I can kind of doodle on it and draw things. And, okay, so when I spoke about the layers of your application, what I'm really talking about is a backend application, right? So kind of putting this picture into context, it maybe looks more like this. So first of all, on the left, you maybe have your client. This could be a web browser, this could be a mobile app. And those things are all gonna be making, you know, various requests to your backend, to your backend APIs. Those could be rest requests, those could be GraphQL queries. So the business logic layer, this sort of, this handles that, like, the, you know, mapping those requests to actual things that are going inside your application. For example, if you want to get a specific organization, the business logic would be gathering all the relevant data to return, computing fields, doing transformations, things like that.

Now the bottom, the persistence layer, this is what's like reading and writing data to the database. Okay, for example, coming back to that, user wants to review a specific organization, right, so maybe they do that through a rest request, and in the back end maybe we have some application logic that we wrote to handle that, you know, looks up the organization by that ID from the database. It authorizes, is the user allowed to read that organization, and if not, returns null. Okay, so that's maybe our rest endpoint. Similarly, on the GraphQL side, you know, we now instead have a query for an organization by a specific ID. But again, we write our resolver logic to say, first, you know, look up that organization by that particular ID, authorize, is the user allowed to read that organization and similarly return null. Okay. So far, so good.

3. Authorization in GraphQL: Best Practices

Short description:

We have our rest API, our GraphQL API, and authorization. Duplicating authorization logic across multiple places can lead to inconsistencies and a poor user experience. The solution is to delegate authorization to the business logic layer and handle it there. This ensures consistency and avoids duplicating logic. Additionally, when fetching multiple organizations, it's best to apply authorization logic as a filter at the query level to avoid performance issues and handle unauthorized access.

We have our rest API, we've got our GraphQL API, we have authorization. Doesn't seem too bad. So going back to that original docs page, what it's saying, the problem here is that what you've actually done is you've duplicated this authorization logic across multiple places. And they highlighted this as a bad thing because, okay, in this case we have two reads, two methods and you can't upstate them too bad. But as you start growing, growing your different APIs and endpoints, you now need to keep all of these different authorize statements in sync between these two APIs, the REST and GraphQL.

Now, why that's problematic is if these things fall out of sync, maybe you check for one permission somewhere, in one place, check for a different permission somewhere else, then your application starts behaving differently based on what APIs somebody is using and that can create a really poor user experience. So going back to that diagram, when that Golden Rule said, delegate authorization to the business logic layer, what it's talking about is pushing that authorize down. Don't handle it in those API handlers but instead, push it down, handle it inside the business logic layer. So in my previous example, what that might mean is, in your method to look up the organization by ID, maybe that's where you put that authorize logic. So when you go and fetch that organization, you then check can the user read it or not? Because both the rest and the GraphQL API are both calling the same method, we sort of have a guarantee that they're gonna be in sync. Okay. So there you have it. That's the sort of conceptual theory of authorization in GraphQL. In fact, you don't actually do it in GraphQL. You push it down to the business logic layer and handle it there. So you don't have to repeat that logic multiple times. Actually, that's not just a theory. I think in practice, this is also fantastic advice. I think for a lot of people, this should be the right default option, especially if you have an application, you already have authorization in a lot of places. As you go and start adding those GraphQL endpoints, you don't wanna go and copy-pasting that authorization logic around. It's better that you can just sort of have it defined in one place.

I wanna briefly extend this passing with something else that I think can be super helpful to do. Before, we were getting a specific organization, but what if instead, we were fetching multiple organizations? Suppose we wanna get the first 10 orgs, right? The naive thing to do would be to fetch those organizations and then go through and authorize each one one by one. The reason that's problematic is, one, it can be kind of slow to repeatedly do that authorization. But two, if one of those is not allowed, then what do you do? Do you just only return nine organizations instead of 10? Do you return a null? Do you require the user goes back and fetches more and so on? This can actually be a pretty tricky thing to get right. But again, that theory from before holds really well. You should do this authorization down in that business logic layer. But in practice, how you achieve that is by applying your authorization logic as a filter at the query level. So maybe what you need to do is filter those organizations by all the organizations that the user belongs to. I mean, maybe we've got, like, a list of orgs on the user.

4. Authorization Logic and Query Resolvers

Short description:

When doing query resolvers, a great pattern is to do authorization as part of fetching data from the database. This can be achieved by separating the authorization logic behind a single interface, such as OSO. The alternative version of the diagram could have authorization before the persistence layer, all within the business logic layer.

Now, as that authorization logic gets more complex, you probably want to separate out that logic as well behind a single interface. Say, something they can list all the authorized organization IDs for you, and then you can go and filter the database. And that's the kind of thing you can actually get from sort of modern authorization solutions like OSO. And so the pattern I want you to take away here is that when you're doing your query resolvers, a great pattern to follow is actually doing that authorization as part of, like, fetching the data from the database. Not just for, like, one thing, but also for multiple things. And so maybe an alternative version of the diagram might have that authorized before the persistence layer. I don't know. All part of that business logic layer.

5. Reasons for Authorization in GraphQL

Short description:

The speaker discusses the reasons why some people choose to put authorization logic in the resolver layer in GraphQL. They mention that it can be easier and faster to do so, especially for those who are adopting GraphQL and already have experience with putting authorization in route handling logic for REST endpoints. Another reason is for companies that are fully committed to GraphQL, as it provides an opportunity to do authorization cleanly and take advantage of the benefits it offers. Lastly, defense in depth is highlighted as a strong reason for doing authorization in the GraphQL layer, ensuring that authorization is implemented correctly throughout the backend.

OK. So seems like we've outcovered everything. As we've done, give your time back. You can, you know, go for a walk or something before the next talk.

Not quite. Not quite. So the previous stuff, right? It's all great in theory and actually mostly great in practice, too. When we first started looking at GraphQL authorization a few years ago, this just completely made sense to me. This is great. We'll solve authorization for people with GraphQL and there's nothing for us to do. Actually, it was my co-founder who repeatedly asked me, there must be more we could do for GraphQL authorization. Every time we sort of thought about it, the rationale says we do the business logic layer and that's where we fit anyway. And yet, time we did see people who were doing custom authorization things with GraphQL, they were asking us about integrations and so we wanted to find out what was going on in there. Why was this? And there were kind of three different reasons we saw out there.

So number one, honestly, it's just easier. It's actually a lot easier to not have this rigorous discipline where you have perfectly separate and decoupled your authorization from your resolver handler logic and your persistence layer, and a third one. For a lot of people, they're just trying to move fast, they are adopting GraphQL and they put their authorization in the resolver because it's just easiest to do that way. And there was zero judgment them in there, by the way, because for years, people have been doing this for authorization with REST endpoints, right? They just kind of put it into their route handling logic. They may make middleware, there's many, many different things people do. And so often, that's, that can be the rationale.

The second one I saw is maybe a little bit more principled than that, which is for people who either GraphQL first as a company. They're sort of all in on GraphQL, and so that kind of rationale of like, well, you don't want to duplicate it between GraphQL and REST, that doesn't quite add up for them because they're only using GraphQL anyway. And so that doesn't hold. And we'll see in a second why it can actually be very powerful to do authorization in the GraphQL layer. I think simply from that, for a lot of people, they see it as an opportunity to do authorization very cleanly. And we'll see there's some really great benefits of doing authorization in the GraphQL layer. And so people I think are jumping on that opportunity. I think about that sort of the GraphQL first approach where you're sort of saying you want to do authorization in GraphQL intentionally. I think, finally, and this is always a fantastic reason in authorization, for defense in depth. Right? So it can be hard to know you've done authorization correct in all the right places from all the way throughout your backend, all the different routes you need to handle.

6. Authorization in the GraphQL Layer

Short description:

Having a single place for authorization in either the rest API or the GraphQL API provides comfort and ensures some level of authorization. The speaker discusses doing authorization directly in the GraphQL layer, specifically in the resolver side. They give an example of mutations and how authorization can be implemented in the resolver layer.

And so having like a single place to put it, whether it's the rest API, the GraphQL API, it can kind of give you that comfort of knowing that there is at least some amount of authorization done in one place. So the next pattern I want to talk about is what does it look like to do authorization directly in the GraphQL layer. And so that means, and there's a couple of different ways we could do this. I'm going to talk about sort of the resolver side of things. So suppose we have some mutations. Maybe there's created a repository, open an issue, and so on. And we've implanted resolvers for each of those mutations, right? That looks at the data. And for one of those reasons I mentioned before, we have done authorization here in the resolver layer.

7. Abstracting Authorization Logic

Short description:

It's crucial to abstract authorization behind an API. This centralizes logic, making it easier to manage and debug. The integration layer handles authorization, eliminating the need to worry about it elsewhere.

OK, so there's a couple of things I want to point out around what I have here. So number one, I think it's absolutely crucial that you do, if you're going to do authorization anywhere, that you abstract it away behind an API like this. I really cannot recommend that one highly enough. It lets you keep all your authorization logic in one place, one place to make changes, one place to debug, log, and so on. You'll sort of see throughout this talk, I'm not even going to show you any authorization logic itself. Like, you know, you can do this because you have a role, because here in the integration layer, like, we don't need to worry about that.

8. Custom Directives and Permissions Field

Short description:

Even with a clean authorized call, it can be tedious to ensure correct authorization in every resolver. A pattern to reduce this tedium is to use a custom directive to annotate mutations with required permissions. Doing authorization at the resolver level can work well, but it should be combined with filtering at the database. Another pattern is to extend GraphQL types with a permissions field, allowing front-ends to be permissions-aware without duplicating authorization logic.

OK, so number two, like, even with that API in place, even with this really clean, like, one-line authorized call, it can still be really tedious to go through every single resolver and make sure that you've done authorization correct. You'll probably go around and copy and paste, and you might end up making a mistake.

And so a pattern I've seen emerging to sort of reduce that tedium, to make this a little bit easier and repeatable is to use a custom directive. I'm not going to go deep into the definition of directives and how those work, but suppose that we have this custom check directive, and what this lets you do is annotate your mutations with the permissions you should check. So again, when you create a repository, you should check that the user has create repo permission on the organization.

What's really nice about this approach, if you go down this path, is that your GraphQL schema becomes a single declarative place to map your GraphQL APIs to the permissions you need to access them. And so the takeaway is that doing authorization at the resolver can actually work pretty well. However, remember when with the business logic layer, we had two patterns, that was the single authorized, that was like the query filtering. You're never going to get away from that data filtering piece. You can do it in alternative ways, but you'll never fully get away from it. And so this pattern of doing resolver level authorization should only really be used in combination with, say, filtering at the database. And so in particular, I see this resolver level authorization being really great for mutations. Because those are often ways to have a wide range of different things you can do and different permission checks.

Okay. So I have one final bonus pattern I want to share with you. And it's all about how you can build front-ends that are permissions-aware without needing to duplicate all your authorization logic between your backend and front-end. The gist is basically you can extend your GraphQL types with a permissions field. And that permissions field will contain all the permissions the current user has on that particular resource. And you can see an example of this out in the wild. So, for example, if you go look at the GitHub GraphQL API, when creating for a repository, you can ask for the viewer permissions. And what you'll get back is a string representing the permission level that the user has. And now the general idea is that what a UI can just do, it can take that information, a simple conditional expression to decide whether you should maybe gray out a button, hide a configuration option, hide a tab, things like that.

Now, I find this is a really... I feel this is a very elegant pattern. And in particular, it's very, very nice and easy to express this for GraphQL. Because to implement this, all you're doing is maybe just extending your resolver with a new permissions field. Which you're gonna compute in some completely different way. Because GraphQL allows you to extend your types with other kinds of data this easily, it can be very natural just to inject this extra field into your types. So, the way you might implement this, again, you probably want that abstracted interface. So, something like list actions that can return all the permissions that user has on a particular resource.

9. Authorization Patterns and Exposing Permissions

Short description:

For a simple authorization model, you can check the user's role and return the corresponding permissions. As the authorization logic becomes more complex, existing solutions like OSO can be very helpful. Exposing permissions in the backend helps build UIs that utilize permission data and extend the schema. Three patterns are discussed: data filtering for read-level permissions, using custom directives for mutation permissions, and exposing permissions in the GraphQL schema. If you want to learn more, there are blog posts and technical guides available, and you can also explore the Oso Cloud product for a ready-made solution.

For maybe a simple authorization model, the way you might implement this is maybe check what role the user has and then return the permissions that role has. As the authorization logic gets more complex, this can get a bit more involved, which is where existing authorization solutions like OSO can be really, really helpful.

So, what I'd really love, I'd really love everybody to take this pattern away, because I think it's an incredibly powerful one. You sort of want your backend to stay the source of truth for authorization logic and by sort of exposing permissions in this way, it helps you build really, really great UIs that kind of use that permission data and extend that schema.

Okay, so in summary, right, three patterns. One, doing sort of data filtering for read-level permissions at the business logic layer is a great one to help you sort of centralize that logic in one place. But when you're thinking about doing sort of lots of mutations and trying to figure out what permissions should a mutation check, doing something like a custom directive can be a really nice way to manage that declaratively in your GraphQL schema. And then finally, the pattern that I mentioned around, you know, exposing permissions as part of your GraphQL schema so that UIs can build on top of that, I think can be a really great one to build in applications that are very aware of authorization.

So that's everything I want to speak about. Thanks for listening. If you'd like to learn more about any of these topics, we, you know, a lot of this content was based on a blog post written by a colleague of mine, Patrick, and talks through about these different patterns of authorization in GraphQL. If you're just interested in learning more about authorization, I only just scratched the surface on different kinds of authorization. There's also everything around how to do things like, you know, roles, relationships, attributes in logic modeling, you know, how to structure this across microservices, things like that. We basically took a lot of the thinking we've done on authorization and put them in this vendor-neutral set of technical guides on how to build authorization for your application. And then, finally, you know, if you are looking for a way for someone else to solve this, you know, if you're listening to this talk and you're like, oh, Sam, just make this problem go away for me, well, we have a product called Oso Cloud that will help you with that.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

React Summit 2022React Summit 2022
20 min
Routing in React 18 and Beyond
Concurrent React and Server Components are changing the way we think about routing, rendering, and fetching in web applications. Next.js recently shared part of its vision to help developers adopt these new React features and take advantage of the benefits they unlock.In this talk, we’ll explore the past, present and future of routing in front-end applications and discuss how new features in React and Next.js can help us architect more performant and feature-rich applications.
GraphQL Galaxy 2021GraphQL Galaxy 2021
32 min
From GraphQL Zero to GraphQL Hero with RedwoodJS
We all love GraphQL, but it can be daunting to get a server up and running and keep your code organized, maintainable, and testable over the long term. No more! Come watch as I go from an empty directory to a fully fledged GraphQL API in minutes flat. Plus, see how easy it is to use and create directives to clean up your code even more. You're gonna love GraphQL even more once you make things Redwood Easy!
Vue.js London Live 2021Vue.js London Live 2021
24 min
Local State and Server Cache: Finding a Balance
How many times did you implement the same flow in your application: check, if data is already fetched from the server, if yes - render the data, if not - fetch this data and then render it? I think I've done it more than ten times myself and I've seen the question about this flow more than fifty times. Unfortunately, our go-to state management library, Vuex, doesn't provide any solution for this.For GraphQL-based application, there was an alternative to use Apollo client that provided tools for working with the cache. But what if you use REST? Luckily, now we have a Vue alternative to a react-query library that provides a nice solution for working with server cache. In this talk, I will explain the distinction between local application state and local server cache and do some live coding to show how to work with the latter.
GraphQL Galaxy 2022GraphQL Galaxy 2022
29 min
Rock Solid React and GraphQL Apps for People in a Hurry
In this talk, we'll look at some of the modern options for building a full-stack React and GraphQL app with strong conventions and how this can be of enormous benefit to you and your team. We'll focus specifically on RedwoodJS, a full stack React framework that is often called 'Ruby on Rails for React'.

Workshops on related topic

GraphQL Galaxy 2021GraphQL Galaxy 2021
140 min
Build with SvelteKit and GraphQL
Featured WorkshopFree
Have you ever thought about building something that doesn't require a lot of boilerplate with a tiny bundle size? In this workshop, Scott Spence will go from hello world to covering routing and using endpoints in SvelteKit. You'll set up a backend GraphQL API then use GraphQL queries with SvelteKit to display the GraphQL API data. You'll build a fast secure project that uses SvelteKit's features, then deploy it as a fully static site. This course is for the Svelte curious who haven't had extensive experience with SvelteKit and want a deeper understanding of how to use it in practical applications.

Table of contents:
- Kick-off and Svelte introduction
- Initialise frontend project
- Tour of the SvelteKit skeleton project
- Configure backend project
- Query Data with GraphQL
- Fetching data to the frontend with GraphQL
- Styling
- Svelte directives
- Routing in SvelteKit
- Endpoints in SvelteKit
- Deploying to Netlify
- Navigation
- Mutations in GraphCMS
- Sending GraphQL Mutations via SvelteKit
- Q&A
React Advanced Conference 2022React Advanced Conference 2022
95 min
End-To-End Type Safety with React, GraphQL & Prisma
Featured WorkshopFree
In this workshop, you will get a first-hand look at what end-to-end type safety is and why it is important. To accomplish this, you’ll be building a GraphQL API using modern, relevant tools which will be consumed by a React client.
Prerequisites: - Node.js installed on your machine (12.2.X / 14.X)- It is recommended (but not required) to use VS Code for the practical tasks- An IDE installed (VSCode recommended)- (Good to have)*A basic understanding of Node.js, React, and TypeScript
GraphQL Galaxy 2022GraphQL Galaxy 2022
112 min
GraphQL for React Developers
Featured Workshop
There are many advantages to using GraphQL as a datasource for frontend development, compared to REST APIs. We developers in example need to write a lot of imperative code to retrieve data to display in our applications and handle state. With GraphQL you cannot only decrease the amount of code needed around data fetching and state-management you'll also get increased flexibility, better performance and most of all an improved developer experience. In this workshop you'll learn how GraphQL can improve your work as a frontend developer and how to handle GraphQL in your frontend React application.
React Summit 2022React Summit 2022
173 min
Build a Headless WordPress App with Next.js and WPGraphQL
In this workshop, you’ll learn how to build a Next.js app that uses Apollo Client to fetch data from a headless WordPress backend and use it to render the pages of your app. You’ll learn when you should consider a headless WordPress architecture, how to turn a WordPress backend into a GraphQL server, how to compose queries using the GraphiQL IDE, how to colocate GraphQL fragments with your components, and more.
GraphQL Galaxy 2020GraphQL Galaxy 2020
106 min
Relational Database Modeling for GraphQL
In this workshop we'll dig deeper into data modeling. We'll start with a discussion about various database types and how they map to GraphQL. Once that groundwork is laid out, the focus will shift to specific types of databases and how to build data models that work best for GraphQL within various scenarios.
Table of contentsPart 1 - Hour 1      a. Relational Database Data Modeling      b. Comparing Relational and NoSQL Databases      c. GraphQL with the Database in mindPart 2 - Hour 2      a. Designing Relational Data Models      b. Relationship, Building MultijoinsTables      c. GraphQL & Relational Data Modeling Query Complexities
Prerequisites      a. Data modeling tool. The trainer will be using dbdiagram      b. Postgres, albeit no need to install this locally, as I'll be using a Postgres Dicker image, from Docker Hub for all examples      c. Hasura
GraphQL Galaxy 2021GraphQL Galaxy 2021
48 min
Building GraphQL APIs on top of Ethereum with The Graph
The Graph is an indexing protocol for querying networks like Ethereum, IPFS, and other blockchains. Anyone can build and publish open APIs, called subgraphs, making data easily accessible.

In this workshop you’ll learn how to build a subgraph that indexes NFT blockchain data from the Foundation smart contract. We’ll deploy the API, and learn how to perform queries to retrieve data using various types of data access patterns, implementing filters and sorting.

By the end of the workshop, you should understand how to build and deploy performant APIs to The Graph to index data from any smart contract deployed to Ethereum.