DEV Community: Sam Gwilym

Modelling Authorisation in GraphQL

Sam Gwilym — Mon, 11 Mar 2019 16:25:37 +0000

In this article, we'll explore how to expose different levels of information on a GraphQL schema depending on who makes the request, i.e. authorisation, using only GraphQL's built-in schema definition capabilities.

By the end, we'll have an intelligent, authorised type that can be reused at any level of the graph with no extra effort.

Authorisation in GraphQL is often treated as a failure state, either reporting failed authorisations in the GraphQL response's errors field, or in the worst case throwing the entire response altogether.

But returning a different kind of response based on who asks for it isn't exceptional. Just because we're not allowed to see everything doesn't mean we shouldn't see anything, and that should be reflected in our schemas. GraphQL gives us everything we need to express the different layers of access we'd like to expose.

Users Bare All

Let's start with a service where we can query information about its users:

Schema

type Query {
  users: [User!]!
}

type User {
    nickname: String!
    email: String!
    billingAddress: String!
}

Query

{
    users {
        nickname
        email
        billingAddress
    }
}

Response

{
    "data": {
        "users": [
            {
                "nickname": "Jenny Me",
                "email": "jenz@itsame.com",
                "billingAddress": "123 Open Lane"
            },
            {
                "nickname": "Freddy Friend",
                "email": "fred@buds.com",
                "billingAddress": "22a Sharing Avenue"
            },
            {
                "nickname": "mr. private",
                "email": "bill@respectmysolitude.biz",
                "billingAddress": "36bis Ivory Tower"       
            }
        ]
    }
}

Not good: there’s information that both we as developers and our users clearly wouldn't want anyone to be able to query for, like their email or billingAddress.

How can we withhold that information from unauthorised users?

Users with nullable fields

The first approach we could take is to detect unauthorised operations during field resolution.

// As an Apollo Server style resolver
User: {
    // ...
    billingAddress: (user, args, ctx) => {
        if (user.id === ctx.currentUser.id) {
            return user.billingAddress;
        }
        return null;
    }
    // ...
}

Now if someone requests a field they're not allowed to see, they'll get null instead.

Schema

type Query {
  users: [User!]!
}

type User {
    nickname: String!
    # These fields are all nullable now
    email: String
    billingAddress: String
}

Query

{
    users {
        nickname
        email
        billingAddress
    }
}

Response

{
    "data": {
        "users": [
            {
                "nickname": "Jenny Me",
                "email": "jenz@itsame.com",
                "billingAddress": "123 Open Lane"
            },
            {
                "nickname": "Freddy Friend",
                "email": "fred@amicus.com",
                "billingAddress": null
            },
            {
                "nickname": "mr. private",
                "email": null
                "billingAddress": null  
            }
        ]
    }
}

We’re logged in as Jenny Me, so we can see all of our information, including billingAddress. The second user, Freddy Friend is, well, our friend, so we can see their email too. The third user, mr. private, wants nothing to do with us, so we're only able to see their nickname.

Here we've managed to only expose the information Jenny Me is allowed to see, but this rough approach to schema-based authorisation has many downsides.

The first is that by making everything nullable, your clients can’t ensure the presence of data even for situations where they’re pretty sure it should be available: imagine a BillingAddressForm component which is expecting a User, which strictly speaking may or may not have a billingAddress. Clients now need to handle all the cases where a field could have a null value.

The second downside is that this approach burdens your schema’s field resolvers with authorisation logic. Resolvers which only had to return a value now need to have all kinds of checks inside them.

Pretty soon these two issues would make both making our client and server codebase far more laborious to work with.

Many kinds of User

What we really want is to be able to know that we’re going to get the data we’re asking for – not just guess from the presence of absence of data.

In the case of our user type, we have three levels of authorisation:

Public information: Anyone can see users’ nicknames
Friends-only information: Friends can also see each other’s email.
Current user only information: Only the user themselves should be able to get their own billingAddress.

Querying for a user can give us three different kinds of results, so let’s model that in GraphQL with a union type:

Schema

type Query {
  users: [User!]!
}

type User {
    nickname: String!
}

type FriendUser {
    nickname: String!
    # Email isn't nullable anymore!
    email: String!
}

type CurrentUser {
    nickname: String!
    email: String!
    billingAddress: String!
}

# Wrap all our users in a User union type
type User = PublicUser | FriendUser | CurrentUser

Query

{
    users {
        __typename
        ... on PublicUser {
            nickname
            # PublicUser has no email field, so you can't even request it!
        }
        ... on FriendUser {
            nickname
            email
        }
        ... on CurrentUser {
            nickname
            email
            billingAddress
        }
    }
}

Response

{
    "data": {
        "users": [
            {
                "__typename": "CurrentUser",
                "nickname": "Jenny Me",
                "email": "jenz@itsame.com",
                "billingAddress": "123 Open Lane"
            },
            {
                "__typename": "FriendUser",
                "nickname": "Freddy Friend",
                "email": "fred@amicus.com",
            },
            {
                "__typename": "PublicUser",
                "nickname": "mr. private",
            }
        ]
    }
}

This improves on our previous nullable approach in a number of ways.

Now when we query our users field, we can be certain that fields like email or billingAddress will return a result – no more checking for null in our client code.

Because we have different types for each kind of User returned, we can also easily make our clients serve different UIs just by checking the typename:

const UserDescription = ({user}) => {
    if (user.__typename === "CurrentUser") {
        return <div>Hey, it's you!</div>;
    } else if (user.__typename === "FriendUser") {
        return <div>`It's your friend ${user.nickname}, email them at ${user.email}!`</div>
    } else {
        return <div>`Someone called ${user.nickname}.`</div>
    }
}

We've also removed most cases where we'd to put authorisation checks inside of our field resolvers anymore — instead we check for which kind of result to return in our union type’s resolve type method:

// In an Apollo Server style resolvers file
User: {
    resolveType: (user, args, ctx) => {
        if (user.id === ctx.currentUser) {
            return "CurrentUser";
        } else if (ctx.currentUserHasFriend(user.id)) {
            return "FriendUser"
        }
        return "PublicUser"
    }
}

But, again, this solution is not going to scale well.

You may have noticed the repetition in our different user types:

type User {
    nickname: String!
}

type FriendUser {
    nickname: String!
    email: String!
}

type CurrentUser {
    nickname: String!
    email: String!
    billingAddress: String!
}

This isn’t only undesirable because of the repetition, but because every addition, removal or change to these fields needs to be coordinated between all of our types. It would cause a lot of confusion if you renamed nickname to name, but only on PublicUser. What if we had eight levels of authorisation, or these types were split up into different files where a big team wouldn’t necessarily know who was changing what?

Adding to the problems, querying these types is not very ergonomic:

{
    users {
        __typename
        ... on PublicUser {
            nickname
        }
        ... on FriendUser {
            nickname
            email
        }
        ... on CurrentUser {
            nickname
            email
            billingAddress
        }
    }
}

Again, the repetition is tedious (and that with only three types), but we could also run into trouble if we’re writing client code that expects the presence of these fields on all of our User types – a risk that grows with the number of fields on our types.

Users with interfaces

It would be good if we could make our different User types promise that they'll definitely have certain fields. Fortunately we can do this with GraphQL interfaces.

Let’s create an interface for each level of access we want to grant, and assign them to their relevant types:

interface PublicUserInfo {
    nickname: String!
}

interface FriendInfo {
    email: String!
}

interface PrivilegedInfo {
    billingAddress: String!
}

type User implements PublicUserInfo {
    nickname: String!
}

type FriendUser implements PublicUserInfo & FriendInfo {
    nickname: String!
    # If the nickname were missing here GraphQL would tell us about it.
    email: String!
}

type CurrentUser implements PublicUserInfo & FriendInfo & PrivilegedInfo {
    nickname: String!
    email: String!
    billingAddress: String!
}

type User = User | FriendUser | CurrentUser

Now if we add, remove or change a field, that change will be expected in all of our different types, and GraphQL will warn us which types are not fulfilling these interfaces.

This change also means we can rewrite our queries in a more ergonomic fashion:

{
    users {
        __typename
        # You can write fragments for interfaces, cool!
        ... on PublicInfo {
            nickname
        }
        ... on FriendInfo {
            email
        }
        ... on PrivilegedInfo {
            billingAddress
        }
    }
}

And the response, again:

{
    "data": {
        "users": [
            {
                "__typename": "CurrentUser",
                "nickname": "Jenny Me",
                "email": "jenz@itsame.com",
                "billingAddress": "123 Open Lane"
            },
            {
                "__typename": "FriendUser",
                "nickname": "Freddy Friend",
                "email": "fred@amicus.com",
            },
            {
                "__typename": "PublicUser",
                "nickname": "mr. private",
            }
        ]
    }
}

Users everywhere

By combining an authorised union type with matching interfaces for each of its members, we've gained the following:

Users only get the information they're authorised to receive.
Requested fields always return the data we expect, so no having to check for null.
We've been able to move many authorisation checks from field resolvers to the union type resolver. This effect can be total for authorisation checks that depend on a top-level value, like the current user (thanks to Andrew Ingram for pointing out that this doesn't totally obviate the need for auth checks in field resolvers).
Trivial to determine the level of authorisation for any returned type via __typename.
Confidence that our types will have common sets of fields that return the same type of data – GraphQL will ensure it through our interfaces.

The combination of multiple interface and type definitions may look like a lot of boilerplate, but it saves a lot of lines of code elsewhere on the GraphQL server, and creates an excellent experience for the clients querying it, especially if types are being used.

Best of all, our User type can be used anywhere in our schema, without having to write any new auth code. Imagine if we wanted to add a new friends field to PublicInfo:

Schema

interface PublicUserInfo {
    nickname: String!
    friends: [User!]!
}

interface FriendInfo {
    email: String!
}

interface PrivilegedInfo {
    billingAddress: String!
}

type User implements PublicUserInfo {
    nickname: String!
}

type FriendUser implements PublicUserInfo & FriendInfo {
    nickname: String!
    # If the nickname were missing here GraphQL would tell us about it.
    email: String!
}

type CurrentUser implements PublicUserInfo & FriendInfo & PrivilegedInfo {
    nickname: String!
    email: String!
    billingAddress: String!
}

type User = User | FriendUser | CurrentUser

Query

{
    users {
        __typename
        ... on PublicInfo {
            nickname
            friends {
                __typename
                ... on PublicInfo {
                    nickname
                }
            }
        }
        ... on FriendInfo {
            email
        }
        ... on PrivilegedInfo {
            billingAddress
        }
    }
}

Response

{
    "data": {
        "users": [
            {
                "__typename": "CurrentUser",
                "nickname": "Jenny Me",
                "email": "jenz@itsame.com",
                "billingAddress": "123 Open Lane"
                "friends": [
                    {
                        "__typename": "FriendUser",
                        "nickname": "Freddy Friend",
                    }
                ]
            },
            {
                "__typename": "FriendUser",
                "nickname": "Freddy Friend",
                "email": "fred@amicus.com",
                "friends": [
                    {
                        // Hey, we could render a little crown over our name in Freddy's friend list!
                        "__typename": "CurrentUser",
                        "nickname": "Jenny Me",
                    }
                ]
            },
            {
                "__typename": "PublicUser",
                "nickname": "mr. private",
                "friends": []
            }
        ]
    }
}

The only code that had to be added for this is a resolver for the friends field on PublicInfo – and no authorisation code would be needed.

This approach can be applied to any kind of type, not just Users: Events, Tasks, Recipes. All the same principles apply. Hopefully this pattern can help you make your schema even more of a pleasure to work with.

How far can Prisma take you? (in February 2019)

Sam Gwilym — Fri, 08 Feb 2019 11:41:14 +0000

There comes a point during a solo project where you need to work with something you’re just not that good at. In my case, that’s databases. I had two options:

A. Do the right thing and finally learn SQL
B. Remain blissfully ignorant and use something that uses my existing knowledge and allows me to get on with it.

The last few years I’ve worked a lot with GraphQL clients and APIs. Prisma is a tool that provides a way to turn a bit of GraphQL SDL like this:

type User {
    id: ID! @unique
    name: String!
    email: String!
    posts: [Post!]!
    friends: [User!]!
}

type Post {
    id: ID! @unique
    title: String!
    body: String!
    isDraft: Boolean!
    author: User!
}

into a running database which you can read/write to in your own apps like this:

let newUser = prisma.createUser({
  name: "Sally Moobles",
  email: "sally@moobleit.biz",
});

let newPost = prisma.createPost({
  title: "My Great Post",
  body: "I'll finish this later…",
  isDraft: true,
  author: {
    connect: {
      id: newUser.id,
    }
  }
});

From writing a single SDL you get a database and a client to read and write to it from. It can’t be overstated how cool this is! It works as advertised — you can go from nothing to ORM in a very short space of time, have a choice of database technologies to choose from (e.g. Postgres), and the generated clients are great in combination with a language like Typescript where you can get autocompletion for all the different operations. This is going to be huge.

But this post is about Prisma as of February 2019, and how far it can take you now. Below are a few reasons which prevent it from being something I’d want to take into a production environment today.

No data migrations

Prisma will automatically migrate your database when you change your SDL and run prisma deploy. But what it doesn’t know how to do is migrate data. This means that non-trivial schema changes, such as creating a new required field or changing a field type, have to be handled manually. There are no Rails-esque up or down migrations which tell Prisma what data should look like in the next schema. In the case of a new required field you would first create the field as optional, fill in all the data using a script, and then flip on the required flag and redeploy.

When you’re working on something alone with dummy data this is… bearable. Just. But how can this approach possibly work with a team of people, working on different branches, deployed to different environments? How do you do CI? The answer: very tediously and slowly.

There is an issue on migrations which has been marked stale as of a month ago. The Prisma website suggests that in the future, there will be a better system. When is it coming? What should you do now instead? It’s really not very clear.

And this leads into the other biggest problem I think Prisma has right now:

Support / Communication problems

It’s hard to know what the roadmap is for Prisma, what their priorities in terms of features are, or whether the features many people are asking for are considered important. There are lots of issues which offer specs for new features, but which have not been updated for a long time.

There’s no doubt that the Prisma team is working hard, but the lack of regular communication on their work and plans inevitably affects your confidence as an end user. It makes me think, well this is fun but I am probably going to have to do this the old fashioned way eventually.

They also seem to have a bit of a problem with support. Because Prisma positions itself as an easy way to do something, it attracts a lot of beginners — a great thing — who ask a lot of questions. On their Slack, forums and Github it looks like most of these questions go unanswered. In the past Prisma had someone dedicated to support who left. They should pay whoever does that job next very well!

A non-exhaustive list of smaller things I bumped into while working on my project

Non-trivial unique constraints. Using the SDL you can specify that certain fields (e.g. User’s emails) should be unique, but you can’t do things like say all Post titles should be unique within the context of their user. This will apparently be addressed by an enigmatic Datamodel v2.
No case-insensitive search for text fields
Exposing connections. Connections are a spec for exposing long lists of data which you’d like to paginate through or only capture a small part of. Exposing connections retrieved from Prisma to your own client-facing GraphQL API requires some weird workarounds.
Using the generated Prisma client with Typescript is great but figuring out how to use it with Javascript is painful. The method names are generated from the names of your fields in your SDL so you have to figure out what the names are and what kind of arguments they take by yourself. The arguments especially can be very, very deep and are easy to mess up.

Finally

The reason I’m writing this is because I want Prisma to be the only thing I need to use so badly. The points above are why I don’t think I can do that right now. But there are a lot of reasons to believe it’ll get there.

But man, waiting sucks.

Programming robs us of our spaces. Dynamicland could give them back.

Sam Gwilym — Wed, 03 Jan 2018 11:01:38 +0000

Returning from a short break from programming brings home how much work it can be: languages, libraries, techniques, all with their own tools and communities, all moving through stages of development or abandonment. For most programmers, working within these worlds means spending many hours a day looking at a jumble of terminal windows, text editors, documentation, and team chat.

It’s hard not to feel like a head in a jar. The world of the computer ends at the edge of the screen, and everything within those edges has the designed assumption that only one person is using it at a time. We interact with this solipsistic world with mice and keyboards that at most use just our fingers. A further indignation is that using a computer requires that you be always be stationary: you can sit, recline or stand, but that’s kind of it. Some bravely try to walk and use their phone at the same time, but lose the ability to be a convincing part of the real world and walk into people, lampposts, and busy roads.

This is all very frustrating, as there are many rewards unique to programming: collaborating with others in a field of ideas, having the strange thrill of seeing something work for the first time, the quiet satisfaction of having refactored some chthonic, untamed part of a codebase — these are all things that make us put up with the obtuse environment we work in.

But environment is a generous word for where we spend our working hours: it suggests a spacious place with many interesting things, shared by many people. It could not be further from reality. Sharing these screens and the worlds in them with others is an exercise in frustration, and we’ve come to accept that to get any real work done we need to each have our own screen, and keep each other abreast of our progress after the fact. We collaborate mainly by assessing additions and deletions of source code, long after the thoughts have been thunk. Instead of being teammates, we are archeologists of each other’s brains. The height of modern remote collaboration is broadcasting what you see on your screen and letting others take control of your mouse.

Don’t get me wrong: I’m not ungrateful for these technologies, and use them daily. But peering over my computer display at my studio-mates (non-programmers all), I begin to feel grateful for these tools in the same way someone with a gateless fence is grateful to have a ladder. I’d watch them gather around a large table, their day’s work in front of them: recently manufactured materials, photos and prints strewn over the table, pens, pencils, rulers. They’d pose their problems physically in front of them on the table’s surface, lifting them in their hands, collaborating with a material and human directness which, when my eyes refocused on the screen in front of me, made the all those tiny windows seem a little absurd.

The same sort of feeling would come over me when — peering over the screen again — I’d spy on one of my friends working alone, carving wood. I’d take in the workspace they’d built around them, the ad-hoc placement of their tools, the positioning of their work in progress next to their sketches, tools and materials being combined in unexpected ways. You could see all the possibilities and progress at once, in the context of the task at hand.

It was then that I decided that programming is difficult enough without having to do all of it exclusively within the confines of a computer screen. Why should we accept what programming has to offer at the expense of our environments, the natural way we interact with other people, of our own bodies?

Toward the end of 2017 I began to see a trickle of images and videos shared by programmers I like. In these videos, you’d see many people in a strange, workshop-like space pushing around bits of paper with coloured circles on them, and ghost-like images would follow the paper around, and change as it was moved. What I was looking at was so strange that at first I couldn’t really tell what the videos were meant to show.

// Detect dark theme var iframe = document.getElementById('tweet-906641217089187840-647'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=906641217089187840&theme=dark" }

But with more time — and more videos — it all started to become a bit clearer.

// Detect dark theme var iframe = document.getElementById('tweet-906761882307981317-58'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=906761882307981317&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-906675494422167552-844'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=906675494422167552&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-907276592581193728-646'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=907276592581193728&theme=dark" }

These are all videos of people programming, together, in a physical space, using a physical medium. It is called Dynamicland, and it is a building in Oakland, California.

// Detect dark theme var iframe = document.getElementById('tweet-907121507196837889-510'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=907121507196837889&theme=dark" }

I didn’t know how much I wanted to be in this world until I saw it. I’ve begun to even more hungrily covet the workspaces of my neighbours — illustrators, woodworkers, cooks — envious of their physicality, of being able to call someone over, point to a table somewhere and say “this is what I’ve been working on — do you have any idea how I could fix this bit?”. A workshop for programmers.

It is also clearly more than that, a project that aims to bring the dynamism of programming to those who cannot not tolerate the environment that programming currently demands. The current situation has made it so that programming is a profession today as being a scribe was in ancient Egypt. “Pens, scissors, and staplers are genuinely powerful tools here”, they say, and I can easily believe it, having used the command line. Imagining this system in classrooms, libraries and museums is in many way easier that imagining how this could be used for a full-blooded programming environment. It is easy to cynically wonder how being able to use a stapler really benefits the long-lived libraries, tools, and methods that we rely on to get our work done today. But that is thinking of it in the way that we’d think of a new text editor or versioning system: this computer changes how people work together, and that will have far more of an effect than any dozen new tools could.

It’s also worth comparing to other visions of computing in the future: VR tries to take the solipsistic computer all the way to its extreme conclusion by fooling your eyes and ears — not always successfully — and replacing your real environment with a virtual one. It’s clearly something fun, but has had trouble breaking out of being more than a carnival attraction, and using it as a full-time computer seems like an actual dystopian nightmare. Many consider augmented reality a more exciting prospect, and this requires a headset which superimposes simulated elements onto what you can really see, and in some ways this is like Dynamicland. But you need a headset for AR, and everyone not wearing one just sees a person with weird glasses interacting with thin air. Dynamicland, in contrast, requires an entire building, but with the benefit that everyone present is part of the same world, only needs what they were born with to be part of it, and interacts with real things with mass and texture.

There is also the difference of institution: both VR and AR are embodied by private companies aiming to sell headsets, build marketshare and a new ecosystem with it. Dynamicland is backed by a non-profit organisation and solicits donations and research funding. They see their idea in the context of decades rather than product cycles, and use the Internet’s development as a model. Whichever of these futures you think is most likely, there is undoubtedly a long way to go before something like this could replace the the isolated desks and computers that we use now. But it’s worth entertaining taking that long road, especially when you imagine having to sit at a desk, navigating through a flat world for the rest of your working days.

From here — the very beginning of 2018, the Netherlands — Dynamicland seems a very long way away. It will be some time before I get to experience something like it for myself. But when I selfishly imagine myself having the option to work in a space that looks more than a workshop than a terminal, or (unselfishly) imagine future children having a classroom that looks anything like this — well, I can’t help but write something about it even if it only helps to usher in that future by a minute or two.