Developer Products

Roy Derks


There are many different ways to handle authentication in GraphQL, but one of the most common is to use OAuth 2.0 - and, more specifically, JSON Web Tokens (JWT) or Client Credentials.

In this blog post, we'll look at how to use OAuth 2.0 to authenticate GraphQL APIs using two different flows: the Authorization Code flow and the Client Credentials flow. We'll also look at how to use StepZen to manage authentication.

## What is OAuth 2.0?

But first, what is OAuth 2.0? OAuth 2.0 is an open standard for authorization that allows one application to let another application access certain parts of a user's account without giving away the user's password. There are different ways to set up this type of authorization, called "flows", and it depends on the type of application you are building.

For example, if you're building a mobile app, you will use the "Authorization Code" flow. This flow will ask the user to permit the app to access their account, and then the app will receive a code to use to get an access token (JWT). The access token will allow the app to access the user's information on the website. You might have seen this flow when you log in to a website using a social media account, such as Facebook or Twitter.

Another example is if you're building a server-to-server application, you will use the "Client Credentials" flow. This flow involves sending the website's unique information, like a client ID and secret, to get an access token (JWT). The access token will allow the server to access the user's information on the website. This flow is quite common for APIs that need to access a user's data, such as a CRM or a marketing automation tool.

Let's have a look at these two flows in more detail.

## Authorization Code Flow (using JWT)

The most common way to use OAuth 2.0 is with the Authorization Code flow, which involves using JSON Web Tokens (JWT). As mentioned above, this flow is used when you want to build a mobile or web application that needs to access a user's data from a different application.

For example, if you have a GraphQL API that allows users to access their data, you can use a JWT to verify that the user is authorized to access the data. The JWT could contain information about the user, such as the user's ID, and the server can use this ID to query the database and return the user's data.

![Flow to get JWT](/images/blog/validating-jwt-tokens/flow.png)

You would need a frontend application that can redirect the user to the authorization server and then redirect the user back to the frontend application with the authorization code. The frontend application can then exchange the authorization code for an access token (JWT) and then use the JWT to make requests to the GraphQL API.

The JWT can be sent to the GraphQL API in the `Authorization` header:

```graphql
curl https://USERNAME.stepzen.net/api/hello-world/__graphql \
   --header "Authorization: Bearer JWT_TOKEN" \
   --header "Content-Type: application/json" \
   --data-raw '{
     "query": "query { me { id username } }"
   }'
```

And the server can use the JWT to verify that the user is authorized to access the data.

The JWT can also contain information about the user's permissions, such as whether they can access a specific field or mutation. This is useful if you want to restrict access to specific fields or mutations or if you want to limit the number of requests a user can make. But we'll look at this in more detail after discussing the Client Credentials flow.

## Client Credentials Flow

The Client Credentials flow is used when you want to build a server-to-server application, like an API, that needs to access information from a different application. It also relies on JWT.

As mentioned above, this flow involves sending the website's unique information, like a client ID and secret, to get an access token. The access token will allow the server to access the user's information on the website. Unlike the Authorization Code flow, the Client Credentials flow doesn't involve a (frontend) client. Instead, the authorization server will directly communicate with the server that needs to access the user's information.

![Client Credentials Flow](https://images.ctfassets.net/cdy7uua7fh8z/2waLvaQdM5Fl5ZN5xUrF2F/7a6750b784493042d073de709cccd843/Client_Credentials_flow.png)
*Image from [Auth0](https://auth0.com/docs/flows/concepts/client-credentials)*

The JWT can be sent to the GraphQL API in the `Authorization` header, in the same way as for the Authorization Code flow.

In the next section, we'll look at how to implement both the Authorization Code flow and the Client Credentials flow using StepZen.

## Using StepZen to Manage Authentication

By default, StepZen uses API Keys to authenticate requests. This is a developer-friendly way to authenticate requests that don't require an external authorization server. But if you want to use OAuth 2.0 to authenticate requests, you can use StepZen to manage authentication. Similar to how you can use StepZen to build a GraphQL schema for all your data in a declarative way, you can also manage authentication declaratively.

### Implement Authorization Code Flow (using JWT)

To implement the Authorization Code flow, you must set up both a (frontend) client and an authorization server. You can use an existing authorization server, such as Auth0, or build your own. 

> You can find a complete example of using StepZen to implement the Authorization Code flow in the [StepZen GitHub repository](https://github.com/stepzen-dev/examples/tree/main/with-auth0/).

StepZen can validate the JWTs generated by the authorization server and send them to the GraphQL API. You only need the authorization server to validate the user's credentials to generate a JWT and StepZen to validate the JWT.

Let's have another look at the flow we discussed above:

![Flow to get JWT](/images/blog/validating-jwt-tokens/flow.png)

In this flow diagram, you can see that the frontend application redirects the user to the authorization server (from Auth0) and then turns the user back to the frontend application with the authorization code. The frontend application can then exchange the authorization code for a JWT and then use that JWT to make requests to the GraphQL API. 

StepZen will validate the JWT that is sent to the GraphQL API in the `Authorization` header by configuring the JSON Web Key Set (JWKS) endpoint in the StepZen configuration in the `config.yaml` file in your project:

```yaml 
deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
```

The JWKS endpoint is a read-only endpoint that contains the public keys to verify a JWT. The public keys can only be used to validate the tokens, as you would need the private keys to sign the tokens, which is why you need to set up an authorization server to generate the JWTs.

You can then limit the fields and mutations a user can access by adding [Access Control rules](/docs/access-control/access-control-rules) to the GraphQL schema. For example, you can add a rule to the `me` query to only allow access when a valid JWT is sent to the GraphQL API:

```yaml
deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
access:
  policies:
    - type: Query
      rules:
        - condition: '?$jwt' # Require JWT
          fields: [me] # Define fields that require JWT
```

This rule only allows access to the `me` query when a valid JWT is sent to the GraphQL API. If the JWT is invalid, or if no JWT is sent, the `me` query will return an error.

Earlier, we mentioned that the JWT could contain information about the user's permissions, such as whether they can access a specific field or mutation. This is useful if you want to restrict access to specific fields or mutations or if you want to limit the number of requests a user can make.

You can add a rule to the `me` query to only allow access when a user has the `admin` role:

```yaml
deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
access:
  policies:
    - type: Query
      rules:
        - condition: '$jwt.roles:String has "admin"' # Require JWT
          fields: [me] # Define fields that require JWT
```

To learn more about implementing the Authorization Code Flow with StepZen, look at the [Easy Attribute-based Access Control for any GraphQL API article](/blog/simple-abac-for-graphql) on the StepZen blog.

### Implement Client Credentials Flow

You will also need to set up an authorization server to implement the Client Credentials flow. But instead of redirecting the user to the authorization server, the server will directly communicate with the authorization server to get an access token (JWT).

> You can find a complete example for implementing the Client Credentials flow in the [StepZen GitHub repository](https://github.com/stepzen-dev/examples/tree/main/with-auth0/).

First, you must set up the authorization server to generate the access token. You can use an existing authorization server, such as Auth0, or build your own.

In the `config.yaml` file in your StepZen project, you can configure the authorization server to generate the access token:

```yaml
# Add the JWKS endpoint
deployment:
  identity:
    jwksendpoint: 'https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json'

# Add the authorization server configuration
configurationset:
  - configuration:
      name: auth
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      audience: YOUR_AUDIENCE
```

The `client_id`, `client_secret` and `audience` are required parameters for the authorization server to generate the access token (JWT). The `audience` is the API's identifier for the JWT. The `jwksendpoint` is the same as the one we used for the Authorization Code flow.

In a `.graphql` file in your StepZen project, you can define a query to get the access token:

```graphql
type Query {
  token: Token
    @rest(
      method: POST
      endpoint: "YOUR_AUTHORIZATION_SERVER/oauth/token"
      postbody: """
      {
        "client_id": "{{ .Get "client_id" }}",
        "client_secret": "{{ .Get "client_secret" }}",
        "audience": "{{ .Get "audience" }}",
        "grant_type": "client_credentials"
      }
      """
    )
}
```

The `token` mutation will request the authorization server to get the JWT. The `postbody` contains the parameters that are required by the authorization server to generate the access token.

You can then use the JWT from the response on the `token` mutation to request the GraphQL API, by sending the JWT in the `Authorization` header.

But we can do better than that. We can use the `@sequence` custom directive to pass the response of the `token` mutation to the query that needs authorization. This way, we don't need to send the JWT manually in the `Authorization` header on every request:

```graphql
type Query {
  me(access_token: String!): User
    @rest(
      endpoint: "YOUR_API_ENDPOINT"
      headers: [{ name: "Authorization", value: "Bearer $access_token" }]
    )
  profile: User @sequence(steps: [{ query: "token" }, { query: "me" }])
}
```

The `profile` query will first request the `token` query to get the JWT. Then, it will send a request to the `me` query, passing along the JWT from the response of the `token` query as the `access_token` argument.

As you can see, all configuration is set up in a single file, and you can use the same configuration for both the Authorization Code flow and the Client Credentials flow. Both are written declarative, and both use the same JWKS endpoint to request the authorization server to verify the tokens.

## What's next?

In this blog post, you learned about common OAuth 2.0 flows and how to implement them with StepZen. It's important to note that, as with any authentication mechanism, the details of the implementation will depend on the application's specific requirements and the security measures that need to be in place.

StepZen GraphQL APIs are default protected with an API key but can be configured to use any authentication mechanism. We'd love to hear what authentication mechanisms you use with StepZen and how you use them. Ping us on [Twitter](https://twitter.com/stepzen_dev) or join our [Discord community](https://discord.gg/9k2VdPn2FR) to let us know.


There are many different ways to handle authentication in GraphQL, but one of the most common is to use OAuth 2.0 - and more specifically JSON Web Tokens (JWT) or Client Credentials.


Authenticating GraphQL APIs with OAuth 2.0

Customer Success

Carlos Eberhardt

Cofounder & CTO

Sridhar Rajagopalan



We recently read this as the lead-in to an article on API security:

> ***So you’ve built out your GraphQL API, and you’re almost ready to deploy it to production. Time to talk security!***

**We disagree!** As part of our [GraphQL Architecture Master Class series](/blog/graphql-masterclass-build-faster-run-better) > [How to Reduce Security Risks in API Architectures](https://youtu.be/2VUOzbiY9sI), we explored security risks in API architectures and a fundamental premise is to avoid thinking like this. We believe that it's just a bad idea to design your API first and your security as an afterthought. Read on for why we hold that point of view and more.


# REST vs. GraphQL API security

 You know how to secure REST endpoints. But are you worried about securing GraphQL? GraphQL has an entire graph of capability underneath one endpoint; REST APIs have different endpoints for different capabilities, and developers are familiar with protecting those endpoints using standard things.
- Authentication and authorization are important
- Since calls are over HTTP; worrying about standard HTTP attacks matters
- Things like cross-site scripting are relatively easy to understand and well known

![REST vs. GraphQL API security](/images/blog/masterclass/security-masterclass-rest-v-graphql.png)

GraphQL is more powerful. It enables you to ask for exactly what you need, and get back tailor made information. Everything that you used to expose under many APIs is now available
under a single endpoint. The request URL is always the same -  it's what's in the request payload that must be managed. This leads to a belief among some, _mistaken, in our view,_ that GraphQL is inherently less secure.

## GraphQL: Security opportunity or a great risk?
Being careless with one endpoint that does everything can be a risk. Hence, being thoughtful from the start and having a mindset that designs your API for security eliminates a bunch of “after-the-fact” work - and, importantly, makes security an intentional design choice rather than an retrofit afterthought.

It used to be that security was done after the API - “Okay, now the API does what I want, so  I need to secure it.” Instead, you should design your API and your security schema simultaneously. That is, you can now have a security model that you can reason about across all of your assets consistently instead managing multiple possibly inconsistent fragments which are hard to keep aligned with each other. If you do this well, you can end up with a more maintainable, more reusable, and not surprisingly, a more secure system.

## API Security Concerns

API Security is reasonably well-understood and supported by relatively mature products. This should be a cause for comfort, because these work well and tend to be hardened and bug free. Things you should know and understand are:

- Authentication / Authorization (don't confuse the two!)
- Network attacks - what happens if someone gets through the firewall? It's good to have some redundant measures in place.
- OWASP - the organization has been doing great work for a long time, helping us understand the types of attacks we're seeing and how to mitigate those.

As you transition to GraphQL, our best recommendation is not to throw away all the best practices and security considerations you currently use:

- Continue best practices around XSS, input validation, SQL injection, etc.
- Infrastructure: Don't throw away your NGINX proxy, etc.
- Consider API management tools - some are starting to provide GraphQL-specific capabilities.
- Test, Monitor, and Automate!

# GraphQL Security

So let's get to specific concerns about GraphQL API security. We'll think about the considerations and our perspective and recommendations in three dimensions:

- Information leakage
- Request complexity
- Authorization

## Information Leakage

We think about information leakage a little through the lens of “security through obscurity.” Consider what you want to make easily available to people, and co-design a type system and security policies that reflect your point of view. Everything that you make hard to get at must add more in terms of security than the frictional pain caused. Do not fall into the trap of designing a very secure API that provides no information of value.
![information  leakage PNG](/images/blog/masterclass/info-leakage.png)

#### What to watch out for
- Introspection - a powerful feature of GraphQL that allows you to query the graph for data and metadata and really navigate and understand an API. This can be of real value to a developer using your API - it could also be useful information for malicious actors who want to take advantage. So be thoughtful about what you expose, but at the same time, don't lock it down wholesale.
- Field suggestions - GraphQL servers will often make field suggestions for you. Handy - but an opportunity for attackers to send in fields - and the field suggestions can reveal things you don’t want to reveal. Again, be thoughtful, but not draconian.
- Error messages - gives you details of an error - much like REST API. You don’t want to reveal backend info about what the error happened, so you need to curate your exception messages carefully.

#### Recommendations
- Design your schema thoughtfully. Note that when you generate the schema automatically, you’re not finished. So go back in and consider your design for security implications.
- Expose introspection thoughtfully.
- Expose field suggestions thoughtfully.
- Don't simply return errors as-is think about what would be helpful, but not harmful.
- Automate testing
- Ongoing monitoring - continually think about security and use the requests to understand what people might be trying to do!

## Request Complexity
With REST APIs, all you can provide are query parameter flags that allow people to change what request returns in controlled ways. Thus, you're typically in a much smaller domain, so it’s a lot easier to understand that you’re not going to let someone try to download a database through your REST API. But because of how you can define the schema in GraphQL and make relationships between types, you can build up a relatively complex request in GraphQL. You can batch requests in a single GraphQL call and nest things deeply.
![request complexity PNG](/images/blog/masterclass/request-complexity.png)
#### What to watch out for
- Multiple operations
- Nested queries
- Query complexity - There's complexity in terms of what is happening on the backend - handling N+1 problems, for example.

#### Recommendations
- Design your schema thoughtfully
- Validate requests
- Configure timeouts, query depth, page size and other limits to make wholesale attacks less profitable.
- Test! Test! Test!

## Authorization ++

Authorization consideration goes beyond authorization just for making the request. What’s the nature of that request? Is the user authorized to get all of that?

For example,  you might have a large graph connecting customers and orders. Customers may have detailed purchasing records. You may not want everyone to be able to find that information - even if the API is internal to your organization. We have security controls on data for a reason, so it's important to carry those same security controls through to your GraphQL API.
![Authorization PNG](/images/blog/masterclass/authorization.png)
#### What to watch out for
- Access to the entire graph from one endpoint
- Access to all fields of a type
- Queries and mutations through the same HTTP request

#### Recommendations
- Do user authentication via JWT for example, not just API keys
- Use attribute-based access control
- Be thoughtful about attaching access requirements for every entry point
- Be thoughtful about attaching access requirements to restrict field access

## Demo
Drop into the video around the 37’15” timestamp for a short demo that demonstrates a problem that can arise in an auto-generated schema.

## Summary
GraphQL APIs should be carefully designed. And Security considerations are a very important part of the design. If you do this well, you will have a more secure, more useful, more re-usable, and better performing API. It's win, win, win, win. The only way to make this a losing proposition is to think about Security after you have designed your API. Don't fall into that trap.

[![YouTube video on demand - Master Class 2:Security](https://res.cloudinary.com/stepzen/image/upload/v1668726170/covers/masterclass_2-play_zdylkb.jpg)](https://youtu.be/2VUOzbiY9sI "Master Class 2: How to Reduce Security Risks in API Architectures")



## More from the GraphQL Architecture Master Class

The blogs from the ***GraphQL Architecture Master Class*** are:
1. [Build Quicker. Run Better.](/blog/graphql-masterclass-build-faster-run-better)
2. [How to Reduce Security Risks in API Architectures](/blog/how-to-reduce-security-risks-in-api-architectures-graphql-masterclass)

Subsequent blogs in the series will cover:

3. **How to Implement a GraphQL Layer when Data Resides in more than a Database**. If you have more than PostgreSQL or any one database backend, this session is for you.

4. **Federated Data: How to Massively Simplify your Approach**. Current approaches to federated data access are much more complicated than necessary.

5. **How to Design GraphQL for a Global Scale**. Your applications are global. How to ensure that your infrastructure keeps pace.

And if you want to jump ahead, you can find the videos of each webinar on-demand at the YouTube [GraphQL Master Class Playlist](https://www.youtube.com/playlist?list=PLRbLs--WELU_d_hQwz0EJHIsS3KtR8wHI)

[![GraphQL Master Class Playlist](https://res.cloudinary.com/stepzen/image/upload/v1668641461/covers/masterclass-playlist_cbcj4n.png)](https://www.youtube.com/playlist?list=PLRbLs--WELU_d_hQwz0EJHIsS3KtR8wHI "GraphQL Master Class Playlist")


---
[**Start For Free**](/signup) |  | [**Request StepZen Demo**](/connect/request-demo) |  | [**Connect With The Team On Discord**](https://discord.gg/9k2VdPn2FR)


You know how to secure REST endpoints. But are you worried about securing GraphQL? Is GraphQL less secure than REST? What do developers need to know? Should developers design the API first, secure it second? We hope you walk away with ideas and best practices for the ever-important topic of API security.


How to Reduce Security Risks in API Architectures: GraphQL Architecture Master Class

Software Engineer

Charlie Kim

## Managing Introspection

StepZen provides GraphQL introspection for all endpoints.  For public or externally facing APIs where you have developers working to use your API, this is a great tool and service.  However, if you have an API that's a bit more closed, you will probably want to disable introspection in production.  It is commonly listed as a best practice and is certainly best to do when you want your API to be closed or to tamp down on information leakage — you'll find other ways of masking your APIs such as stripping comments, renaming types, etc. to hide away details of your endpoint.

Specifically, GraphQL introspection allows extraction of the schema from a GraphQL endpoint.   This includes the types, fields, and descriptions.   This, of course, is particularly important in code-first GraphQL implementations where the schema is only defined by the code. There are a number of tools,such as GraphiQL, that make extensive use of this information to provide structured views of your schema, auto-completion, and descriptions.  It's a powerful reflection tool.   Let's start with a brief look at what can be done with introspection.  Take the following  schema.

```graphql
""" Post is public """
type Post {
  postmessage : String!
}
""" News is public """
type News {
  newsMessage: String!
}
""" User should not be public """
type User {
  user: String!
}
""" Query """
type Query {
   """ Get Posts """
   posts : [Post!]
   """ Get News """
   news : [News!]
   """ Get Users """
   users : [User!]
}
```

GraphQL introspection is performed by examining the built-in `Query` type `__schema` field.  Here's a simplified query on `__schema`: 

```graphql
{
  __schema {
    directives { name }
    queryType {
      fields {  name  description }
    }
    types { name description }
  }
}
```
and even trimmed, you can see the depth of the information available:

```graphql
{
  "data": {
    "__schema": {
      "directives": [
        {
          "name": "include"
           "description": "Directs the executor to include this field or fragment only when the `if` argument is true."
        }....
      ],
      "queryType": {
        "fields": [
          {
            "name": "news",
            "description": " Get News ",
          },
          {
            "name": "posts",
            "description": " Get Posts ",
          },
          {
            "name": "users",
            "description": " Get Users ",
          }
        ]
      },
      "types": [
        {
          "name": "User",
          "description": " User should not be public "
        },
        {
          "name": "News",
          "description": " News is public "
        },
        {
          "name": "Post",
          "description": " Post is public "
        },
        {
          "name": "Query",
          ....
        },
.....
        {
          "name": "__Schema",
          ....
        }
      ]
    }
  }
}
```


The [blog article](https://stepzen.com/blog/simple-abac-for-graphql) by my colleague Carlos Eberhardt introduced Attribute-based [Access Control rules](https://stepzen.com/docs/access-control/access-control-rules), and if you've read that, you can probably already see the path to making this work for JWT based access.  

Before we go on to defining the policy, let's examine how access policies work: ***if a rule exists for a field with a condition that evaluates to true, then access is allowed under that condition***.  The corollary is that if the condition evaluates to false, then access is not allowed.  ***So, we can disallow access to a field simply by using a `false` condition.***

So, a simple effective policy that allows users to access all fields in `Query`, but not introspection would be:
```graphql
access:
 policies:
   - type: Query
     rules:
       - name: "Disable introspection"
         condition: false
         fields: [ "__schema", "_type"]
     policyDefault:
       condition: "?$jwt"
```
Specifically, this allows all users (with a valid JWT) access to all Query fields (e.g. `posts`, `news`, and `users`) and removes access to the fields used for introspection  `__schema` and `__type`.  `__type` allows users to probe the types and there's really no need for them to do so - unless they are your developers.

So, if you wished to be more nuanced, you could allow your developers access to introspection by adding the following rule:

```graphql
       - name: "Developer introspection"
         condition: "?$jwt && $jwt.MINE.group: String == 'developers'"
         fields: [ "__schema", "__type"]
```
This requires that every JWT token have a claim named `MINE.group` that is added when the token is created. 

For public access, you'd likely want to be more controlled about which fields are accessible and a good policy  would look like:

```graphql
access:
 policies:
   - type: Query
     rules:
       - name: "Disable introspection"
         condition: false
         fields: [ "__schema", "_type" ]
       - name: "public fields"
         condition: true
         fields: [ "posts", "news" ]
```


## Summary
Introspection is a core tool when creating and developing a GraphQL endpoint, so StepZen's default is to allow introspection.   For production, access policies provide a straight-forward and precise controls over introspection.

> **NOTE**: if you are using your localhost-based proxy to access your StepZen endpoint, it is easy to forget that it is using your Admin key and will bypass any access control policy you have in place.

Controlling introspection is only one tool for managing information leakage.   This could be sensitive comments or information that could enable others to use your endpoints in ways you had not anticipated or wanted.  However, it's best to have mechanisms in place that protect you even if schema information does leak out.   

Consider using access policies to limit access to your GraphQL endpoint.  You can also use `@materializer`, `@sequence`, `@graphql` and `stepzen import graphql` to build out secondary GraphQL endpoints that control and limit your exposure.   Check out the StepZen [docs](/docs) for more, and we'll follow up on some of these ideas in future blog articles.



GraphQL APIs allow for introspection to view the schema.  However, a best practice is to turn off introspection in production.  Access Control policies allow for this.


How to Use Access Control Policies to Manage Introspection

Cofounder & CEO

Anant Jhingran

Having done different forms of API infrastructure for over a decade, I can safely say that there is nothing as powerful from a data consumption perspective as GraphQL. A query like:

```graphql
query MyQuery {
   customerByEmail(email: "john.doe@example.com") {
      city
      name
      orders {
      createdOn
      delivery {
         status
      }
   }
  }
}
```
makes the right customer, order and delivery data available to the API consumer, completely abstracting away the backend protocols, keys, locations and stitching requirements. It makes enterprise data “liquid” from a consumption perspective.

## Liquid Data

But with such liquidity comes a danger. Let me draw upon my [Apigee](https://cloud.google.com/apigee) experience, where I saw this constant struggle in organizations. On the one hand, APIs were great — they reduced friction in the adoption of services and increased the topline. But on the other hand, they opened up a new channel of vulnerability. Could organizations eat the cake and have it too?

I used to give an analogy: You have a door or two to your house. You cannot have a house without a door. And you do your best to protect that door. You lock it so that only authorized people with keys can get in. You put security cameras to see if some unauthorized entry is happening, and so on. You balance a need (having a door) with a concern (security).

GraphQL poses similar challenges. On the one hand, it makes enterprise data easily available through a very flexible API. But on the other hand, given how easy it makes the data flow, we must ask what security challenges it creates that need to be addressed. If the two sides go hand in hand, then GraphQL will deliver on the promise of being the universal API standard.

In this article, we discuss three of these challenges and describe some of the mechanisms that can mitigate those challenges.

## Data Rights
Is the query allowed to access the data it is asking for? There are three obvious places to check this:

1. **At the query structural level** before it is even executed (“Whoa, why is the query asking for the details of john.doe@example.com when the credentials it has presented do not give it the permission?”)
1. **In the backend** (“Sorry buddy, you are asking for order status from me, a database, but given the context I have, I cannot do that for you.”)
1. **In the GraphQL layer** (“Hmmm, why are you asking for orders of a customer; only developers with a fulfillment role can check that.”)

Each has its pros and cons. In a good system, bad queries are stopped before they are executed. The GraphQL engine stops certain subqueries, and data requests received by the backends are further checked.

A good mechanism for the query structural–level check is to have each query come in with a JSON web token (JWT) token and for the GraphQL API endpoint to check for structural validity. So the above query presented along with a JWT token that has an entry: `“enduser: john.doe@example.com”` might be accepted, but the same query with a JWT token that contains `“enduser: jane.smith@example.com”` might be denied. More complex tokens and verification mechanisms might specify who could ask for orders or not.

Checking for rights in the backend often depends on the backends. Databases have good access-control mechanisms, so it is relatively straightforward to use the checks and balances there. REST backends are typically controlled by API keys, which are a coarser control. JWT and OAuth tokens are much better, but not all REST APIs implement them. And of course, the GraphQL layer must be able to pass the context down to the backend.


The checks and balances in the GraphQL layer pose their own challenges. Typically, a GraphQL implementation has a concept of “resolvers” — what code to execute when customer.orders needs to be populated. A key question is: what checks can be put on the resolvers? That is before `customer.orders` resolver can be called, is it even permitted to be called? Different implementations take different approaches to resolvers. In StepZen, they are query-based, connecting data in the enclosing object with a query in the enclosed object. So one might say, “Take the data customer.id and pass it as parameter customerId in the query getOrdersByCustomer and the data that is returned becomes the value of `customer.orders.”`


In this model, the query structural-level check serves as a resolver-based check — you kill two birds with one stone. In other ways of doing it, resolver-based checks have to be implemented separately.

## Data Protection
HIPAA or PII (personally identifiable information) controls often prevent bits of data from being inadvertently leaked (Social Security numbers might get masked, names might get anonymized, etc.) However, in GraphQL, individual bits are important, but how they get combined is where the real danger lies.

Imagine a backend that produces the current employment details of a customer. And another backend that produces their demographics. What if the two, when combined, give a strong signal on the education level, and what if leaking the two bits of information together is the real problem, and individually each of them is harmless (assuming HIPAA and PII compliance). In this case, clearly, the GraphQL layer has to do some magic of masking or anonymizing etc. So a query

```graphql
query MyQuery {
  customerByEmail(email: "john.doe@example.com") {
    name
    age
    employment {
	company
	position
    }
  }
}
```
is unacceptable, but a query without age or without position is acceptable? Implementing query structure-level controls requires too many combinations. A better approach is to add some bit of logic that says “mask age+position” allowing a much wider set of data to be queried for.

This kind of “individual bits are good, but together some might be bad” can only be implemented in the GraphQL layer. A common mechanism (which StepZen employs) is to enable “pre” and “post” logic around declarative query-based resolvers, and one use of such logic is to do the above masking.

## Data Sovereignty

As we have discussed in a previous article, GraphQL has an in-built mechanism for federation (or a graph of graphs). So such an assembly is easily possible in GraphQL, whereas it is challenging to achieve in traditional REST implementations:

![graph of graphs](/images/blog/liquid-data-graph-of-graphs.jpg)

While we have done a functional decomposition above, it could as easily be a country- or continent-based decomposition (or any combination of geographic, cloud, functional, etc.). In the geographic decomposition, the customer subgraph might be built out of two subgraphs: a North America (NA) subgraph and a Europe (EU) subgraph.

Now each subgraph can implement its data sovereignty rules. For example, the EU subgraph can decide to only send aggregated information further up the chain, whereas the NA subgraph could send more details. Any level of data sovereignty can be built in once the concept — GraphQL is just a graph of graphs — is internalized.

## Conclusion
As you saw, GraphQL makes data liquid. But that poses challenges in data rights, protection and sovereignty, to name just three. Each of these is not only solvable; sometimes it is much easier to do in GraphQL than in other approaches.

The time to march toward a future API architecture built on GraphQL is now. You can enable new business through these APIs, and yet you can relatively easily ensure that data vulnerabilities do not increase the cost of the new business.

*Visit [stepzen.com](/) to read about StepZen's approach to helping developers build GraphQL to implement secure, performant data access. We'd love to share more and learn what you're working on - [book a short call](/connect/request-demo)*.

---
This article was originally published in The New Stack: [![The New Stack](/images/blog/tns-graphql-liquid-data.png)](https://thenewstack.io/graphql-makes-data-liquid-what-it-means-for-data-protection/)







GraphQL makes enterprise data “liquid” from a consumption perspective. But with such liquidity comes the possibility of opening new vulnerabilities. In this article, we explore challenges for data rights, data protection, and data sovereignty and describe mechanisms that can mitigate them.


GraphQL Makes Data Liquid — What It Means for Data Protection

## Is Securing GraphQL APIs Harder?
Here at StepZen, we're often asked about securing GraphQL APIs.

> "We've heard GraphQL is a security risk. Is it? Is securing GraphQL harder than securing REST APIs?"

Of course, security isn't a boolean, it's a gradient. The question isn't a matter of "secure vs insecure"; it's "more secure vs less secure."

If you only consider that the main method of interacting with a GraphQL API is an HTTP request, the answer is no, it's not harder. There are time-proven ways of handling security for HTTP.

But when you look at GraphQL one step beyond the network access control perspective, it can be harder to make it more secure. You have a single endpoint that may expose a broader capability than a REST API endpoint – especially if you federate multiple services into a single GraphQL endpoint. From that perspective, granting access to the endpoint may generate more risk than granting access to a single REST API endpoint. Therefore we need some ability to control access to the GraphQL schema that lies beyond the endpoint.


In this blog, we’ll take a look at StepZen Field Policies, which allow you to control access to your GraphQL API beyond simply approving or blocking the HTTP request. Field Policies can be used on APIs created in StepZen or applied to any GraphQL API, regardless of implementation technology.

## GraphQL API Entry Points
Recall that a GraphQL API has, at the top level, root types under which all the fields, or entry points, for the API are defined. Typically those root types are Query and Mutation. Let's look at an example where we have the two root types, Query and Mutation. Each, in turn, has two fields, or entry points, defined.
```graphql
type Query {
  users(email: String): [User]
  orders(userId: ID): [Order]
}

type Mutation {
  createUser(username: String!, email: String!, companyName: String): User
  addItemToOrder(
    orderId: ID!
    productId: ID!
    quantity: Int!
    price: Float!
  ): Order
}
```

The Query root type has the users and orders fields defined. And the Mutation root type has createUser and addItemToOrder fields defined.


If the access control for this API relies solely on HTTP endpoint access, anyone with access to the endpoint can execute an operation using any of the four entry point fields. In most real-world situations you would either need to lock down the API too much, limiting the value of GraphQL, or allow access to more callers while implementing security further down the stack, leading to much greater risk. We need a solution that allows us to restrict access beyond simply restricting access to the endpoint. We need a solution that recognizes the capabilities of GraphQL and can control access to the fields in the GraphQL request.

## Access Control with  StepZen Field Policies
StepZen Field Policies let you define rules under which those top-level fields, or entry points, may be accessed when a request is executed. This means you can control access to your GraphQL API beyond simply approving or blocking the HTTP request.
Like any other feature in StepZen, field policies are configuration, not code. Rather than live in the defined schema for a GraphQL API, they live in the configuration file that specifies the deployment of an API. Let's look at the anatomy of a field policy.
You define field policies in YAML, and you put them in the config.yaml for your StepZen endpoint. Here is a generic example:
```bash

access:
 policies:
   - type: Query
     policyDefault:
       condition: PREDICATE
     rules:
       - name: "name of rule"
         condition: PREDICATE
         fields: ["entry1"]
       - name: "name of rule"
         condition: PREDICATE
         fields: ["entry2", "entry3"]
   - type: Mutation
     policyDefault:
       condition: PREDICATE
     rules:
       - name: "name of rule"
         condition: PREDICATE
         fields: ["entry4"]
```

There are two policy types supported, Query and Mutation. For each type, there is a policyDefault, which allows you to specify the condition to apply when a field is not specified in any rule. The default condition for policyDefault is false, meaning that fields are not accessible. To make any field not specified in a rule accessible through any request, you can set the condition to true.
> **Note!** Setting condition to true would allow any request to access that field.

For each policy type you can specify multiple rules. A rule is made up of a name, condition, and set of fields to which it applies. The name is useful for administration purposes and for keeping track of why a rule exists. It is visible only in the config.yaml file. The condition evaluates to a boolean indicating whether access to the field or fields listed in the fields property is allowed.

That's all there is to it. The only restriction is that a field must be listed in only one rule. When dealing with security it is important to avoid any ambiguity, and allowing fields in multiple rules creates ambiguity. In practice, this restriction is invaluable in preventing unanticipated access to the fields you wish to protect.

In the next section, we'll look at a real-world example of applying field rules to a mock endpoint, using JSON Web Token (JWT) attributes in the conditions.

## Using Field Policies with JWT
JSON Web Tokens (JWT) are industry-standard credentials for representing claims, typically about a user. To learn more about JWT in general, visit [JWT.io](https://jwt.io). By combining JWT claims, or attributes, with StepZen field policies we can create an Attribute-Based Access Control (ABAC) framework for our GraphQL API. (If a user's role is an attribute of the JWT, you could just as easily use field policies to build a Role-Based Access Control (RBAC) framework for your GraphQL API). However, before we can use JWT in our policy rules we need to inform our StepZen configuration on how to validate the tokens.

As with Field Policies, this configuration is also done in the configuration file for the deployment of an endpoint. You specify the identity information required to verify the JWT – either by setting the JWKS URL in the case of OpenID-based identity, or by specifying the algorithm and keys used to sign the JWT. If you're not familiar with JWT this can sound a little complicated, but it's straightforward once you have a bit of background. We'll walk through a very simple example below. For more information on configuring StepZen to validate tokens, please see the online documentation: [JWT-based access control](https://stepzen.com/docs/access-control/access-control-jwt).

## Using JWT Attributes in Rules
Once StepZen is configured to validate JWT, you can then make GraphQL requests to your StepZen endpoint using a JWT in the Authorization header. StepZen validates the token using the identity information you provide in the configuration, and the token claims will be available to refer to in the Policy rules. Let's take a look at a few examples to see how we might configure the rules to use JWT information.

First, let's look at a policy that allows a user to make a request for any Query field if they provide a valid JWT in the authorization header:

```bash
access:
 policies:
   - type: Query
     policyDefault:
       condition: ?$jwt

```
This policy says that the default condition for any field of Query is the existence (? operator) of a valid JWT ($jwt variable). If there are any Mutations defined in your API, access to those would require the StepZen default access control method, API key (see [Secure Your Schema and Endpoint](/docs/access-control#api-keys) for more information on default access control).

### Example: Users with different levels of access control
Now imagine a GraphQL API for a blog website where you want anyone to be able to view posts, but only logged-in users to be able to comment and view comments. Your Policy definition could look like the following, in part:
```bash
access:
 policies:
   - type: Query
     rules:
       - name: "no access control"
         condition: true
         fields: ["posts"]
       - name: "logged in queries"
         condition: ?$jwt
         fields: ["comments"]
   - type: Mutation
     rules:
       - name: "logged in mutations"
         condition: ?$jwt
         fields: ["createComment"]
```

Let's consider a scenario where we have users with different levels of access control. We'll have editors, administrators, and authors. In this situation, we'll only look at the mutations. Editors can edit and publish posts, administrators can only edit posts, and authors can create and edit posts. Our authorization system assigns roles in the JWT roles claim (RFC7643, Section 4.1.2)[https://www.iana.org/go/rfc7643]. Our access policies would look like the following, in part:
```bash
access:
 policies:
   - type: Mutation
     rules:
       - name: "create posts"
         condition: $jwt.roles:String has "author"
         fields: ["createPost"]
       - name: "edit posts"
         condition: $jwt.roles:String has "editor" || $jwt.roles:String has "administrator" || $jwt.roles:String has "author"
         fields: ["editPost"]
       - name: "publish posts"
         condition: $jwt.roles:String has "editor"
         fields: ["publishPost"]
```
This example shows a few key points about Field Policies and their conditions.


Firstly, a field may only appear in one rule in a policy. This is to prevent ambiguous access control decisions. Often people start thinking about conditions, and the fields to which those conditions have access. This is most common when thinking about this from a role-based access control perspective. It's easier to define rules when you flip your perspective to start with the fields and think about which conditions have access to those fields. In the example above, look at the "edit posts" rule. The field is editPost, and the conditions that have access are where the roles claim contains editor, administrator, or author. Thinking about rules this way makes it easier to avoid ambiguity when defining your Field Policies.


Secondly, the condition is built using a simple expression language. This language is fairly strict since we're dealing with access control. Part of that strictness means we specify the type of the variables we use in the conditions, e.g. $jwt.roles:String says the items in the list of roles are Strings, so when we use the 'has' operator we can use a string on the right-hand side. For more details on the condition, or predicate, language, refer to the [Predicates](/docs/access-control/access-control-rules#predicates) in the StepZen docs.

## A Complete Example You Can Run
If you would like to try a sample before testing with your API, we've provided one in our [snippets repository](https://github.com/stepzen-dev/snippets). In the `protection` directory of that repository you will find a `simpleABACSample` subdirectory ([direct link](https://github.com/stepzen-dev/snippets/tree/main/protection/simpleABACSample)). Follow the instructions in the README to see how you can use Field Policies to protect any GraphQL API quickly and easily!

## Summary
All APIs, including GraphQL, present an enticing target for cyber criminals.  Exploiting the API can enable access to sensitive data or protected functionality within an application. GraphQL APIs share many of the same risks and attack vectors as REST APIs, and maybe even greater risk given that GraphQL delivers a single endpoint that, by design, exposes broader capability than a REST endpoint. But they also share the main method of interacting with them — an HTTP request, and there are proven ways of handling security for HTTP.

StepZen supports two methods to control access to your schemas and GraphQL endpoints.

**[API Keys](/docs/access-control)** control access to the entire endpoint. API keys are a typical access control method for APIs, and the default access control mechanism.

**[Field Policies](/docs/access-control/access-control-rules)** provide fine-grained access control to your GraphQL API using a model similar to attribute-based access control. Field Policies can leverage industry-standard JSON Web Tokens, and provide specific controls for GraphQL APIs. Using a configuration-based mechanism, you can set access control rules for fields in the entry points of your GraphQL API.

Have questions about API security? Want to brainstorm a scenario? We’d love to hear from you over on our [Discord Community](https://discord.gg/9k2VdPn2FR) or you can [schedule time.](/connect/request-demo)




GraphQL APIs are excellent for frontend developers, providing a simpler interface and more capabilities with a single request. However, this does raise security questions. Here we look at a StepZen feature designed to help address those security concerns.
