DOCS: documenting oauth flow

docsfera.json

@@ -3470,7 +3470,7 @@
       }
     },
     "info": {
-      "title": "Maestro - teste new docsfera",
+      "title": "Maestro - feat/oauth-login",
       "description": "Documentation for Maestro gateway",
       "version": "1.0.0",
       "contact": {}

src/modules/auth/README.md

@@ -0,0 +1,38 @@
+# Auth
+
+## SSO/oAuth
+
+### Strategy
+We are using [PassportJs](https://www.passportjs.org/) to handle oAuth authentications.
+
+When the client (front end) makes a `GET /auth/oauth/{strategy}` Passport automatically redirects the user to the `strategy` login page. To do that we must configure and use a **Passport Strategy**. We must also have a callback route, conventionally `GET /auth/oauth/{strategy}/callback`, so the oAuth app can report the status of the user's login.
+
+- If the oAuth is successfull we call DUC's `AuthOauthSignIn` request that gets the tokens from Cognito and saves them on cache temporarily under a key we call `session`. Duc returns that `session` to maestro which then redirects the user to our app login page with that `session` as a query param.
+
+- If the oAuth login is not successfull for some reason or the user **does not** exist on DUC's database we redirect the user to our login page with an `error` and `error_description` as query params.
+
+### Routes
+
+So in order to have an SSO login, besides configuring the Strategy, we must have two routes for each Strategy, like in the example below:
+
+```ts
+  @Get('oauth/google')
+  @UseGuards(AuthGuard('google-login'))
+  googleOauth() {
+    this.logger.info('/oauth/google');
+    return true;
+  }
+
+  @Get('oauth/google/callback')
+  @UseGuards(AuthGuard('google-login'))
+  @Redirect()
+  async googleOauthCallback(@Req() req) {
+    const { url, email, token, language = 'pt-br' } = await this.callback(req);
+    if (url.searchParams.get('error')) {
+      this.logger.error('/oauth/google - ERROR');
+      return { url: url.href };
+    }
+    // ... Rest of the logic
+    return { url: url.href };
+  }
+```