@ndeitch/nestjs-keycloak

NestJS Keycloak

nestjs-keycloak is a nestjs guard implementation which supports Rest endpoints and GraphQL resolvers authentication/authorization against a keycloak server.

Getting started

Install nestjs-keycloak

  npm install @ndeitch/nestjs-keycloak

Import nestjs-keycloak module to your app

@Module({ imports: [KeycloakModule] })
export class AppModule {}

Add required environment variables:

.env

CLIENT_ID="some-id"
CLIENT_SECRET="some-secret"
AUTHORIZATION_SERVER_URL="https://your-keycloak-instance/auth"

Available decorators

Resource protection

Usage:

@Get()
@Protected()
protected(): string {
  return 'Your token is valid'
}

Behavior

Performs a live validation on KC server

Example

Controller expecting jwt token valid:

@Controller('users')
export class UserController {
  @Get(':userId')
  @Protected()
  getUser(): string {
    return 'Your token is valid'
  }
}

Requesting user 1

  curl GET 'http://localhost:3000/users/1' --header 'Authorization: Bearer ey...'

If it's ok, user is returned, otherwise a 401 is returned.

Scope validation

Usage

@Get(':id')
@HasScope()
scoped(): string {
  return "You've id:scoped scope"
}

Behavior

Performs a UMA request to KC server. Extracts resource id parameter from request params, if there is no id in request, then it sends CLIENT_ID as resource to perform validation.

As default @HasScope looks for id param in request, if you want to supply a different one, then pass as param like: @HasScope({ resourceId: 'request-id' })

Example

Controller expecting id:getUser permission on KC:

@Controller('users')
export class UserController {
  @Get(':userId')
  @HasScope({ resourceId: 'userId' })
  getUser(): string {
    return "You've id:scoped scope"
  }
}

Requesting user 1 so the token must have 1:getUser permission

  curl GET 'http://localhost:3000/users/1' --header 'Authorization: Bearer ey...'

If it's ok, user is returned, otherwise a 401 is returned.

Note: as resource id on @Get(':userId') is not id you must have to update on @HasScope with { resourceId: 'userId' }

Role validation

Usage

@Get(':id')
@HasRole('admin')
adminOnly(): string {
  return "You're admin"
}

Behavior

Validate token against KC server and checks if it has required role for CLIENT_ID

Example

Controller expecting admin role for resource content which is the CLIENT_ID on .env:

@Controller('users')
export class UserController {
  @Get(':id')
  @HasRole('admin')
  adminOnly(): string {
    return "You're admin"
  }
}

Requesting user 1:

  curl GET 'http://localhost:3000/users/1' --header 'Authorization: Bearer ey...'

Jwt token must have:

{
  "resource_access": {
    "content": {
      "roles": ["admin"]
    }
  }
}

If it's ok, user is returned, otherwise a 401 is returned.

Note: you can pass a list of roles @HasScope(['admin', 'super-admin']) if token has some role request is granted

GraphQL

The context in gql module configuration is required

@Module({
  imports: [
    KeycloakModule,
    GraphQLModule.forRoot({
      context: ({ req }) => req, // THIS LINE IS REQUIRED
    }),
  ],
  providers: [ResolverOne],
})
export class GqlModule {}

With this config, everything should work as expected

Multi tenancy

This lib get realm from jwt token iss property you can check here how it's done. If realm not found the request is denied

Additional info

• JWT token must be sent as http header in format: Bearer YOUR_JWT_TOKEN for both Rest and GraphQL