Authorization Patterns in GraphQL

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.

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 GraphQL.org. 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 GraphQL.org 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.

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 GraphQL.org 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.

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.

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.

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.

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.

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.

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.