mercurius-auth

Mercurius Auth is a plugin for Mercurius that adds configurable Authentication and Authorization support.

Features:

• Define auth directives on fields anywhere in your schema and this plugin will apply custom policies against these protected fields when a GraphQL request is made.
• Works in both normal and gateway mode.
• In addition to the matching auth directive, auth policies have access to the same GraphQL information that any GraphQL resolver has access to.
• Build up an auth context to load identities onto the context before policies are applied.
• Define custom errors.
• GraphQL spec compliant.

Docs

• Install
• Quick Start
  • Directive (default) mode
  • External Policy mode
• Examples
• Benchmarks
• API
• Auth Context
• Apply Policy
• Auth Directive
  • Schema filtering
  • Schema replacement
• External Policy
• Errors
• Federation

Install

1npm i fastify mercurius mercurius-auth

Quick Start

We have two modes of operation for Mercurius Auth:

Directive (default) mode

Setup in Directive mode as follows (this is the default mode of operation):

1'use strict'
2
3const Fastify = require('fastify')
4const mercurius = require('mercurius')
5const mercuriusAuth = require('mercurius-auth')
6
7const app = Fastify()
8
9const schema = `
10  directive @auth(
11    requires: Role = ADMIN,
12  ) on OBJECT | FIELD_DEFINITION
13
14  enum Role {
15    ADMIN
16    REVIEWER
17    USER
18    UNKNOWN
19  }
20
21  type Query {
22    add(x: Int, y: Int): Int @auth(requires: USER)
23  }
24`
25
26const resolvers = {
27  Query: {
28    add: async (_, { x, y }) => x + y
29  }
30}
31
32app.register(mercurius, {
33  schema,
34  resolvers
35})
36
37app.register(mercuriusAuth, {
38  authContext (context) {
39    return {
40      identity: context.reply.request.headers['x-user']
41    }
42  },
43  async applyPolicy (authDirectiveAST, parent, args, context, info) {
44    return context.auth.identity === 'admin'
45  },
46  authDirective: 'auth'
47})
48
49app.listen({ port: 3000 })

External Policy mode

Instead of using GraphQL Directives, you can implement an External Policy at plugin registration to protect GraphQL fields and types. You can find more information about implementing policy systems and how to build external policies for a GraphQL schema in the External Policy documentation.

1'use strict'
2
3const Fastify = require('fastify')
4const mercurius = require('mercurius')
5const mercuriusAuth = require('mercurius-auth')
6
7const app = Fastify()
8
9const schema = `
10  type Message {
11    title: String
12    message: String
13    adminMessage: String
14  }
15
16  type Query {
17    messages: [Message]
18    message(title: String): Message
19  }
20`
21
22const messages = [
23  {
24    title: 'one',
25    message: 'one',
26    adminMessage: 'admin message one'
27  },
28  {
29    title: 'two',
30    message: 'two',
31    adminMessage: 'admin message two'
32  }
33]
34
35const resolvers = {
36  Query: {
37    messages: async (parent, args, context, info) => {
38      return messages
39    },
40    message: async (parent, args, context, info) => {
41      return messages.find(message => message.title === args.title)
42    }
43  }
44}
45
46app.register(mercurius, {
47  schema,
48  resolvers
49})
50
51app.register(mercuriusAuth, {
52  // Load the permissions into the context from the request headers
53  authContext (context) {
54    const permissions = context.reply.request.headers['x-user'] || ''
55    return { permissions }
56  },
57  async applyPolicy (policy, parent, args, context, info) {
58    // When called on field `Message.adminMessage`
59    // policy: { requires: 'admin' }
60    // context.auth.permissions: ['user', 'admin'] - the permissions associated with the user (passed as headers in authContext)
61    return context.auth.permissions.includes(policy.requires)
62  },
63  // Enable External Policy mode
64  mode: 'external',
65  policy: {
66    // Associate policy with the 'Message' Object type
67    Message: {
68      // Define policy for 'Message' Object type
69      __typePolicy: { requires: 'user' },
70      // Define policy for 'adminMessage' field
71      adminMessage: { requires: 'admin' }
72    },
73    // Associate policy with the Query root type
74    Query: {
75      // Define policy for 'message' Query
76      messages: { requires: 'user' }
77    }
78  }
79})
80
81app.listen({ port: 3000 })

Examples

Check GitHub repo for more examples.

Benchmarks

Normal GraphQL Server Mode | Without Auth

Last run: 2021-04-21

1┌─────────┬──────┬──────┬───────┬───────┬─────────┬─────────┬───────┐
2│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%   │ Avg     │ Stdev   │ Max   │
3├─────────┼──────┼──────┼───────┼───────┼─────────┼─────────┼───────┤
4│ Latency │ 4 ms │ 5 ms │ 9 ms  │ 13 ms │ 5.21 ms │ 2.01 ms │ 57 ms │
5└─────────┴──────┴──────┴───────┴───────┴─────────┴─────────┴───────┘
6┌───────────┬─────────┬─────────┬─────────┬─────────┬──────────┬─────────┬─────────┐
7│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg      │ Stdev   │ Min     │
8├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
9│ Req/Sec   │ 11135   │ 11135   │ 18223   │ 18671   │ 17550.19 │ 2049.52 │ 11134   │
10├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
11│ Bytes/Sec │ 5.86 MB │ 5.86 MB │ 9.58 MB │ 9.82 MB │ 9.23 MB  │ 1.08 MB │ 5.86 MB │
12└───────────┴─────────┴─────────┴─────────┴─────────┴──────────┴─────────┴─────────┘
13
14Req/Bytes counts sampled once per second.
15193k requests in 11.03s, 102 MB read

Normal GraphQL Server Mode | With Auth

Last run: 2021-04-21

1┌─────────┬──────┬──────┬───────┬───────┬─────────┬────────┬───────┐
2│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%   │ Avg     │ Stdev  │ Max   │
3├─────────┼──────┼──────┼───────┼───────┼─────────┼────────┼───────┤
4│ Latency │ 5 ms │ 5 ms │ 10 ms │ 14 ms │ 5.59 ms │ 2.1 ms │ 64 ms │
5└─────────┴──────┴──────┴───────┴───────┴─────────┴────────┴───────┘
6┌───────────┬─────────┬─────────┬─────────┬─────────┬──────────┬─────────┬─────────┐
7│ Stat      │ 1%      │ 2.5%    │ 50%     │ 97.5%   │ Avg      │ Stdev   │ Min     │
8├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
9│ Req/Sec   │ 9463    │ 9463    │ 17279   │ 17583   │ 16586.55 │ 2260.65 │ 9459    │
10├───────────┼─────────┼─────────┼─────────┼─────────┼──────────┼─────────┼─────────┤
11│ Bytes/Sec │ 4.98 MB │ 4.98 MB │ 9.08 MB │ 9.25 MB │ 8.72 MB  │ 1.19 MB │ 4.98 MB │
12└───────────┴─────────┴─────────┴─────────┴─────────┴──────────┴─────────┴─────────┘
13
14Req/Bytes counts sampled once per second.
15182k requests in 11.03s, 96 MB read

Normal GraphQL Server Mode | With Introspection Filters

Last run: 2022-05-24

1┌─────────┬───────┬───────┬───────┬───────┬──────────┬─────────┬────────┐
2│ Stat    │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg      │ Stdev   │ Max    │
3├─────────┼───────┼───────┼───────┼───────┼──────────┼─────────┼────────┤
4│ Latency │ 10 ms │ 12 ms │ 30 ms │ 47 ms │ 13.59 ms │ 6.54 ms │ 155 ms │
5└─────────┴───────┴───────┴───────┴───────┴──────────┴─────────┴────────┘
6┌───────────┬─────────┬─────────┬────────┬─────────┬─────────┬─────────┬─────────┐
7│ Stat      │ 1%      │ 2.5%    │ 50%    │ 97.5%   │ Avg     │ Stdev   │ Min     │
8├───────────┼─────────┼─────────┼────────┼─────────┼─────────┼─────────┼─────────┤
9│ Req/Sec   │ 2559    │ 2559    │ 7607   │ 8335    │ 7101.55 │ 1579.83 │ 2559    │
10├───────────┼─────────┼─────────┼────────┼─────────┼─────────┼─────────┼─────────┤
11│ Bytes/Sec │ 1.04 MB │ 1.04 MB │ 3.1 MB │ 3.39 MB │ 2.89 MB │ 643 kB  │ 1.04 MB │
12└───────────┴─────────┴─────────┴────────┴─────────┴─────────┴─────────┴─────────┘
13
14Req/Bytes counts sampled once per second.
1578k requests in 11.05s, 31.8 MB read

Gateway GraphQL Server Mode | Without Auth

Last run: 2021-04-21

1┌─────────┬───────┬───────┬───────┬───────┬──────────┬──────────┬────────┐
2│ Stat    │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg      │ Stdev    │ Max    │
3├─────────┼───────┼───────┼───────┼───────┼──────────┼──────────┼────────┤
4│ Latency │ 29 ms │ 32 ms │ 66 ms │ 88 ms │ 34.96 ms │ 11.57 ms │ 195 ms │
5└─────────┴───────┴───────┴───────┴───────┴──────────┴──────────┴────────┘
6┌───────────┬────────┬────────┬─────────┬────────┬────────┬────────┬────────┐
7│ Stat      │ 1%     │ 2.5%   │ 50%     │ 97.5%  │ Avg    │ Stdev  │ Min    │
8├───────────┼────────┼────────┼─────────┼────────┼────────┼────────┼────────┤
9│ Req/Sec   │ 1286   │ 1286   │ 3039    │ 3135   │ 2819.5 │ 543.65 │ 1286   │
10├───────────┼────────┼────────┼─────────┼────────┼────────┼────────┼────────┤
11│ Bytes/Sec │ 450 kB │ 450 kB │ 1.06 MB │ 1.1 MB │ 987 kB │ 190 kB │ 450 kB │
12└───────────┴────────┴────────┴─────────┴────────┴────────┴────────┴────────┘
13
14Req/Bytes counts sampled once per second.
1528k requests in 10.03s, 9.87 MB read

Gateway GraphQL Server Mode | With Auth

Last run: 2021-04-21

1┌─────────┬───────┬───────┬───────┬───────┬──────────┬──────────┬────────┐
2│ Stat    │ 2.5%  │ 50%   │ 97.5% │ 99%   │ Avg      │ Stdev    │ Max    │
3├─────────┼───────┼───────┼───────┼───────┼──────────┼──────────┼────────┤
4│ Latency │ 29 ms │ 33 ms │ 69 ms │ 93 ms │ 35.92 ms │ 12.46 ms │ 209 ms │
5└─────────┴───────┴───────┴───────┴───────┴──────────┴──────────┴────────┘
6┌───────────┬────────┬────────┬─────────┬────────┬────────┬────────┬────────┐
7│ Stat      │ 1%     │ 2.5%   │ 50%     │ 97.5%  │ Avg    │ Stdev  │ Min    │
8├───────────┼────────┼────────┼─────────┼────────┼────────┼────────┼────────┤
9│ Req/Sec   │ 1216   │ 1216   │ 2943    │ 3129   │ 2744.7 │ 552.54 │ 1216   │
10├───────────┼────────┼────────┼─────────┼────────┼────────┼────────┼────────┤
11│ Bytes/Sec │ 426 kB │ 426 kB │ 1.03 MB │ 1.1 MB │ 961 kB │ 193 kB │ 426 kB │
12└───────────┴────────┴────────┴─────────┴────────┴────────┴────────┴────────┘
13
14Req/Bytes counts sampled once per second.
1527k requests in 10.03s, 9.61 MB read

License

MIT