Skip to content

Latest commit

 

History

History
204 lines (151 loc) · 9.76 KB

README.md

File metadata and controls

204 lines (151 loc) · 9.76 KB
Raw

graphql-auth-directive

ci codeql codecov Snyk Codacy semantic-release: angular FOSSA

GraphQL @auth directive that protects resources from unauthenticated and unauthorized access.

Inspired by TypeGraphQL and GraphQL Tools.

⚠️ Under development

👋 Any help is appreciated

Installation

npm install graphql-auth-directive
# or
yarn add graphql-auth-directive

Usage

Note: See examples directory

  1. Add @auth directive to GraphQL schema:

    Note: on OBJECT | FIELD | FIELD_DEFINITION

    type Example @auth {
 unprotected: String!
 adminProtected: String! @auth(roles: [ADMIN])
}

type Query {
 unprotected: String!
 protected: String! @auth
 adminRoleProtected: String! @auth(roles: [ADMIN])
 adminOrModeratorRolesProtected: String! @auth(roles: [ADMIN, MODERATOR])
 viewPermissionProtected: String! @auth(permissions: [VIEW])
 viewOrEditPermissionsProtected: String! @auth(permissions: [VIEW, EDIT])
 roleAndPermissionProtected: String! @auth(roles: [ADMIN], permissions: [VIEW])
 # ...
}

type Mutation {
 # Same as Query
}

type Subscription {
 # Same as Query
}

  2. Build auth directive and create GraphQL schema:

    import { buildAuthDirective, defaultAuthFn } from 'graphql-auth-directive';
import { makeExecutableSchema } from '@graphql-tools/schema';
import { ApolloServer } from 'apollo-server';
import { typeDefs } from './typeDefs';
import { resolvers } from './resolvers';

// Build auth directive
const authDirective = buildAuthDirective({
  auth: defaultAuthFn // Auth procedure (default or custom)
  // ... More options
});

// Build schema
let schema = makeExecutableSchema({
  typeDefs: [authDirective.typeDefs, typeDefs], // TypeDefs
  resolvers // Resolvers
});
schema = authDirective.transformer(schema); // Transform schema

// Build and start server
const server = new ApolloServer({
  schema,
  context: () => {
    /* ... */
  }
});
server
  .listen()
  .then((serverInfo) => console.info(`Server started at ${serverInfo.url}`));

    Warning: defaultAuthFn requires a context of the following type:

    {
  user?: {
    roles: string[] | number[];
    permissions: string[] | number[];
  };
  /* ... */
}

    If defaultAuthFn does not match your configuration or you want more control, you can fully customize the auth procedure. See Custom Auth procedure for more information.

Options

Name Type Default Value Description
name string auth Directive name.
auth Auth<TContext, TRole, TPermission> Auth function (AuthFn<TContext, TRole, TPermission>) or class (AuthFnClass<TContext, TRole, TPermission>).
authMode 'ERROR' | 'NULL' ERROR Auth mode if access is not granted. ERROR throws an error. NULL returns null.
roles { enumName?: string, default?: TRole | TRole[] } { enumName: undefined, default: undefined } Roles configuration. enumName is the enum name for roles array type, default is String. default is the default value, default to [].
permissions { enumName?: string, default?: TPermission | TPermission[] } { enumName: undefined, default: undefined } Permissions configuration. enumName is the enum name for permissions array type, default is String. default is the default value, default to [].
authenticationError ClassTypeEmptyConstructor<Error> AuthenticationError Authentication error class. An error class must extends Error.
authorizationError ClassTypeEmptyConstructor<Error> AuthorizationError Authorization error class. An error class must extends Error.
container ContainerType IOCContainer Dependency injection container.

Custom Auth procedure

Warning: auth must return boolean or Promise<boolean>, where true indicates that access has been granted and false that is denied

You can fully customize the auth procedure by providing a function or class when building the directive.

import { buildAuthDirective } from 'graphql-auth-directive';
import { myAuth } from './myAuth';

// Build auth directive
const authDirective = buildAuthDirective({
  auth: myAuth // Custom auth procedure
});

AuthFn function

import type { AuthFn } from 'graphql-auth-directive';
import type { Context } from './Context'; // Your context type
import type { Roles, Permissions } from './User'; // Your roles and permissions enum

export const myAuthFn: AuthFn<Context, Roles, Permissions> = (
  { context: { user } }, // Context
  { roles, permissions } // @auth(roles: [...], permissions: [...])
) : boolean | Promise<boolean> => {
  /* ... */
};

AuthFnClass class

Note: Class based auth can leverage Dependency Injection (DI) mechanism. To enable DI mechanism register your OCI Container when building the directive: buildAuthDirective({ ..., container: MyContainer });

import type { AuthFnClass } from 'graphql-auth-directive';
import type { Context } from './Context'; // Your context type
import type { Roles, Permissions } from './User'; // Your roles and permissions enum

export class MyAuthFnClass implements AuthFnClass<Context, UserRoles, Permissions> {
  public auth(
    { context: { user } }, // Context
    { roles, permissions } // @auth(roles: [...], permissions: [...])
  ): boolean | Promise<boolean> {
    /* ... */
  }
}

Integrations

TypeGraphQL

See typegraphql example for more information.

Why another GraphQL Auth Directive?

Similar libraries are unmaintained and use an old (and deprecated) version of graphql-tools. Moreover this library tries to be as most modular as possible, giving the user the ability to configure the directive as much as possible.

Similar libraries:

  1. graphql-auth-user-directives

  2. graphql-directive-auth

  3. graphql-auth-directives

  4. gql-auth-directives

Contributing

I would love to see your contribution ❤️

See CONTRIBUTING guidelines.

License

This project is licensed under the MIT License.
See LICENSE file for details.

FOSSA