docs: Update authentication documentation

docs/.vuepress/config.js

@@ -6,16 +6,16 @@ module.exports = {
   themeConfig: {
     version: require("../../package").version,
     repo: "TypedProject/ts-express-decorators",
-    openCollective: 'tsed',
+    openCollective: "tsed",
     gitterUrl: "https://gitter.im/Tsed-io/community",
     editLinks: true,
     docsDir: "docs",
     sidebar: "auto",
     ga: "UA-35240348-1",
     apiUrl: "/api.json",
     algolia: {
-      apiKey: 'f8a038207e461aaac0e2fd16403c2b01',
-      indexName: 'ts_ed',
+      apiKey: "f8a038207e461aaac0e2fd16403c2b01",
+      indexName: "ts_ed"
     },
     locales: {
       "/": {
@@ -43,7 +43,6 @@ module.exports = {
             type: "links",
             items: [
               {link: "/tutorials/", text: "Examples"},
-              {link: "/tutorials/authentication.html", text: "Authentication"},
               {link: "/tutorials/session.html", text: "Session & cookies"},
               {link: "/tutorials/passport.html", text: "Passport.js"},
               {link: "/tutorials/typeorm.html", text: "TypeORM"},
@@ -73,6 +72,7 @@ module.exports = {
               {link: "/docs/scope.html", text: "Scope"},
               {link: "/docs/filters.html", text: "Filters"},
               {link: "/docs/interceptors.html", text: "Interceptors"},
+              {link: "/docs/authentication.html", text: "Authentication"},
               {link: "/docs/server-loader.html", text: "ServerLoader"},
               {link: "/docs/testing.html", text: "Testing"}
             ]
@@ -115,6 +115,7 @@ module.exports = {
               "scope",
               "filters",
               "interceptors",
+              "authentication",
               "server-loader",
               "testing"
             ]
@@ -126,7 +127,6 @@ module.exports = {
             collapsable: false,
             children: [
               "",
-              "authentication",
               "session",
               "passport",
               "typeorm",
@@ -147,7 +147,6 @@ module.exports = {
         },
 
         otherTopics: [
-          "/tutorials/authentication",
           "/tutorials/session",
           "/tutorials/passport",
           "/tutorials/typeorm",
@@ -173,6 +172,7 @@ module.exports = {
           "/docs/scope",
           "/docs/filters",
           "/docs/interceptors",
+          "/docs/authentication",
           "/docs/server-loader",
           "/docs/testing"
         ],

docs/docs/authentication.md

@@ -0,0 +1,41 @@
+---
+meta:
+ - name: description
+   content: Authentication configuration 
+ - name: keywords
+   content: ts.ed express typescript auth node.js javascript decorators
+---
+# Authentication
+## Usage
+
+Ts.ED use middleware to protect your route with your own strategy. To handle correctly a request and protect your endpoints,
+we have to use the @@UseAuth@@ decorator.
+
+<<< @/docs/tutorials/snippets/authentication/auth-example.ts
+
+::: tip
+If you planed to use `Passport.js`, it's recommended to follow the [Passport.js guide here](/tutorials/passport.md).
+:::
+
+Any middleware can be used as a authentication strategy. Just keep in mind, to works properly, the middleware must use @@EndpointInfo@@
+decorator to retrieve the endpoint context execution.
+
+Here an example of the a CustomAuth middleware with use the Passport.js method to check authentication:
+
+<<< @/docs/tutorials/snippets/authentication/auth-middleware.ts
+
+## Create your Auth decorator
+
+It could be practical to create you own Authentication decorator to reduce the amount of code.
+For example, if we use swagger, we have to configure some extra **security** and **responses** information and it can quickly become heavy. 
+
+Example:
+<<< @/docs/tutorials/snippets/authentication/auth-swagger-example.ts
+
+To avoid that, we can create a decorator which apply all of theses instructions automatically, like this:
+
+<<< @/docs/tutorials/snippets/authentication/auth-decorator-example.ts
+
+And use it on our controller and endpoints:
+
+<<< @/docs/tutorials/snippets/authentication/auth-custom-auth-example.ts

docs/docs/snippets/authentication/auth-custom-auth-example.ts

@@ -0,0 +1,11 @@
+import {Controller, Get} from "@tsed/common";
+import {CustomAuth} from "../decorators/CustomAuth";
+
+@Controller("/dashboard")
+@CustomAuth({role: "admin", scopes: ["email", "firstname"]})
+class DashboardCtrl {
+  @Get("/")
+  @CustomAuth({role: "admin", scopes: ["email", "firstname"]})
+  public getResource() {
+  }
+}

docs/docs/snippets/authentication/auth-decorator-example.ts

@@ -0,0 +1,18 @@
+import {IUseAuthOptions, UseAuth} from "@tsed/common";
+import {applyDecorators} from "@tsed/core";
+import {Responses, Security} from "@tsed/swagger";
+import {CustomAuthMiddleware} from "../guards/CustomAuthMiddleware";
+
+export interface ICustomAuthOptions extends IUseAuthOptions {
+  role?: string;
+  scopes?: string[];
+}
+
+export function CustomAuth(options: ICustomAuthOptions = {scopes: []}): Function {
+  return applyDecorators(
+    UseAuth(CustomAuthMiddleware, options),
+    Security("oauth", ...options.scopes!),
+    Responses(401, {description: "Unauthorized"}),
+    Responses(403, {description: "Forbidden"})
+  );
+}

docs/docs/snippets/authentication/auth-example.ts

@@ -0,0 +1,11 @@
+import {Controller, Get, UseAuth} from "@tsed/common";
+import {CustomAuthMiddleware} from "../guards/CustomAuthMiddleware";
+
+@Controller("/dashboard")
+@UseAuth(CustomAuthMiddleware, {role: "admin"}) // on class level for all endpoints
+class DashboardCtrl {
+  @Get("/")
+  @UseAuth(CustomAuthMiddleware, {role: "admin"}) // or for specific endpoints
+  public getResource() {
+  }
+}

docs/docs/snippets/authentication/auth-middleware.ts

@@ -0,0 +1,18 @@
+import {EndpointInfo, IMiddleware, Middleware, Req} from "@tsed/common";
+import {Forbidden, Unauthorized} from "ts-httpexceptions";
+
+@Middleware()
+export class CustomAuthMiddleware implements IMiddleware {
+  public use(@Req() request: Express.Request, @EndpointInfo() endpoint: EndpointInfo) {
+    // retrieve options given to the @UseAuth decorator
+    const options = endpoint.get(CustomAuthMiddleware) || {};
+
+    if (!request.isAuthenticated()) { // passport.js method to check auth
+      throw new Forbidden("Forbidden");
+    }
+
+    if (request.user.role !== options.role) {
+      throw new Unauthorized("Unauthorized");
+    }
+  }
+}

docs/docs/snippets/authentication/auth-swagger-example.ts

@@ -0,0 +1,18 @@
+import {Controller, Get, UseAuth} from "@tsed/common";
+import {Responses, Security} from "@tsed/swagger";
+import {CustomAuthMiddleware} from "../guards/CustomAuthMiddleware";
+
+@Controller("/dashboard")
+@UseAuth(CustomAuthMiddleware, {role: "admin"}) // on class level for all endpoints
+@Security("oauth2", "email", "firstname")
+@Responses(401, {description: "Unauthorized"})
+@Responses(403, {description: "Forbidden"})
+class DashboardCtrl {
+  @Get("/")
+  @UseAuth(CustomAuthMiddleware, {role: "admin"}) // or for specific endpoints
+  @Security("oauth2", "email", "firstname")
+  @Responses(401, {description: "Unauthorized"})
+  @Responses(403, {description: "Forbidden"})
+  public getResource() {
+  }
+}