Implementation Guide

This flow is meant to be used if there is a server-side application that can securely store secret keys (your client_secret), the authorization_code received from this flow is exchanged for an access token and refresh token. Steps in this guide is not intended for a Single Page Application (SPA) or a native application (mobile or desktop).

Note
 If you are planning to implement the Authorization Code Flow on a Single Page Application (SPA) or native application (mobile or desktop), you should consider using the PKCE extension guide instead.

Setting up

Before starting, you will need the client_id, the client_secret and scope from your Provider for your Connect Application.

Your Application will also need to handle HTTP requests on your redirect_uri.

Overview

Sequence diagram of OAuth2

Step 1 - Getting the authorization_code

Building the Login Link

The first step is to redirect your User (that you want to authenticate) to your Provider’s authorize URL (e.g. https://[providerFQDN]/oauth/authorize) with the following query parameters:

client_id
required 		string

Your Connect Application client ID
response_type
required 		string

Should be code
redirect_uri
required 		string

A valid redirect_uri (must match any one registered with your Connect Application)
scope
required 		string

A space-separated list of strings (e.g. openid phone email)
state
optional 		string

This parameter should be used for preventing Cross-site Request Forgery and will be passed back to you, unchanged, in your redirect URI (255 characters max).

A common redirect_uri would be https://your.website.com/oauth/callback, it can be anything you want but it must match one of the redirect_uris in your Connect Application configuration.

Code Sample

The following code uses Node.js and express with the pug rendering engine to illustrate a typical web application.

To do so, this application needs to display the correct link to Connect.

Caution
 The following code is not production ready 
// app.js
app.get("/", function(req, res) {
  res.render("index", {
    login_url: `https://[providerFQDN]/oauth/authorize?client_id=${client_id}&redirect_uri=${redirect_uri}&response_type=code&scope=${scope}`
  });
});
// templates/index.pug
a(href=login_url) Login

login_url is just a link that you can put anywhere on your page. The Authentication process with Connect starts as the User clicks on this link (and leaves your Application).

When the User has successfully authenticated on Connect, he or she will be redirected back to your Application using the redirect_uri with the authorization_code as a code parameter in the URL.

Using a Popup

Alternatively, you could use our Popup package to open a new window to do the authentication. You can find its documentation on npm:

Connect Popup
https://www.npmjs.com/package/@fewlines/connect-popup

However, note that in order to make things work, we need to wrap some data in the state parameter so you may need to shorten the value if you want to use a popup.

Step 2 - Getting the access_token

You need to take the authorization_code you just received and exchange it for an access_token.

To do that, you just need to do a POST HTTP request to the token URL of your Provider (e.g. https://[providerFQDN]/oauth/token) with the following parameters:

client_id
required 		string

Your Connect Application client ID
client_secret
required 		string

Your Connect Application client_secret key
code
required 		string

The code you got in the redirection query params
grant_type
required 		string

Should be authorization_code
redirect_uri
required 		string

Your redirect_uri

Following this request, you will get a response from Connect containing the following:

Note
 The length of tokens can vary and exceed 255 characters. Keep that in mind if you want to store them in a database as a VARCHAR will not be large enough.
Warning
 Both the access_token and the refresh_token are sensitive information and should NEVER be shared with your User’s browser as a mean of session identification (e.g. cookie).

Code Sample

The following code shows how your redirect_uri route can proceed to exchange the code with an access_token.

Note

For the sake of clarity, we’re using the following node packages:

  • request to make a POST HTTP request

  • jsonwebtoken to verify a JWT token
Caution
 The following code is not production ready 
// app.js
const request = require("request");
const jwt = require("jsonwebtoken");

app.get("/oauth/callback", function(req, res) {
  const payload = {
    client_id: client_id,
    client_secret: client_secret,
    code: req.query.code,
    grant_type: "authorization_code",
    redirect_uri: redirect_uri
  };

  request.post(
    "https://[providerFQDN]/oauth/token",
    { form: payload },
    function(err, httpResponse, body) {
      const json_response = JSON.parse(body);
      jwt.verify(json_response.access_token, client_secret, function(err, decoded_jwt) {
        if (err !== null) {
          // something went wrong
        } else {
          // Yay! 🤗 Your User has successfully authenticated
          // `decoded_jwt` contains the information about the token
        }
      });
    }
  );
});
Warning
 Once again: keep in mind that you should NOT share the access_token and refresh_token with the User’s browser (or any other unsecure device like a mobile) or any application that you do not trust.
Table of Content