Authorization

Authorization is the process of a user giving you permission to access a specific resource (like some of their data). At first glance, this might seem similar to Authentication, but there is a key difference: Authentication is the process of you verifying a user's identity, mainly to log them in to your application. Sounds complicated? Don't worry, we'll explain the basics below and have comprehensive hands-on guides for each flow.

For Authorization, Eduplaces uses the industry standard OAuth 2.0 authorization framework. It allows users to grant external applications access to resources without compromising security. At Eduplaces, we use OAuth 2.0 to grant your application access to data about the user, such as their profile data and school information.

In addition to users granting access to their data, OAuth 2.0 also allows us to grant you access to API endpoints that are not directly related to a user. For example, you can use OAuth 2.0 to access the list of schools that activated your App as a tile. For more information on this, head over to our guide on Client Credentials.

In some details OAuth 2.0 is already a bit outdated. Therefor some recommendations we make and implementational details are based on the newer OAuth 2.1 standard draft. It's important to note that OAuth 2.1 is not a new protocol, but just a set of recommendations on how to use OAuth 2.0 in a more secure way. So if you are already familiar with OAuth 2.0, you will not have any problems with OAuth 2.1. You can also use the same libraries and tools.

To interact with our OAuth 2.0 server, you need to have valid client credentials: both a client ID and a client secret. We will provide you with these credentials when you start integrating your application with Eduplaces. Head over to our Getting Started page for more information on this.

Once permission is given, the authorization server provides an access token, essential for making API requests on behalf of the user or app. It is also possible to request a refresh token, which can be used to obtain a new access token when the current one expired and the user is not present to re-authorize your application. For example, if you want to check if a user is still a member of a group, you can use a refresh token to obtain a new access token and then make a request to access the users groups.

Available Flows

In general, the OAuth 2.0 standard defines multiple ways to request and receive an access token, also known as flows.

At Eduplaces we currently support the following flows:

• Authorization Code Flow with PKCE
• Authorization Code Flow (deprecated by OAuth 2.1)
• Client Credentials Flow
• Refresh Token Flow

We do not support the following flows (and also won't in the future):

• Implicit Flow (deprecated by OAuth 2.1)
• Resource Owner Password Credentials Flow (deprecated by OAuth 2.1)

Scopes

Access to protected resources is determined by one or multiple scopes. These scopes empower your application to access specific data or functionality representing a user (like accessing data about the users school, role or schooling level). Currently, Eduplaces mainly exposes scopes allowing you to access data. However, we will be exposing scopes for functionality in the future as well, granting your application the ability to perform actions on behalf of the user (like storing data about the users learning progress). The collection of scopes defined during authorization dictates the access rights users are prompted to approve.

For an in-depth look at our defined scopes and which data they will provide you access to, refer to the Scopes section.

Client Types

If you want to use OAuth 2.0 to access data about a user, you need to register your application with Eduplaces. In terms of OAuth 2.0, this application is called a client. OAuth 2.0 defines two types of clients: confidential and public.

The main difference between these two types is that confidential clients can keep their client secret confidential, while public clients cannot. For example, a server-based web application can keep its client secret confidential, while a mobile application cannot as it would be possible to decompile the application and extract the client secret. Also Single Page Applications (SPAs) are considered public clients, as the client secret would be part of the source code and therefore not confidential.

Not all flows are available for both client types as some flows require a client secret. See the table below for an overview of which flows are available for which client type.

If you are having a server-based web application as well as a mobile application for your product, just let us know and we will provide you with two sets of client credentials, one for each client type.