Authorization
The following section assumes you are familiar with authentication in nestjs.
nestjs-query
provides authorization helpers out of the box to reduce the amount of boilerplate typically required.
The nestjs-query
graphql package exposes decorators and options to allow the following
- Additional filtering for objects based on the graphql context.
- Filtering relations based on the graphql context.
- Low level authorization service support when your authorizer needs to use other services or additional information that is not in the graphql context.
If you are looking to modify incoming requests based on the context, take a look at the hooks documentation
Authorization is invoked as the last step before calling the QueryService
.
Getting Started
All examples assume you have a guard that adds a user
to the req on the context.
type AuthenticatedUser = {
id: number;
username: string;
};
type UserContext = {
req: {
user: AuthenticatedUser;
};
};
For the sake of this example we'll use a JWTAuthGuard
described in implementing passport jwt nestjs docs.
To enable the guard on your resolver endpoints you use the guards
option when setting up your resolver.
The guards
option will ensure that all queries and mutations will have the guard
added so the user is added to
the request.
import { NestjsQueryGraphQLModule } from '@ptc-org/nestjs-query-graphql';
import { NestjsQueryTypeOrmModule } from '@ptc-org/nestjs-query-typeorm';
import { Module } from '@nestjs/common';
import { TodoItemInputDTO } from './dto/todo-item-input.dto';
import { TodoItemUpdateDTO } from './dto/todo-item-update.dto';
import { TodoItemDTO } from './dto/todo-item.dto';
import { TodoItemEntity } from './todo-item.entity';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
@Module({
imports: [
NestjsQueryGraphQLModule.forFeature({
imports: [NestjsQueryTypeOrmModule.forFeature([TodoItemEntity])],
resolvers: [
{
DTOClass: TodoItemDTO,
CreateDTOClass: TodoItemInputDTO,
UpdateDTOClass: TodoItemUpdateDTO,
guards: [JwtAuthGuard],
},
],
}),
],
})
export class TodoItemModule {}
@Authorize Decorator
The @ptc-org/nestjs-query-graphql
package includes an @Authorize
decorator that allows you to add additional filter
criteria to authorize an incoming request.
The @Authorize
decorator accepts the following types.
- An
object
that has anauthorize
method that returns a Filter for the DTO. - An instance of an
Authorizer
that implements theauthorize
andauthorizeRelation
methods. - An
Authorizer
class reference that implements theAuthorizer
interface. TheAuthorizer
class will be instantiated using thenestjs
's dependency injection.
The @Authorize
decorator does not return an unauthorized error instead the following will occur:
queryMany
results will not include any DTOs that do not match the filter criteria.findOne
will return a not found for a DTO that cannot be found for theid
and auth filter.updateOne
will return a not found error if the DTO to update cannot be found for theid
and auth filter.updateMany
will exclude any records that do not match the user provided filter and the auth filter from being updated.deleteOne
will return a not found error if the DTO to delete cannot be found for theid
and auth filter.deleteMany
will exclude any records that do not match the user provided filter and the auth filter from being deleted.
You can throw an UnauthorizedException
or return a rejected promise with an UnauthorizedException
in your
authorize function, if you can determine at that point that the user should not be able to access the endpoint.
In the following example the authorize
function returns a Filter
that includes the ownerId
to ensure that only
TodoItems
that belong to the authenticated user are returned.
import {
FilterableField,
IDField,
FilterableConnection,
FilterableRelation,
Authorize
} from '@ptc-org/nestjs-query-graphql';
import { ObjectType, ID, GraphQLISODateTime, Field } from '@nestjs/graphql';
import { SubTaskDTO } from '../../sub-task/dto/sub-task.dto';
import { TagDTO } from '../../tag/dto/tag.dto';
import { UserDTO } from '../../user/user.dto';
import { UserContext } from '../../auth/auth.interfaces';
@ObjectType('TodoItem')
@Authorize({ authorize: (context: UserContext) => ({ ownerId: { eq: context.req.user.id } }) })
@FilterableRelation('owner', () => UserDTO)
@FilterableConnection('subTasks', () => SubTaskDTO, { update: { enabled: true } })
@FilterableConnection('tags', () => TagDTO)
export class TodoItemDTO {
@IDField(() => ID)
id!: number;
@FilterableField()
title!: string;
@FilterableField({ nullable: true })
description?: string;
@FilterableField()
completed!: boolean;
@FilterableField(() => GraphQLISODateTime)
created!: Date;
@FilterableField(() => GraphQLISODateTime)
updated!: Date;
@Field()
age!: number;
@FilterableField()
priority!: number;
@FilterableField({ nullable: true })
createdBy?: string;
@FilterableField({ nullable: true })
updatedBy?: string;
@FilterableField()
ownerId!: number;
}
The above example is pretty straight forward, however your authorize function can be as complex as you need it to be based on information in the context.
Relation Filtering
By default when relations are queried any additional filters defined using the @Authorize
decorator on the relation
DTO will also be included.
When mutating relations
- If the DTO that is having a relation(s) added or removed cannot be found for the
id
and auth filter a not found error will be returned. - When adding or removing a single relation if the relation cannot be found for the
id
and auth filter a not found error will be returned. - When adding or removing multiple relations if all relations cannot be found a not found error will be throw.
For example given the following SubTaskDTO
definition whenever the subTasks
connection is queried through a
todoItem
, only subTasks
that belong to the user will be returned.
import { FilterableField, IDField, FilterableRelation, Authorize } from '@ptc-org/nestjs-query-graphql';
import { ObjectType, ID, GraphQLISODateTime } from '@nestjs/graphql';
import { TodoItemDTO } from '../../todo-item/dto/todo-item.dto';
import { UserContext } from '../../auth/auth.interfaces';
@ObjectType('SubTask')
@Authorize({ authorize: (context: UserContext) => ({ ownerId: { eq: context.req.user.id } }) })
@FilterableRelation('todoItem', () => TodoItemDTO, { update: { enabled: true } })
export class SubTaskDTO {
@IDField(() => ID)
id!: number;
@FilterableField()
title!: string;
@FilterableField({ nullable: true })
description?: string;
@FilterableField()
completed!: boolean;
@FilterableField(() => GraphQLISODateTime)
created!: Date;
@FilterableField(() => GraphQLISODateTime)
updated!: Date;
@FilterableField()
todoItemId!: string;
@FilterableField({ nullable: true })
createdBy?: string;
@FilterableField({ nullable: true })
updatedBy?: string;
}
Customizing Relation Authorization
If you run into a case where you need to handle authorization for a relation differently from the @Authorize
decorator on the relation DTO you can specify the auth
option in your relation/connection decorator.
The auth
option will take precedence over the @Authorize
decorator on the relation DTO.
For example you could define the subtasks with the auth
option, only allowing completed subtasks to be returned.
@FilterableConnection('subTasks', () => SubTaskDTO, {
update: { enabled: true },
auth: {
authorize: (context: UserContext) => ({ ownerId: { eq: context.req.user.id }, completed: { is: true }}),
},
})
Custom Authorizer
When you need more control over authorization you can create a CustomAuthorizer
. You may want to use a
CustomAuthorizer
if you need to use additional services to do authorization for a DTO.
The CustomAuthorizer
interface ensures two methods:
authorize
- Should return a filter that should be used for all queries and mutations for the DTO.authorizeRelation
- Optionally modify the filter for the relation that will be used when querying the relation or adding/removing relations to/from the DTO. If undefined is returned, the authorization filter of the relation DTO will be used instead.
In this example we'll create a simple authorizer for SubTasks
. You can use this as a base to create a more complex
authorizers that depends on other services.
import { Injectable } from '@nestjs/common';
import { Authorizer } from '@ptc-org/nestjs-query-graphql';
import { Filter } from '@ptc-org/nestjs-query-core';
import { UserContext } from '../auth/auth.interfaces';
import { SubTaskDTO } from './dto/sub-task.dto';
@Injectable()
export class SubTaskAuthorizer implements CustomAuthorizer<SubTaskDTO> {
authorize(context: UserContext): Promise<Filter<SubTaskDTO>> {
return Promise.resolve({ ownerId: { eq: context.req.user.id } });
}
authorizeRelation(relationName: string, context: UserContext): Promise<Filter<unknown> | undefined> {
if (relationName === 'todoItem') {
return Promise.resolve({ ownerId: { eq: context.req.user.id } });
}
return Promise.resolve(undefined);
}
}
To use the SubTaskAuthorizer
you only need to provide it as an argument to the @Authorize
decorator
import { Authorize, FilterableField, IDField, FilterableRelation } from '@ptc-org/nestjs-query-graphql';
import { ObjectType, ID, GraphQLISODateTime } from '@nestjs/graphql';
import { TodoItemDTO } from '../../todo-item/dto/todo-item.dto';
import { UserDTO } from '../../user/user.dto';
import { SubTaskAuthorizer } from '../sub-task.authorizer';
@ObjectType('SubTask')
@Authorize(SubTaskAuthorizer)
@FilterableRelation('owner', () => UserDTO)
@FilterableRelation('todoItem', () => TodoItemDTO, { update: { enabled: true } })
export class SubTaskDTO {
@IDField(() => ID)
id!: number;
@FilterableField()
title!: string;
@FilterableField({ nullable: true })
description?: string;
@FilterableField()
completed!: boolean;
@FilterableField(() => GraphQLISODateTime)
created!: Date;
@FilterableField(() => GraphQLISODateTime)
updated!: Date;
@FilterableField()
todoItemId!: string;
@FilterableField({ nullable: true })
createdBy?: string;
@FilterableField({ nullable: true })
updatedBy?: string;
ownerId!: number;
}
Using Authorizers In Your Resolver
The easiest way to leverage Authorizers
in a custom resolver is to use the AuthorizerInterceptor
and
AuthorizerFilter
param decorator.
In this example there are two important additions:
- The
AuthorizerInterceptor
is added to theTodoItemResolver
as an interceptor, this interceptor will add the authorizer to the context so it can be used down stream - The
AuthorizerFilter
param decorator uses the authorizer added by the interceptor to create an authorizer filter.
import { Filter, InjectQueryService, mergeFilter, mergeQuery, QueryService } from '@ptc-org/nestjs-query-core';
import { AuthorizerInterceptor, AuthorizerFilter, ConnectionType } from '@ptc-org/nestjs-query-graphql';
import { Args, Query, Resolver } from '@nestjs/graphql';
import { UseInterceptors } from '@nestjs/common';
import { TodoItemDTO } from './dto/todo-item.dto';
import { TodoItemConnection, TodoItemQuery } from './types';
@Resolver(() => TodoItemDTO)
@UseInterceptors(AuthorizerInterceptor(TodoItemDTO))
export class TodoItemResolver {
constructor(@InjectQueryService(TodoItemEntity) readonly service: QueryService<TodoItemEntity>) {}
// Set the return type to the TodoItemConnection
@Query(() => TodoItemConnection)
async uncompletedTodoItems(
@Args() query: TodoItemQuery,
@AuthorizerFilter() authFilter: Filter<TodoItemDTO>,
): Promise<ConnectionType<TodoItemDTO>> {
// add the completed filter the user provided filter
const filter: Filter<TodoItemDTO> = mergeFilter(query.filter ?? {}, { completed: { is: false } });
const uncompletedQuery = mergeQuery(query, { filter: mergeFilter(filter, authFilter) });
return TodoItemConnection.createFromPromise(
(q) => this.service.query(q),
uncompletedQuery,
(q) => this.service.count(q),
);
}
}
@InjectAuthorizer Decorator
If you need access to an authorizer for a DTO you can use the @InjectAuthorizer
decorator.
The most common use case for using the @InjectAuthorizer
decorator is when you are not using the autogenerated
resolvers provided by nestjs-query
.
In this example the Authorizer
is injected as a readonly
property you can then use it for any custom methods.
import { QueryService, InjectQueryService } from '@ptc-org/nestjs-query-core';
import { CRUDResolver, InjectAuthorizer } from '@ptc-org/nestjs-query-graphql';
import { Resolver, Query, Args } from '@nestjs/graphql';
import { TodoItemDTO } from './dto/todo-item.dto';
import { TodoItemEntity } from './todo-item.entity';
@Resolver(() => TodoItemDTO)
export class TodoItemResolver extends CRUDResolver(TodoItemDTO) {
constructor(
@InjectQueryService(TodoItemEntity) readonly service: QueryService<TodoItemEntity>,
@InjectAuthorizer(TodoItemDTO) readonly authorizer: Authorizer<TodoItemDTO>,
) {
super(service);
}
}
If you are extending the CRUDResolver
directly be sure to register your DTOs with the NestjsQueryGraphQLModule
When using @InjectAuthorizer
, the injected Authorizer is not the CustomAuthorizer, but the DefaultCRUDAuthorizer that internally uses the CustomAuthorizer.
If you want to use the CustomAuthorizer directly, inject it with @InjectCustomAuthorizer
instead.
Authorize depending on operation
Sometimes it might be necessary to perform different authorization based on the kind of operation an user wants to execute. E.g. some users could be allowed to read all todo items but only update/delete their own.
In this case we can make use of the second parameter of the authorize
function in our CustomAuthorizer
or the one passed to the @Authorizer
decorator which gets passed additional AuthorizationContext
such as the name of the operation that should be authorized:
import { Injectable } from '@nestjs/common';
import { CustomAuthorizer } from '@ptc-org/nestjs-query-graphql';
import { Filter } from '@ptc-org/nestjs-query-core';
import { UserContext } from '../auth/auth.interfaces';
import { SubTaskDTO } from './dto/sub-task.dto';
@Injectable()
export class SubTaskAuthorizer implements CustomAuthorizer<SubTaskDTO> {
authorize(context: UserContext, authorizationContext?: AuthorizationContext): Promise<Filter<SubTaskDTO>> {
if (authorizationContext?.readonly) {
return Promise.resolve({});
}
return Promise.resolve({ ownerId: { eq: context.req.user.id } });
}
authorizeRelation(relationName: string, context: UserContext): Promise<Filter<unknown>> {
if (relationName === 'todoItem') {
return Promise.resolve({ ownerId: { eq: context.req.user.id } });
}
return Promise.resolve({});
}
}
The AuthorizationContext
has the following shape:
export enum OperationGroup {
READ = 'read',
AGGREGATE = 'aggregate',
CREATE = 'create',
UPDATE = 'update',
DELETE = 'delete',
}
interface AuthorizationContext {
/** The name of the method that uses the @AuthorizeFilter decorator */
operationName: string;
/** The group this operation belongs to */
operationGroup: OperationGroup;
/** If the operation does not modify any entities */
readonly: boolean;
/** If the operation can affect multiple entities */
many: boolean;
}
This context is automatically created for you when using the built-in resolvers.
If you authorize custom methods by using the @AuthorizerFilter()
, you should pass the context as argument to the decorator:
@AuthorizerFilter({
operationName: 'completedTodoItems',
operationGroup: OperationGroup.READ,
readonly: true,
many: true
})
You can leave out the operationName
to let the context use the name of the decorated Method.
If you leave out the readonly
property, it's inferred from the operationGroup
.
The operationNames
of the generated CRUD resolver methods are similar to the ones of the QueryService:
queryMany
findById
aggregate
createOne
createMany
updateOne
updateMany
deleteOne
deleteMany
Relations
query{PluralRelationName}
(e.g. querySubTasks)find{SingularRelationName}
(e.g. findTodoItem)aggregate{PluralRelationName}
(e.g. aggregateSubTasks)remove{SingularRelationName}from{SingularParentName}
(e.g. removeSubTaskFromTodoItem)remove{PluralRelationName}from{SingularParentName}
(e.g. removeSubTasksFromTodoItem)set{SingularRelationName}On{SingularParentName}
(e.g. setSubTaskOnTodoItem)add{PluralRelationName}On{SingularParentName}
(e.g. addSubTasksOnTodoItem)
Complete Example
You can find a complete example in examples/auth