How to configure OAuth 2.0 as part of your Shared Accounts authentication method.
Note: Some OAuth 2.0 implementations may differ. Send an email to Support@Northpass.com at any point in the setup if your implementation differs or if you encounter errors while testing.
OAuth 2.0 Flow
Northpass supports OAuth 2.0 as an SSO integration, specifically the Authorization Code Grant flow. Click here to learn more.
Roles
The roles are outlined below. Click here to learn more.
-
Client : Northpass
-
Resource owner: Learner
-
Resource server: You company server
-
Authorization server: Your company server
Flow
-
Learner visits Northpass school website (example-- https://your-school.northpass.com)
-
The learner is redirected to the Authorization server “Authorize Endpoint” to authenticate and authorize. This is known as the “Authorization Request” and is described here.
-
After successful authentication and authorization, the learner is redirected back to Northpass. This is known as the “Authorization Response” as is described here. As explained, the redirect URL is provided by the “Authorization Request”.
-
In step 3), when the learner is redirected back to Northpass, Northpass will use the “authorization code” received in step 3) to obtain an access token from the “Token Endpoint”. This happens behind the scenes, and the learner will not see this happening. This is known as the “Access Token Request” and is described here.
-
The “Authorization Server” will return an access token. This is known as the “Access Token Response” and is described here.
-
Northpass will then use the access token returned in step 5) to access learner details from the Resource server at the configured “Users API Endpoint”. This is basically an API request for an individual resource. This request is not specified in the OAuth specification (other than utilizing the access token). This is described here.
-
Northpass will use the response from step 6) to identify the learner and create a session on Northpass for that learner. The learner will now be logged in to Northpass.
Integration Steps
The flow described above is the basic OAuth 2.0 Authorization Code Grant flow. There are details in each step of the flow that can change from implementation to implementation.
Authorize Request
-
The “redirect_uri” is optional, but Northpass will always provide it.
Token Request
-
The method of client authentication needs to be established. By default, Northpass will use Basic Authentication, uses the “Client Identifier” and “Client Secret”.
User API Endpoint Request
-
The method of authentication and format of returned data needs to be established so that Northpass can parse the incoming learner data. By default, Northpass assumes JSON, and a format as follows:
{
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"email": "EMAIL",
"lms": {
"groups": [
"GROUP_1",
"GROUP_2"
]
}
}
Important note: for the login process to be successful, not all the data presented in the sample endpoint userInfo response is necessary. The most important thing is that an email will appear that will allow us to identify the user in our system.
What will happen based on the data that is the response from the endpoint userInfo:
-
If the user logs in to the Northpass application for the first time, an account will be created for him, supplemented with the data from the response, and the user will be logged in.
-
If in the response from userInfo there will be namespace "LMS" with the key "groups", then the user will be automatically added to these groups and enrolled in all courses in a given group (this will happen only if the group already exists in Northpass).
Configuration in Northpass
Step 1
Select School Settings by hovering over your school logo in the top left-hand corner, followed by selecting Authentication.
Step 2
Click Edit in the upper right-hand corner.
Step 3
Select Shared Accounts from the dropdown.OAuth 2.0.
Step 4
Enter your Client Identifier. This value is provided by the Authorization server and is specific to Northpass. Click here to learn more about this value.
Step 5
Enter your Client Secret. This value is provided by the Authorization server and is specific to Northpass. Click here to learn more about this value.
Step 6
Enter your Authorize Endpoint. This is provided by the Authorization server configuration. It should be the same for all of your OAuth integrations. Click here to learn more about this endpoint.
Step 7
Enter your Token Endpoint. This is provided by the Authorization server configuration. It should be the same for all of your OAuth integrations. Click here to learn more about this endpoint.
Step 8
Enter your Users API Endpoint. This is provided by Resource server configuration. This is not specific to OAuth. It is an API endpoint, that can be used to retrieve information about a single learner with the token received from the Token Endpoint. Click here to learn more about this endpoint.
Step 9
Enter a URL that you’d like the learner to be redirected to when they click “Log Out” from your school website.
Step 10
Enter your SSO issuer.
Step 11 (Optional)
Choose a default group. If a default group is selected, then all learners who access the school will be added into the default group and gain access to the courses within the default group. Click here to learn more about managing course access.
Step 12
Click Save.
Get started sharing links to your school. Anyone with an account in your system will be able to authenticate upon visiting your school. Learners will only see the courses that they have been granted access to.