Enhance customer experiences with Apollo GraphOS

<a href="https://github.com/accounts-js/accounts">accounts-js</a>&nbsp;is a fullstack authentication and accounts-management for Javascript.&nbsp;We provide you with a set of tools to authenticate and manage your users in your application. These tools work with REST, GraphQL and are database agnostic.



We will implement the Authentication GraphQL API in NodeJS using accounts-js and Apollo. At the end of this article, our server will be able to sign up new users, allow the users to login and authenticate them to protect some restricted information.



At the end of this post, you can find a link to a repository containing the sources.



<h3 class="wp-block-heading"><a href="#requirements" aria-hidden="true" class="aal_anchor" id="requirements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Requirements</h3>



For this project, you will need to have nodejs and mongodb installed on your system.



<h3 class="wp-block-heading"><a href="#setup-the-node-project" aria-hidden="true" class="aal_anchor" id="setup-the-node-project"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the node project</h3>



Let&#8217;s start by creating our NodeJS project. Create a new folder named&nbsp;<code>accounts-js-server</code>, all the project files should be inside this folder. Let&#8217;s initialize our new project using&nbsp;<code>npm</code>&nbsp;(you can use&nbsp;<code>yarn</code>&nbsp;if you prefer):



<pre class="wp-block-prismatic-blocks"><code class="language-">npm init</code></pre>



Now, let&#8217;s add the dependencies we need to setup our Apollo GraphQL server.



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install apollo-server graphql</code></pre>



Create a new&nbsp;<code>index.js</code>&nbsp;file (to make this tutorial simpler all our code will be in a single file) and add this code to setup the Apollo server.



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const { ApolloServer, gql } = require(&#039;apollo-server&#039;);

const typeDefs = gql`
 type Query {
 # This query will be protected so only authenticated users can access it
 sensitiveInformation: String
 }
`;

const resolvers = {
 Query: {
 sensitiveInformation: () =&gt; &#039;Sensitive info&#039;,
 },
};

const server = new ApolloServer({ typeDefs, resolvers });

// The `listen` method launches a web server.
server.listen().then(({ url }) =&gt; {
 console.log(`🚀 Server ready at ${url}`);
});</code></pre>



Now let&#8217;s start the server to make sure everything is working as expected.



<pre class="wp-block-prismatic-blocks"><code class="language-">node index.js</code></pre>



In your console you should see:



<pre class="wp-block-prismatic-blocks"><code class="language-">🚀 Server ready at http://localhost:4000/</code></pre>



Our GraphQL server is now ready, it&#8217;s time to add accounts-js!



<h3 class="wp-block-heading"><a href="#setup-accounts-js" aria-hidden="true" class="aal_anchor" id="setup-accounts-js"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup accounts-js</h3>



First, we will setup mongoose and connect to our database.



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install @accounts/mongo mongoose</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const mongoose = require(&#039;mongoose&#039;);
const { Mongo } = require(&#039;@accounts/mongo&#039;);

// We connect mongoose to our local mongodb database
mongoose.connect(&#039;mongodb://localhost:27017/accounts-js-server&#039;, {
 useNewUrlParser: true,
 useUnifiedTopology: true,
});

// We tell accounts-js to use the mongo connection
const accountsMongo = new Mongo(mongoose.connection);</code></pre>



Then, we add the accounts-js server dependencies.



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install @accounts/server @accounts/password</code></pre>



<ul class="wp-block-list"><li><code>@accounts/server</code>: The accounts-js core dependency.</li><li><code>@accounts/password</code>: The accounts-js password service, it expose a set of function to manage and authenticate users using email + password.</li></ul>



It&#8217;s time to setup the accounts-js server configuration



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const { AccountsServer } = require(&#039;@accounts/server&#039;);
const { AccountsPassword } = require(&#039;@accounts/password&#039;);

const accountsPassword = new AccountsPassword({
 // You can customise the behavior of the password service by providing some options
});

const accountsServer = new AccountsServer(
 {
 // We link the mongo adapter we created in the previous step to the server
 db: accountsMongo,
 // Replace this value with a strong random secret
 tokenSecret: &#039;my-super-random-secret&#039;,
 },
 {
 // We pass a list of services to the server, in this example we just use the password service
 password: accountsPassword,
 }
);</code></pre>



Then, we add the accounts-js graphql dependencies.



<pre class="wp-block-prismatic-blocks"><code class="language-">npm install @accounts/graphql-api @graphql-toolkit/schema-merging @graphql-modules/core</code></pre>



<ul class="wp-block-list"><li><code>@accounts/graphql-api</code>: The transport layer exposing all the queries and mutations accounts-js provide.</li><li><code>@graphql-toolkit/schema-merging</code>: Expose a set of tools that will help us to merge our schemas.</li><li><code>@graphql-modules/core</code>: An internal dependency that accounts-js use to manage his graphql schema and resolvers.</li></ul>



Let&#8217;s merge the accounts-js GraphQL schema and our schema, so the user can access it



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

// Add makeExecutableSchema to the imported variables
const { ApolloServer, gql, makeExecutableSchema } = require(&#039;apollo-server&#039;);
const { mergeTypeDefs, mergeResolvers } = require(&#039;@graphql-toolkit/schema-merging&#039;);
const { AccountsModule } = require(&#039;@accounts/graphql-api&#039;);

// We generate the accounts-js GraphQL module
const accountsGraphQL = AccountsModule.forRoot({ accountsServer });

// A new schema is created combining our schema and the accounts-js schema
const schema = makeExecutableSchema({
 typeDefs: mergeTypeDefs([typeDefs, accountsGraphQL.typeDefs]),
 resolvers: mergeResolvers([accountsGraphQL.resolvers, resolvers]),
 schemaDirectives: {
 ...accountsGraphQL.schemaDirectives,
 },
});

// When we instantiate our Apollo server we use the schema and context properties
const server = new ApolloServer({
 schema,
 context: accountsGraphQL.context,
});</code></pre>



At the end, our file should look like this:



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const { ApolloServer, gql, makeExecutableSchema } = require(&#039;apollo-server&#039;);
const mongoose = require(&#039;mongoose&#039;);
const { Mongo } = require(&#039;@accounts/mongo&#039;);
const { mergeTypeDefs, mergeResolvers } = require(&#039;@graphql-toolkit/schema-merging&#039;);
const { AccountsServer } = require(&#039;@accounts/server&#039;);
const { AccountsPassword } = require(&#039;@accounts/password&#039;);
const { AccountsModule } = require(&#039;@accounts/graphql-api&#039;);

// We connect mongoose to our local mongodb database
mongoose.connect(&#039;mongodb://localhost:27017/accounts-js-server&#039;, {
 useNewUrlParser: true,
 useUnifiedTopology: true,
});

const accountsMongo = new Mongo(mongoose.connection);

const typeDefs = gql`
 type Query {
 # This query will be protected so only authenticated users can access it
 sensitiveInformation: String
 }
`;

const resolvers = {
 Query: {
 sensitiveInformation: () =&gt; &#039;Sensitive info&#039;,
 },
};

const accountsPassword = new AccountsPassword({});

const accountsServer = new AccountsServer(
 {
 db: accountsMongo,
 // Replace this value with a strong secret
 tokenSecret: &#039;my-super-random-secret&#039;,
 },
 {
 password: accountsPassword,
 }
);

// We generate the accounts-js GraphQL module
const accountsGraphQL = AccountsModule.forRoot({ accountsServer });

// A new schema is created combining our schema and the accounts-js schema
const schema = makeExecutableSchema({
 typeDefs: mergeTypeDefs([typeDefs, accountsGraphQL.typeDefs]),
 resolvers: mergeResolvers([accountsGraphQL.resolvers, resolvers]),
 schemaDirectives: {
 ...accountsGraphQL.schemaDirectives,
 },
});

const server = new ApolloServer({ schema, context: accountsGraphQL.context });

// The `listen` method launches a web server.
server.listen().then(({ url }) =&gt; {
 console.log(`🚀 Server ready at ${url}`);
});</code></pre>



If we restart our server and visit http://localhost:4000/, we should see that the accounts-js queries and mutations are merged with our schema. Our authentication server is now ready 🚀.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="632" src="https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-1024x632.png" alt="" class="wp-image-2160" srcset="https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-1024x632.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-300x185.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-768x474.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2-1200x740.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/05/ud3ptilvz38a2k7pizs2.png 1277w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h3 class="wp-block-heading"><a href="#creating-our-first-user" aria-hidden="true" class="aal_anchor" id="creating-our-first-user"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Creating our first user</h3>



Inside the GraphQL Playground, let&#8217;s execute the following mutation:



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation {
 createUser(
 user: { email: &quot;john.doe@john.com&quot;, password: &quot;superSecurePassword&quot; }
 )
}</code></pre>



Congrats, our first user has been created 👏!



If you take a look at the&nbsp;<code>users</code>&nbsp;collection inside mongodb you should see that your user was created and looks like this:



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
 &quot;_id&quot;: ObjectId(&quot;5e3da6ba13ef1a137bbc8fe4&quot;),
 &quot;services&quot;: {
 &quot;password&quot;: {
 &quot;bcrypt&quot;: &quot;$2a$10$WwhjvbDzQpS2LrdkcgQJwODn.EE95T0b9NmMUNcHKyrDOlXEeybSq&quot;
 }
 },
 &quot;createdAt&quot;: 1581098682713,
 &quot;updatedAt&quot;: 1581098682713,
 &quot;emails&quot;: [
 {
 &quot;address&quot;: &quot;john.doe@john.com&quot;,
 &quot;verified&quot;: false
 }
 ]
}
</code></pre>



What we can see is that a&nbsp;<code>createdAt</code>&nbsp;and&nbsp;<code>updatedAt</code>&nbsp;fields have been created. We also see that the password has been saved hashed in the database, we use bcrypt as a default but you can change it to argon2 via the options if you prefer.



Now let&#8217;s try to login with this user:



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation {
 authenticate(
 serviceName: &quot;password&quot;
 params: {
 user: { email: &quot;john.doe@john.com&quot; }
 password: &quot;superSecurePassword&quot;
 }
 ) {
 sessionId
 tokens {
 accessToken
 refreshToken
 }
 }
}</code></pre>



You should see in the playground that a new session has been created. The session is represented by:



<ul class="wp-block-list"><li>a sessionId (you can check the session in the database)</li><li>a short lived JWT accessToken used to authenticate the user</li><li>a long lived refreshToken that can be used to get a new accessToken once it&#8217;s expired</li></ul>



Save the access token, we will need it to authenticate our requests in the next part.



<h3 class="wp-block-heading"><a href="#protecting-our-query" aria-hidden="true" class="aal_anchor" id="protecting-our-query"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Protecting our query</h3>



Our first user has been created and we are now able to login via the API. Next step is to protect our&nbsp;<code>sensitiveInformation</code>&nbsp;query so only the authenticated users can access it.



accounts-js provide an&nbsp;<code>@auth</code>&nbsp;directive that we can use to protect our private queries.



Let&#8217;s add the directive to the query in our schema:



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">// index.js

const typeDefs = gql`
 type Query {
 # We add the @auth directive
 sensitiveInformation: String @auth
 }
`;</code></pre>



If you try this query, you should get an&nbsp;<code>Unauthorized</code>&nbsp;error 🛑. We can&#8217;t access this resource because we are not authenticated. To authenticate our request with the server we need to add the access token saved previously as a header of the request. The header key should be&nbsp;<code>authorization</code>&nbsp;and the value should be prefixed with&nbsp;<code>Bearer</code>. eg:&nbsp;<code>{ &quot;authorization&quot;: &quot;Bearer my-access-token&quot; }</code>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="630" src="https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-1024x630.png" alt="" class="wp-image-2170" srcset="https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-1024x630.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-300x185.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-768x472.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08-1200x738.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/05/tkat54liy7txdsf8aa08.png 1281w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



You made your first authenticated query, how cool is that?



Well, that&#8217;s it, you are done, you now have a Graphql server that can register and authenticate new users. Pretty simple right? Next step for you is to explore the playground and play with the different queries and mutations available (verify the email, change the password etc..) :).



You can find the source here&nbsp;<a href="https://github.com/pradel/accounts-js-server-tutorial">https://github.com/pradel/accounts-js-server-tutorial</a>.



If you want to learn more about accounts-js head over our website and check the documentation <a href="https://www.accountsjs.com/">https://www.accountsjs.com/</a> 🔐.

Email & password authentication with accounts-js and Apollo Server

Setting Up Authentication and Authorization with Apollo Federation

Authorization in GraphQL

Editor’s note: This post is from early 2016. We published an updated post on this topic in 2018, which you can read here:<a href="https://dev-blog.apollodata.com/authorization-in-graphql-452b1c402a9" target="_blank" rel="noreferrer noopener">Authorization in GraphQLPractical methods for controlling access to the data in your APIdev-blog.apollodata.com</a>



If you like, you can read the original content of this post below!



<hr class="wp-block-separator"/>



Last week, I wrote about how you might go about&nbsp;<a href="https://medium.com/apollo-stack/a-guide-to-authentication-in-graphql-e002a4039d1" target="_blank" rel="noreferrer noopener">authentication in GraphQL</a>. This week, I want to talk about authorization.



As a reminder, here’s the definition of authentication vs. authorization again:



Authentication&nbsp;means checking the identity of the user making a request.



Authorization&nbsp;refers to the set of rules that is applied to determine what a user is allowed to see / do.



<hr class="wp-block-separator"/>



<h2 class="wp-block-heading" id="8197"><a href="#authorization" aria-hidden="true" class="aal_anchor" id="authorization"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Authorization</h2>



Now that we have some ideas for how to authenticate our users on the GraphQL server, let’s look at ways to check the user’s permissions to make sure we only return data the user is allowed to see, or perform actions that the user is allowed to perform.



While you can use good libraries and protocols for much of the hard stuff in authentication, the opposite is true of authorization: This is your app’s territory, and you’ll need to think hard about which user has permission to do what. But instead of saying it’s up to you, wishing you good luck and leaving it at that, let’s take a step back and look at what we’re dealing with. Please bear with me as things are about to get a bit philosophical…



<hr class="wp-block-separator"/>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="768" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-1024x768.jpg" alt="" class="wp-image-126" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-1024x768.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-300x225.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-768x576.jpg 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-1536x1152.jpg 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-2048x1536.jpg 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-1200x900.jpg 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_aoC3q8dGw2FylwSRlm75Dw-1980x1485.jpg 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A GraphQL schema for a simple todo list application.</figcaption></figure>



A GraphQL schema defines types. Each type — except for scalar types like Int, Float or String — has fields which define the relationship between this type and other types (one to one, or one to many). If you think about your schema in terms of a graph, types are the nodes of your graph, and fields are edges. Scalar types have no fields, so they form the leaf nodes of your graph.



A GraphQL query is just an instruction for traversing the graph in a specific way, resulting in a tree.



When traversing a tree, you would start at the root, but a graph has no root so there is no logical starting point! That’s why every GraphQL schema needs to have a root query type: it’s the entry point into the graph. The fields of the root query type are links to the actual queries that your GraphQL server supports. This may sound confusing at first, but don’t worry about it, you can start using GraphQL just fine without understanding this detail.



<hr class="wp-block-separator"/>



Since a GraphQL query is just a set of instructions for how to traverse the graph, there are two natural options for enforcing permissions:



<ol class="wp-block-list"><li>Which edges the user can traverse</li><li>Which nodes the user can visit.</li></ol>



<hr class="wp-block-separator"/>



<h2 class="wp-block-heading" id="33b8"><a href="#permissions-on-edges" aria-hidden="true" class="aal_anchor" id="permissions-on-edges"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Permissions on edges</h2>



Defining permission rules on edges may sound a bit strange at first, but it’s effectively how most systems implement permissions. For instance, a user can see a todo item if that item belongs to a list that the user can see. A user can see a list, if it is either public (no owner), or owned by them.



For graphql-js, authorization on a per-edge basis can easily be checked in the resolve function of a field. If the current user does not have the permission to traverse the edge, the resolver will either throw an error, resolve to null, or — in the case of a list type — the edge will be omitted from the set of edges returned. For the todo list example from above, it would look something like this:



<pre class="wp-block-preformatted"> let listType = new GraphQLObjectType({ name: 'List', fields: () =&gt; ({ id: { type: GraphQLString }, name: { type: GraphQLString }, // other field omitted for brevity ... todos: { type: new GraphQLList(todoType), resolve: function(list){ return DB.Lists.get_todos(list.id); } } }) });</pre>



You may have noticed that there is no permission check in there at all! Because we said a user can see a todo if it’s part of a list they can see, we don’t need to check anything in the todos resolver. The permission check is enforced when the user requests to traverse an edge to get to the list. In our case that happens when the user runs the&nbsp;getListById&nbsp;query. Here’s the schema for that:



<pre class="wp-block-preformatted">let query = new GraphQLObjectType({ name: 'Query', fields: { getListById: { type: listType, description: "Get a specific todo list", args: { id: { type: GraphQLID } }, resolve: function(root, {id}, ctx){ return DB.Lists.get(id) .then( list =&gt; { if(list.owner_id &amp;&amp; list.owner_id != ctx.userId){ throw new Error("Not authorized to see this list"); } else { return list; } }); } } } });</pre>



The approach sounds reasonable in theory, but it has a major disadvantage: There are often multiple edges that lead to a particular node. For example, apart from a&nbsp;getListById&nbsp;query, there might be a&nbsp;list&nbsp;field on&nbsp;user, which finds all the lists for that user. If we can access a list through the&nbsp;user&nbsp;node, we expect to be able to access it through getListById as well. Think about it this way:&nbsp;If you give someone the keys to your front door, you might as well give them the keys to your back door.&nbsp;What you really care about is whether that person can get into your house or not. Which door they are using is really not that important.



There’s another reason why defining permissions on edges isn’t practical. If you want to use a client-side cache like Relay, your GraphQL schema needs to provide a way to retrieve a node of any type by its ID. Effectively that means that your graph must have a query node which has a direct edge to all your object nodes in the graph!



So just like it would be useful to have a single key that works for all doors that lead into the same room, it would be useful to have one place where permissions are checked. That is: if we’re going to put the same rules on every edge in the graph leading to one node, we might as well put the rule on the node itself and save ourselves some unnecessary repetition which would only make our code more error-prone.



That brings us to defining authorization rules per node.



<hr class="wp-block-separator"/>



<h2 class="wp-block-heading" id="27ac"><a href="#permissions-on-nodes" aria-hidden="true" class="aal_anchor" id="permissions-on-nodes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Permissions on nodes</h2>



The goal here is simple — put authorization logic into the nodes, such that they are enforced no matter how the node is reached in the graph. The problem is, graphql-js doesn’t let you do this easily. Fields have resolvers, but types (i.e. nodes) don’t. That leaves us with two possible solutions:



a) Write the authorization logic for&nbsp;list&nbsp;in one function, and make sure it’s called by every resolve function of a field that leads to a node of type&nbsp;list.



b) Write the authorization logic for&nbsp;list&nbsp;in one function, and make sure it’s called in every field on the list type before returning anything.



Clearly, none of these options is ideal. Option a) has the advantage of being pretty close to what we would naturally do in a resolve function: Fetch an item of type&nbsp;list&nbsp;from the backend and pass it on to the&nbsp;list&nbsp;type for dealing with it. What we’re essentially doing is enforcing authorization on the edges, but using the same rule on every edge that leads to&nbsp;list.



The downside of option a) is that you have to make sure that the function is called correctly from every edge that leads to&nbsp;list.&nbsp;Those edges could be anywhere, and new edges could be added by other programmers that don’t know about the authorization logic, making it both harder to test and harder to maintain.



Option b) doesn’t completely eliminate this downside, but it makes sure that the places in which you have to call the authorization function are grouped together. That makes it much easier to test, and it makes it less likely that someone will screw up.



A downside of option b) is that now&nbsp;every&nbsp;field on your type needs to have a resolve function, otherwise you’ll be leaking data. When using option a), the field&nbsp;name&nbsp;on&nbsp;list&nbsp;doesn’t need a resolve function because it’s identical to what’s returned from the database. If we’re using option b), we need to add the resolve function just to check permissions. Another downside of option b) is that we now might be doing extra work by checking a permission on every field when it would be sufficient to check it once for the whole node.



Given the downsides of both of these options, I think it would be very neat if graphql-js would let you define a function that is called whenever a node is entered during the execution of the query, a sort of type-level resolve function. Such a function would be the natural place to do authorization checks. It would also be the natural place to resolve from an id to an object instance. If you use something like Facebook’s Dataloader for batching and caching requests, the impact on performance should be negligible for most all applications. If you absolutely needed to optimize for speed, you could always make your `onEnter` function pass through its argument if it encounters anything other than an ID.



For now, I think the best way to implement either of the above, is to factor data fetching logic out of your resolvers and put it in a separate place. In my opinion, that’s something you should do anyway, because besides giving you a good place to enforce per-node permissions, it will factor out the glue between your GraphQL schema and your backend into a neat component, which can be easily changed in the future.



You should always factor data fetching logic out of your resolve functions.



We’ve all heard the DRY mantra many times, but I think it’s still worth repeating in the context of GraphQL.



<hr class="wp-block-separator"/>



<h2 class="wp-block-heading" id="fa1d"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



So, that’s enough philosophy for now. Where does it all leave us? To summarize, here are the main points:



<ol class="wp-block-list"><li>Checking authorization per node makes the most sense</li><li>graphql-js doesn’t have a type-level resolve function to do #1</li><li>A decent solution is to factor out data fetching into a separate layer and do the authorization check there.</li></ol>



Below is an example that follows the principles outlined above. It’s for a query that fetches all todo lists that a user can see.



For the following query,



<pre class="wp-block-preformatted">{ allLists { name } }</pre>



Don’t do this:



<pre class="wp-block-preformatted">//in schema.js (just the essential bits) allLists: { resolve: (root, _, ctx) =&gt; { return sql.raw("SELECT * FROM lists WHERE owner_id is NULL or owner_id = %s", ctx.user_id); } }</pre>



Instead, I suggest you do this:



<pre class="wp-block-preformatted">// in schema.js (just the essential bits) allLists: { resolve: (root, _, ctx) =&gt; { //factor out data fetching return DB.Lists.all(ctx.user_id) .then( lists =&gt; { //enforce auth on each node return lists.map(auth.List.enforce_read_perm(ctx.user_id) ); }); } }//in DB.js export const DB = { Lists: { all: (user_id) =&gt; { return sql.raw("SELECT id FROM lists WHERE owner_id is NULL or owner_id = %s, user_id); } } }//in auth.js export const auth = { List: { enforce_read_perm: (user_id) =&gt; { return (list) =&gt; { if(list.owner_id !== null &amp;&amp; list.owner_id !== user_id){ throw new Error("User not authorized to read list"); } else { return list; } } } }</pre>



You may think that the&nbsp;DB.Lists.all&nbsp;function is already enforcing permissions, but the way I see it it’s just trying not to fetch too much data, the permissions themselves are enforced not on each node separately.&nbsp;That way you have the auth checks in one place and&nbsp;can be sure that they will be applied consistently, even if you fetch data in many different places.



<hr class="wp-block-separator"/>



Before we wrap up,&nbsp;there is actually one more option&nbsp;worth noting: Not dealing with authorization at all. Your GraphQL server does not necessarily need to deal with authorization, it could just pass through the authentication information and let your various backends deal with authorization. This is not a good choice if you’re connecting directly to a database, but if you are building on top on an existing infrastructure of REST services, this might be the fastest way to transition. Your REST services most likely already implement a bunch of complicated authorization logic, and moving all of it at once would not be practical.



My colleague&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----c6441bcc4302----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;recently published a great Medium post in which he does exactly that to implement a&nbsp;<a href="https://medium.com/apollo-stack/discourse-in-graphql-part-1-ee1ffd8a22df" target="_blank" rel="noreferrer noopener">GraphQL API on top of the popular forum software Discourse</a>.



<hr class="wp-block-separator"/>



Alright, here’s the conclusion of the conclusion — the tldr:



<ol class="wp-block-list"><li>Permission checks are best implemented on nodes</li><li>Permission checks are best separated from data fetching logic to make sure they are applied consistently, regardless of how the data is fetched.</li></ol>



As always, nothing written here should interpreted in a dogmatic way. These are not “hard and fast” rules. Think of them more as guidelines. When it comes to Authorization, there are more often than not many roads that lead to Rome, and the solution that fits best for your application might be quite different from what I’ve outlined above.



Nevertheless, my hope is that you will find this article helpful if you’re just getting started with a GraphQL and weren’t quite sure what to put where. If you already have experience with GraphQL and have implemented authentication and authorization, I’d be curious to hear if you came to the same or a different conclusion. Let me know in the comments below!



If you want to read more articles like this, you might like the Medium publication&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">Building Apollo</a>,&nbsp;which has many posts on similar topics by&nbsp;<a href="https://medium.com/u/803918030a60?source=post_page-----c6441bcc4302----------------------" target="_blank" rel="noreferrer noopener">Sashko Stubailo</a>&nbsp;and myself.

Access Control in GraphQL

Note: If you’re not yet familiar with GraphQL, take a look at my&nbsp;<a href="https://medium.com/apollo-stack/the-basics-of-graphql-in-5-links-9e1dc4cac055" target="_blank" rel="noreferrer noopener">other post</a>&nbsp;first and come back later — you’ll get more out of it.



Update 2018:&nbsp;This post is from early 2016. Check out the&nbsp;<a href="https://www.apollographql.com/docs/guides/access-control.html" target="_blank" rel="noreferrer noopener">best practices we recommend for authentication and authorization.</a>



In this post, I want to talk about how you might go about authentication and authorization when using GraphQL. The examples I’m giving work for graphql-js, Facebook’s reference implementation, but they are quite generic and could be adapted to other implementations as well.



Before we get started, let’s make sure we’re all on the same page when it comes to the terms I’ll be using:



Authentication&nbsp;means checking the identity of the user making a request.



Authorization&nbsp;refers to the set of rules that is applied to determine what a user is allowed to see / do.



The GraphQL specification doesn’t tell you how to do authentication or authorization. That’s a good thing because it lets you use any technology you like, but it can be a bit confusing to developers who are new to GraphQL. For the rest of this post, I will write my thoughts on the topic so far and show a few options for authentication and authorization. GraphQL is still relatively new, so a best practice has yet to emerge. I don’t claim to have all the answers, so if you have a different idea or a different opinion, feel free to share that in the comments so we can all learn together!



Alright, that’s enough disclaimers for now. Let’s get started…



<h2 class="wp-block-heading" id="844e"><a href="#authentication" aria-hidden="true" class="aal_anchor" id="authentication"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Authentication</h2>



Unless your GraphQL API is completely public, your server will need to authenticate its users. Your options are twofold:



<ol class="wp-block-list"><li>Let the web server (e.g. express or nginx) take care of authentication.</li><li>Handle authentication in GraphQL itself.</li></ol>



Both of these options have some advantages and some disadvantages.



If you do authentication in the web server, you can use a standard auth package (e.g. passport.js for express) and many existing authentication methods will work out of the box. You can also add and remove methods at your liking without modifying the GraphQL schema.



However, doing authentication in the web server has the downside of requiring the client to speak to an authentication endpoint in addition to the GraphQL endpoint.



<hr class="wp-block-separator"/>



Let’s start with the first option: doing authentication in the web server. What would that look like?



It’s quite straight forward. If you’re using express for example, you could use a middleware like passport.js and any authentication strategy it supports, for example username+password, or OAuth. The middleware will authenticate the user or reject/redirect the request if it fails. You’ll have to provide the requisite methods for persisting users and expose the login endpoints, but I’ll spare you the details — if you need them, you can look them up in the middleware’s documentation.



Once the user is authenticated, you simply pass the user information into GraphQL as context. If you were using express, graphql-js and passport.js, that would look something like this:



<pre class="wp-block-preformatted">import { Schema } from ‘./schema/schema.js’; //your GraphQL schema import { graphql } from ‘graphql’; import bodyParser from ‘body-parser’; import express from ‘express’; import passport from ‘passport’; import session from ‘express-session’; import uuid from ‘node-uuid’;require(‘./auth.js’); //see snippet belowconst app = express(); const PORT = 3000;//passport's session piggy-backs on express-session app.use(session({ genid: function(req) { return uuid.v4(); }, secret: ‘Z3]GJW!?9uP”/Kpe’ }));app.use(passport.initialize()); app.use(passport.session());app.post('/graphql', (req, res) =&gt; { graphql(schema, req.body, { user: req.user }) .then((data) =&gt; { res.send(JSON.stringify(data)); }); });//login route for passport app.use(bodyParser.urlencoded({ extended: true }) ); app.post('/login', passport.authenticate('local', { successRedirect: '/', failureRedirect: '/login', failureFlash: true }) );app.listen(PORT, () =&gt; { console.log(“GraphQL server listening on port %s”, PORT); });</pre>



And in&nbsp;auth.js:



<pre class="wp-block-preformatted">import passport from ‘passport’; let LocalStrategy = require(‘passport-local’).Strategy;import {DB} from ‘./schema/db.js’;passport.use(‘local’, new LocalStrategy( function(username, password, done) { let checkPassword = DB.Users.checkPassword( username, password); let getUser = checkPassword.then( (is_login_valid) =&gt; { if(is_login_valid){ return DB.Users.getUserByUsername( username ); } else { throw new Error(“invalid username or password”); } }) .then( ( user ) =&gt; { return done(null, user); }) .catch( (err) =&gt; { return done(err); }); } ));passport.serializeUser(function(user, done) { done(null, user.id); });passport.deserializeUser(function(id, done) { DB.Users.get(id).then( (user, err) =&gt; { return done(err, user); }); });</pre>



And voila, you now have access to the user object in the GraphQL resolver!



<hr class="wp-block-separator"/>



Alright, now let’s look at the second option: doing authentication in GraphQL. What would that look like?



A word of caution here:&nbsp;If you’re implementing authentication yourself, make sure to never store passwords in clear text or a MD5 or SHA-256 hash. Use something like bcrypt that is designed for this kind of thing. While we’re at it, make sure to not store your session tokens as-is on the server, you should hash them first.



Here, things get a little bit more complicated, because you have to do more of the heavy lifting yourself. To keep it at least reasonably simple, let’s go with usernames and passwords in this example. So an authentication flow could look like this:



First you get a session token (so your client doesn’t have to store the username and password in cleartext):



<pre class="wp-block-preformatted">mutation { getSessionToken(username: 'alice', password: 'hard2remember') } &gt; { getSessionToken: "6e37a03e-9ee4-42fd-912d-3f67d2d0d852" }</pre>



Then you pass this token in subsequent requests:



<pre class="wp-block-preformatted">query { user(token: "6e37a03e-9ee4-42fd-912d-3f67d2d0d852"){ todoLists{ name } } }&gt; { user { todoLists: [ "Today", "Tomorrow" ] } }</pre>



When your session is over, you can call a logout mutation which invalidates the session token.



On the surface, this looks quite reasonable, but it has some downsides:



<ul class="wp-block-list"><li>Every query or mutation that needs permissions has to add the token field and check it. That can be a lot of repetition, if your schema is complex.</li><li>If any field besides your root queries need to be aware of the token, you have to pass it down by returning it from each resolver. So for example, if the todoLists needed to be filtered based on the logged in user, you would have to do the following:</li></ul>



<pre class="wp-block-preformatted">user: { resolve: (root, {token}){ return { token: token, user: /*...*/ }; } },/* ... */todoLists: { resolve: (parent) =&gt; { let user = parent.user; let token = parent.token; /* Return lists filtered based on token ... */ } }</pre>



That looks bad enough, but if you need the token further down, it gets even worse. If your resolver returns a GraphQLList type, you’ll have to add the token to every item in that list.



Luckily, there’s a slightly better way in graphql-js: You can set the token on the context that every resolver receives as its third argument:



<pre class="wp-block-preformatted">user: { resolve: (root, {token}, ctx){ ctx.token = token; //assuming ctx is already an object return { /* user */ }; } }</pre>



If you are doing multiple queries, you will still have to pass the token into each one, because they get executed in parallel. In that case, writing to the context is also not a great idea any more. There is however a neat trick — or an awful hack, depending on who you ask — you can use, but it only works for mutations:



You can write a login method, which sets the context. Since mutations are executed one after the other and not in parallel, you can be sure the context is set after the login mutation:



<pre class="wp-block-preformatted">mutation { loginWithToken(token: "6e37a03e-9ee4-42fd-912d-3f67d2d0d852"), do_stuff(greeting: "Hello", name: "Tom"), do_more_stuff(submarine_color: "Yellow") }</pre>



I’ll let you in on a secret here, but please don’t shoot yourself in the foot with it: There is no difference between mutations and queries, except that mutations are executed serially, in the order given. That means the second mutation has to wait for the first to finish, the third has to wait for the second to finish, and so on. But there is nothing that prevents you from mutating state in your queries, and there is nothing that prevents you from calling a query a mutation.



That said, I would not recommend calling everything a mutation just to use the above trick. Parallel execution is an important for performance.



As you can see, this approach is not very elegant, and the workaround writes the token to the context, just like the web server would. There may be cases where you cannot modify the web server and you’re forced to do authentication in GraphQL, but in most cases I think I would prefer to handle authentication in the web server. It’s not only more generic, but also more flexible.



<hr class="wp-block-separator"/>



That’s all for now. Originally I was planning to write about authentication and authorization in the same post, but it was getting a little long so I decided to break it up. If you liked this post, make sure to also read&nbsp;<a href="https://medium.com/apollo-stack/auth-in-graphql-part-2-c6441bcc4302" target="_blank" rel="noreferrer noopener">Part 2</a>!



I’m also working towards a complete example app to showcase all language features of GraphQL and how to use them in practice. It will include authentication and authorization as well as a bunch of other things. I‘m looking for collaborators on that, so if you’re interested, do let me know. The more, the merrier!



As always, discussion and feedback is very welcome. Just leave your comments below!

Backend

Email & password authentication with accounts-js and Apollo Server

Setting Up Authentication and Authorization with Apollo Federation

Authorization in GraphQL

Access Control in GraphQL

A guide to authentication in GraphQL

Backend

Email & password authentication with accounts-js and Apollo Server

Setting Up Authentication and Authorization with Apollo Federation

Authorization in GraphQL

Access Control in GraphQL

A guide to authentication in GraphQL

Stay in our orbit