OAuth 2.0 Integration Guide

Setup in Northpass

1. Log in to your Northpass Admin account.
2. Open side navigation and go to Settings.
3. Change the tab to Authentication.
4. There click Edit.
5. In the Authentication tab dropdown, select Shared Accounts and make sure that OAuth 2.0 is marked below it.
6. Fill in the data in the permissions section:
   Client Identifier - CLIENT_ID. Unique string representing the registration information provided by the client. The Authorization server provides this value and is specific to Northpass.
   Secret Code - CLIENT_SECRET. The client secret. The Authorization server provides this value and is specific to Northpass.
   Authorization Endpoint - AUTHORIZATION_ENDPOINT. The authorization endpoint is used to interact with the resource server MUST first verify the identity of the resource owner. The Authorization server provides this value.
   Token Endpoint - TOKEN_ENDPOINT. The client uses the token endpoint to obtain an access token by presenting its authorization grant or refresh token. The Authorization server configuration provides this.
   Users API Endpoint - USER_API_ENDPOINT. This is provided by Resource server configuration. This is not specific to OAuth. It is an API endpoint, that can retrieve information about a single learner with the token received from the Token Endpoint.
   SSO issuer - name that is supplied to the identity provider.

1. Fill destination details.
2. (Optional) Fill Group organization.
3. Click Save button.

Authentication flow

1. The user clicks on the link to the Northpass school.
2. User is redirected to the AUTHORIZATION_ENDPOINT, with following GET request:
   
   client_id - CLIENT_ID.
   
   redirect_uri - YOUR_SCHOOL_URL/auth/oauth_base/callback.
   
   response_type - code.
   
   state - random string.
   
   Example:
   https://oauth_authenticator_example.com/auth/oauth_base/authorize?client_id=CLIENT_ID&redirect_uri=YOUR_SCHOOL_URL/auth/oauth_base/callback&response_type=code&state=STATE
3. After correct authorization, server redirects user to the YOUR_SCHOOL_URL/auth/oauth_base/callback with the following parameters:
   code - code that is used to obtain an access token.
   state - random string.
   Example:
   https://YOUR_SCHOOL_URL/auth/oauth_base/callback?code=CODE&state=STATE
4. Northpass sends a POST request to the TOKEN_ENDPOINT with the following parameters:
   Body:
   
   code - code that is used to obtain an access token.
   
   grant_type - authorization_code.
   
   redirect_uri - YOUR_SCHOOL_URL/auth/oauth_base/callback.
   
   Headers:
   
   Content-Type - application/json.
   
   Authorization - Authorization token is a string calculated by adding the word Basic separated by space with encoded with base64 USER_DATA. Where USER_DATA is CLIENT_ID:CLIENT_SECRET. So it looks this way: Basic base64(USER_DATA).
   
   Example:
   Endpoint: https://oauth_authenticator_example.com/oauth/token
   Body:

   {
     "code": "CODE",
     "grant_type": "authorization_code",
     "redirect_uri": "YOUR_SCHOOL_URL/auth/oauth_base/callback"
   }
   

   Headers:

   {
     "Content-Type": "application/json",
     "Authorization": "Basic Token"
   }
   

5. The authorization server responds with the following parameters:

   {
     "access_token": "TOKEN_GENERATED_BY_AUTHORIZATION_SERVER",
     "token_type": "Bearer",
     "expires_in": VALUE IN SECONDS,
     "refresh_token": "REFRESH TOKEN GENERATED BY AUTHORIZATION SERVER",
     "scope": "read",
     "created_at": TIMESTAMP
   }
   

6. Northpass sends GET request to the USER_API_ENDPOINT with the following headers:
   
   Authorization - Bearer TOKEN_GENERATED_BY_AUTHORIZATION_SERVER.
   
   Example:
   
   Endpoint: https://oauth_authenticator_example.com/api/v1/userinfo
7. User API responds with the following parameters:
   1. First possibility:

      {
        "first_name": "USER_FIRST_NAME",
        "last_name": "USER_LAST_NAME",
        "email": "USER_EMAIL",
        "user_id": "USER_ID",
        "lms": {
          "groups": [
            "GROUP_1_NAME",
            "GROUP_2_NAME"
          ]
        }
      }
      

   2. Second possibility:

      {
        "first_name": "USER_FIRST_NAME",
        "last_name": "USER_LAST_NAME",
        "email": "USER_EMAIL",
        "id": "USER_ID",
        "lms": {
          "groups": [
            "GROUP_1_NAME",
            "GROUP_2_NAME"
          ]
        }
      }
      

8. Northpass creates user with the following parameters:
   
   first_name - USER_FIRST_NAME.
   
   last_name - USER_LAST_NAME.
   
   email - USER_EMAIL.
   
   sso_uid - USER_ID.
   
   groups - adds learner to groups with names: GROUP_1_NAME, GROUP_2_NAME.
9. Northpass redirects authenticated user to the destination page.