OAuth 2.0 Integration Guide
This guide is designed to assist you in integrating your Identity Provider (IdP) with our product using OAuth 2.0. Follow these steps to establish a secure authentication flow, enabling your users to access our product seamlessly with their existing credentials.
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 andclient_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
- Verify the
state
parameter to prevent CSRF attacks. - 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.
Updated 30 days ago