To begin integrating OAuth 2.0, ensure you have the following details:

• Client ID and Client Secret: Unique credentials provided by your Identity Provider (IdP). For example, we'll use client_abc for the Client ID and client_secret_xyz for the Client Secret.
• Authorization Endpoint: The URL from your IdP to initiate the login process, such as https://your-company.com/authorize.
• Token Endpoint: The URL for exchanging an authorization code for an ID token and access token, like https://your-company.com/token.
• Users API Endpoint: The endpoint provided by the resource server to retrieve user information with the access token, https://your-company.com/userinfo.
• Issuer: The URL identifying the token's issuer, set as https://your-company.com.

Authentication Process

Authorization Request Phase

The OAuth 2.0 flow begins with the authorization request, redirecting users to the IdP's login page to authenticate and grant access.

Example authorization request URL:

https://your-company.com/authorize?
  response_type=code&
  client_id=client_abc&
  redirect_uri=https://your-company.northpass.com/auth/oauth_base/callback&
  state=xyzABC123

This URL directs the user to your IdP's login page, where they authenticate and grant the requested permissions.

Callback Request Phase

Upon user authentication and authorization, they're redirected back with the following callback URL:

https://your-company.northpass.com/auth/oauth_base/callback?
    code=authorization_code_from_idp&
    state=xyzABC123

Processing the Callback

1. Verify the state parameter to prevent CSRF attacks.
2. Exchange the authorization code for tokens by sending a request to the token endpoint with the Client ID and Client Secret in a Basic Authorization header.

Token exchange request example:

POST https://your-company.com/token HTTP/1.1
Authorization: Basic Y2xpZW50X2FiYzpjbGllbnRfc2VjcmV0X3h5eg==
Content-Type: application/json

{
  "code": "authorization_code_from_idp",
  "grant_type": "authorization_code",
  "redirect_uri": "https://your-company.northpass.com/auth/oauth_base/callback"
}

The IdP responds with tokens in JSON format:

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "read"
}

We use that access token to send a GET request to the UserInfo API Endpoint to retrieve user information.

GET https://your-company.com/userinfo HTTP/1.1
Authorization: Bearer eyJz93a...k4laUWw
Content-Type: application/json

The API responds with user information, which Northpass uses to create or update the user’s profile:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "user_id": "USER_ID" # or "id" attribute
}

This data creates the user's profile, facilitating a personalized and secure sign-in experience.

Dynamic Group Assignment

Our platform supports dynamic group assignment through custom attributes in the UserInfo response. This feature allows for seamless user categorization and access management based on predefined groups. To leverage this, include an additional attribute in the response as follows:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[email protected]",
  "user_id": "USER_ID", # or "id" attribute
  "lms": {
    "groups": ["GroupName1", "GroupName2", ...]
  }
}

In this structure, the lms object contains a groups array, which should list the names of the groups as strings. Users will be automatically added to the specified groups in this array upon signing in. This facilitates immediate and appropriate access to resources and functionalities aligned with the user's roles and permissions.

Finally, Northpass redirects the authenticated user to the destination page within the platform.