The purpose of this document is to design an oauth flow that can be re-used in any plugin that requires oauth in order to talk to the system that is being integrated with.

1. General concepts

Before using OAuth2 usually user has to create an application via service site (e.g. Twitter) and register redirect uri, than receive a client_id and client_secret. Which will be used by an application during authentication.

The further steps are shown in the diagram below:

We are implementing grant types "Authorization Code Grant" and "Refresh Token". Other types are not suitable or rarely used. Click here for some context.

Input values of the module:

2. OAuth2 Implementation details

1. Plugin developer adds this to widget:

   Button "Authenticate via OAuth2":

   "plugin-function": {
     "method": "POST",
     "widget": "oauth2",
     "output-property": "void",
     "plugin-method": "oauth2"
   }

             Textbox:

           {
             "widget-type": "textbox",
             "label": "Refresh Token",
             "name": "refreshToken",
             "widget-attributes" : {
               "default": "${secure(myplugin_key)}"
             }
           }
   
   

2. User clicks button "Authenticate via OAuth2".

3. Backend handles the call and returns the following data to UI:

   callback_url=http://localhost:11011/oauth2_callback
   authUrl=https://www.facebook.com/dialog/oauth
   tokenUrl=https://graph.facebook.com/v3.3/oauth/access_token
   clientId=fgdsjglfdskgjrpestgreg
   clientSecret=ksgh43trtgreghdfgassa
   scope=readContacts+sendMessages
   secure_store_key=myplugin_key

4. UI opens the following URL:

   https://www.facebook.com/v3.3/dialog/oauth?
     response_type=code
     &client_id=gdsjglfdskgjrpestgreg
     &redirect_uri=http://localhost:11011/oauth2_callback
     &scope=readContacts+sendMessages

5. This shows a popurl window to user:
   
6. User enters his credentials and agrees to grant our applications permissions to "Read contacts and Send messages"

7. When #6 is done client Browser automatically issues this:

   http://localhost:11011/oauth2_callback
    ?code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3
    &state=xcoiv98y2kd22vusuye3kch

8. UI handles the call to "/oauth2_callback" and saves the code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3

9. UI makes a request to tokenUrl with the code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3 it previously received.

   https://graph.facebook.com/v3.3/oauth/access_token?
   grant_type=authorization_code
   &code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3
   &redirect_uri=http://localhost:11011/oauth2_callback
   &clientId=fgdsjglfdskgjrpestgreg
   &clientSecret=ksgh43trtgreghdfgassa

10. UI get request response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    Cache-Control: no-store
    Pragma: no-cache
    
    {
      "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "token_type":"bearer",
      "expires_in":3600,
      "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
      "scope":"readContacts+sendMessages"
    }

11. Now UI saves refresh_token it got to secure store with key myplugin_key, which was passed from backend. 
12. After this at some point user starts a pipeline
13. Plugin (backend) gets refreshToken from myplugin_key.

14. Than backend runs the following request to retrieve a short-lived accessToken:

    POST /token HTTP/1.1
    Host: server.example.com
    Content-Type: application/x-www-form-urlencoded
    
    https://graph.facebook.com/v3.3/oauth/access_token?
    grant_type=refresh_token
    &refresh_token=IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
    &client_id=s6BhdRkqt3
    &client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

15. Plugin uses acessToken it received to make requests by using the following header:

    Authorization: Bearer N2FmNzhhNGM2MTI5N2JhMWJlYjEdZjA0ZWM3ZTRhMTM1OGM0ODJjMzQzYjM7NTk3ZTEzNTVjZDczZTljMDk2MQ

Facebook case

All the APIs I checked: Google APIs, PayPal, WordPress, Microsoft Azure, Okta support refreshing access token. Actually this is parf of RFC. The only API which does not is Facebook. Instead they use concept they have made up called fb_exchange_token. Here's more info. Since facebook is widely spread, I suggest we should handle this separately. For facebook we should UI should put accessToken intead of refreshToken to secure store on step #11. And on step #14 backend needs a request to refresh it.