feat: expose generateAuthrizationUri to decorator (#46)

Author: kamikazechaser

README.md

@@ -147,16 +147,24 @@ Assuming we have registered multiple OAuth providers like this:
 
 ## Utilities
 
-This fastify plugin adds 2 utility decorators to your fastify instance using the same **namespace**:
+This fastify plugin adds 3 utility decorators to your fastify instance using the same **namespace**:
 
 - `getAccessTokenFromAuthorizationCodeFlow(request, callback)`: A function that uses the Authorization code flow to fetch an OAuth2 token using the data in the last request of the flow. If the callback is not passed it will return a promise. The object resulting from the callback call or the promise resolution is a *token response* object containing the following keys:
   - `access_token`
   - `refresh_token` (optional, only if the `offline scope` was originally requested)
   - `token_type` (generally `'bearer'`)
   - `expires_in` (number of seconds for the token to expire, e.g. `240000`)
 - `getNewAccessTokenUsingRefreshToken(refreshToken, params, callback)`: A function that takes a refresh token and retrieves a new *token response* object. This is generally useful with background processing workers to re-issue a new token when the original token has expired. The `params` argument is optional and it's an object that can be used to pass in extra parameters to the refresh request (e.g. a stricter set of scopes). If the callback is not passed this function will return a promise. The object resulting from the callback call or the promise resolution is a new *token response* object (see fields above).
+- `generateAuthorizationUri(requestObject)`: A function that returns the authorization uri. This is generally useful when you want to handle the redirect yourself in a specific route. The `requestObject` argument passes the request object to the `generateStateFunction`). You **don't** need to declare a `startRedirectPath` if you use this approach. Example of how you would use it:
 
-E.g. For `name: 'customOauth2'`, both helpers `getAccessTokenFromAuthorizationCodeFlow` and `getNewAccessTokenUsingRefreshToken` will become accessible like this:
+```js
+fastify.get('/external', { /* Hooks can be used here */ }, async (req, reply) => {
+  const authorizationEndpoint = fastify.customOAuth2.generateAuthorizationUri(req);
+  reply.redirect(authorizationEndpoint)
+});
+```
+
+E.g. For `name: 'customOauth2'`, the helpers `getAccessTokenFromAuthorizationCodeFlow` and `getNewAccessTokenUsingRefreshToken` will become accessible like this:
 
 - `fastify.customOauth2.getAccessTokenFromAuthorizationCodeFlow`
 - `fastify.customOauth2.getNewAccessTokenUsingRefreshToken`

index.js

@@ -54,15 +54,21 @@ const oauthPlugin = fp(function (fastify, options, next) {
   const checkStateFunction = options.checkStateFunction || defaultCheckStateFunction
   const startRedirectPath = options.startRedirectPath
 
-  function startRedirectHandler (request, reply) {
-    const state = generateStateFunction(request)
+  function generateAuthorizationUri (requestObject) {
+    const state = generateStateFunction(requestObject)
     const urlOptions = Object.assign({}, callbackUriParams, {
       redirect_uri: callbackUri,
       scope: scope,
       state: state
     })
 
-    const authorizationUri = this[name].oauth2.authorizationCode.authorizeURL(urlOptions)
+    const authorizationUri = oauth2.authorizationCode.authorizeURL(urlOptions)
+    return authorizationUri
+  }
+
+  function startRedirectHandler (request, reply) {
+    const authorizationUri = generateAuthorizationUri(request)
+
     reply.redirect(authorizationUri)
   }
 
@@ -117,7 +123,8 @@ const oauthPlugin = fp(function (fastify, options, next) {
     fastify.decorate(name, {
       oauth2: oauth2,
       getAccessTokenFromAuthorizationCodeFlow,
-      getNewAccessTokenUsingRefreshToken
+      getNewAccessTokenUsingRefreshToken,
+      generateAuthorizationUri
     })
   } catch (e) {
     next(e)

test.js

@@ -330,6 +330,47 @@ t.test('options.generateStateFunction with request', t => {
   })
 })
 
+t.test('generateAuthorizationUri redirect with request object', t => {
+  t.plan(4)
+  const fastify = createFastify()
+
+  fastify.register(oauthPlugin, {
+    name: 'theName',
+    credentials: {
+      client: {
+        id: 'my-client-id',
+        secret: 'my-secret'
+      },
+      auth: oauthPlugin.GITHUB_CONFIGURATION
+    },
+    callbackUri: '/callback',
+    generateStateFunction: (request) => {
+      t.ok(request, 'the request param has been set')
+      return request.query.code
+    },
+    checkStateFunction: () => true,
+    scope: ['notifications']
+  })
+
+  fastify.get('/gh', function (request, reply) {
+    const redirectUrl = this.theName.generateAuthorizationUri(request)
+    return reply.redirect(redirectUrl)
+  })
+
+  t.tearDown(fastify.close.bind(fastify))
+
+  fastify.inject({
+    method: 'GET',
+    url: '/gh',
+    query: { code: 'generated_code' }
+  }, function (err, responseStart) {
+    t.error(err)
+    t.equal(responseStart.statusCode, 302)
+    const matched = responseStart.headers.location.match(/https:\/\/github\.com\/login\/oauth\/authorize\?response_type=code&client_id=my-client-id&redirect_uri=%2Fcallback&scope=notifications&state=generated_code/)
+    t.ok(matched)
+  })
+})
+
 t.test('options.generateStateFunction should be an object', t => {
   t.plan(1)
 
@@ -367,7 +408,7 @@ t.test('options.checkStateFunction should be an object', t => {
       auth: oauthPlugin.GITHUB_CONFIGURATION
     },
     callbackUri: '/callback',
-    generateStateFunction: () => {},
+    generateStateFunction: () => { },
     checkStateFunction: 42
   })
     .ready(err => {
@@ -412,7 +453,7 @@ t.test('options.generateStateFunction ^ options.checkStateFunction', t => {
       auth: oauthPlugin.GITHUB_CONFIGURATION
     },
     callbackUri: '/callback',
-    checkStateFunction: () => {}
+    checkStateFunction: () => { }
   })
     .ready(err => {
       t.strictSame(err.message, 'options.checkStateFunction and options.generateStateFunction have to be given')