@webundsoehne/nestjs-auth0-guard/README.md

NestJS Auth0 Guard

<p align="center">
  <a href="https://webundsoehne.com" target="blank">
    <img src="https://webundsoehne.com/wp-content/uploads/webundsoehne-logo.png" width="320" alt="Web und Söhne - Logo" />
  </a>
</p>
Web & Söhne is Austrian's leading expert in programming and implementing complex and large web projects.

# @webundsoehne/nestjs-auth0-guard

[![Version](https://img.shields.io/npm/v/init-cli.svg)](https://npmjs.org/package/@webundsoehne/nestjs-auth0-guard)
[![Downloads/week](https://img.shields.io/npm/dw/init-cli.svg)](https://npmjs.org/package/@webundsoehne/nestjs-auth0-guard)

## Description

This is an [Auth0](https://auth0.com/) guard, which covers the whole integration for you.

* [Implementation](#implementation)
* [Auth0Module](#module)
* [AuthGuard](#guard)
* [Permissions](#permissions)
* [User](#user)

### Implementation <a name="implementation"></a>

__Module:__ `./module.ts`

```
  import { Module, NestModule } from '@nestjs/common'
  import { Auth0Module } from '@webundsoehne/nestjs-auth0-guard'
  import TestController from './controller'

  @Module({
    imports: [
      Auth0Module.register({
        domain: 'customer-domain.auth0.com',
        clientId: 'auth0-client-identifier',
        clientSecret: 'auth0-client-secret',
        audience: 'https://customer-domain.com',
        namespace: 'https://customer-domain.com'
      })
    ],
    controller: [
      TestController
    ]
  })
  export class Server implements NestModule {}
```

__Controller:__ `./controller.ts`

```
  import { Controller, Get, Post, UseGuards } from '@nestjs/common'
  import { AuthGuard, Auth0TokenUser, Permissions, User } from '@webundsoehne/nestjs-auth0-guard'

  @Controller('test')
  @UseGuards(AuthGuard.withPermissions(['read:test', 'save:test', 'remove:test']))
  export class TestController {
    @Permissions('read:test')
    @Get()
    getTest () {}

    @Permissions('save:test')
    @Post()
    getTest (@User() user: Auth0TokenUser) {}
  }
```

### Auth0Module <a name="module"></a>

The `Auth0Module.register(options)` has to be imported once in your main `NestModule`. 
It requires the configuration for communicating with [Auth0](https://auth0.com/).

__Options:__

Name         | Type   | Required | Description
------------ | -----  | -------- | -----------
domain       | String | true     | The Auth0 domain of your account's tenant
clientId     | String | true     | The identifier of the Auth0 client
clientSecret | String | true     | The secret key of the used Auth0 client
audience     | String | false    | The configured audience you want to login (__Fallback:__ `http://localhost:3000`)
namespace    | String | false    | The namespace of the JWT property names, which should be extracted to the user's object (__Fallback:__ `audience`)

### AuthGuard <a name="guard"></a>

If you want to enable the guard for a controller or method, you have to use the `AutheGuard`.
You may use the jumper `AuthGuard.withPermissions(permissions: string | string[])`, which allows you to tell the guard which permissions are allowed without using the decorator.

### Permissions <a name="permissions"></a>

The `Permissions(permissions: string | string[])` decorator restricts, the access to an method, to one of the set permission values.

### User <a name="user"></a>

The `User(key?: string)` decorator allows you to fetch user specific information out of the JWT payload.

## Publishing

On each Git tag commit to this repo, the source-code will be automatically transpiled and published to [NPM](https://www.npmjs.com/~ws-admin).

## Stay in touch

* Author: [Backend Team](mailto:backend@webundsoehne.com)
* Website: [Web & Söhne](https://webundsoehne.com)