feat(oauth): allow adding custom query params on authorization request (

#60)

* feat(oauth): allow adding custom params on authentication

* docs: add more info on oauth page

docs/configuration/oauth.md

@@ -1,6 +1,6 @@
 # OAuth login
 
-Besides the local email/password login strategy, the module supports login with OAuth2 providers such as Google, and Github. Note that the tokens are issued by the module's backend and not by the OAuth provider. Thus authorization for the provider's services is not possible.
+Besides the local email/password login strategy, the module supports login with OAuth2 providers such as Google, and Github.
 
 ::: warning Important
 Please note that `email` and `name` information are required for registration, otherwise not accessible error message will be returned.
@@ -22,13 +22,22 @@ export default defineNuxtConfig({
         authorizeUrl: "",
         tokenUrl: "",
         userUrl: "",
+        customParams: {},
       },
     },
   },
   // ...
 });
 ```
 
+To login with an OAuth2 provider the module implements this flow:
+
+1. Via `authorizeUrl`: it requests an authorization code from the provider with `scope` to get user info and `state` to maintain the redirection path of the previously visited protected page. The provider handles user authentication and consent.
+2. Via `tokenUrl`: it requests an access token from the OAuth2 authorization server with the authorization `code` returned earlier.
+3. Via `userUrl`: it requests user info with the access token returned earlier. The `scope` should permit getting the user `name` and `email` fields.
+4. The module checks if the user exists (stored in the database), if not it registers him.
+5. The module issues an access token and a refresh token for this new session. Note the tokens issued by the OAuth provider are omitted, they are only needed to get user info.
+
 The redirect URI to be set on `oauth` configuration should be the following:
 
 ```bash

src/runtime/server/api/login/[provider].get.ts

@@ -29,6 +29,7 @@ export default defineEventHandler(async (event) => {
     const authorizationUrl = withQuery(
       oauthProvider.authorizeUrl,
       {
+        ...oauthProvider.customParams,
         response_type: 'code',
         scope: oauthProvider.scopes,
         redirect_uri: redirectUrl,

src/runtime/types/config.d.ts

@@ -19,6 +19,7 @@ type OauthBase = Record<string, {
   authorizeUrl: string
   tokenUrl: string
   userUrl: string
+  customParams?: Record<string, unknown>
 }>
 
 type OauthGoogle = {
@@ -29,6 +30,7 @@ type OauthGoogle = {
     authorizeUrl: 'https://accounts.google.com/o/oauth2/auth'
     tokenUrl: 'https://accounts.google.com/o/oauth2/token'
     userUrl: 'https://www.googleapis.com/oauth2/v3/userinfo'
+    customParams?: Record<string, unknown>
   }
 }
 
@@ -40,6 +42,7 @@ type OauthGitHub = {
     authorizeUrl: 'https://github.com/login/oauth/authorize'
     tokenUrl: 'https://github.com/login/oauth/access_token'
     userUrl: 'https://api.github.com/user'
+    customParams?: Record<string, unknown>
   }
 }