OAuth is the base layer of the Dataporten platform, and most of the APIs require that you already have obtained an OAuth token. To obtain an OAuth token, you would first need to register your application/client, and then implement or configure the OAuth flow. We recommend that you learn to understand the fundamentals of OAuth before using the Dataporten platform.
Dataporten also have basic support for OpenID Connect, which is an identity layer on top of OAuth 2.0.
Registering your application
In order to access the Dataporten APIs, you would first need to register your application, and obtain the OAuth credentials for your application.
You may register your application using the Developer Dashboard.
When registering an application, you need to know the OAuth redirect URI endpoint of your application.
When you have successfully registered an application, you need to know the OAuth endpoint of Dataporten, in order to configure your application:
- Dataporten OAuth Provider Authorization endpoint
- Dataporten OAuth Provider Token endpoint
Obtaining an OAuth Token
To access the Dataporten APIs, you would need an OAuth Access Token. The OAuth Access Token represents an authenticated and authorized session for both your application and the end user accessing your application. This way your application may obtain information on behalf of the end user accessing your application.
Dataporten implements an OAuth 2.0 Server, a widely used open standard for issuing authorization tokens. Dataporten also supports the OpenID Connect standard, which represents a thin identity layer for authentication on top OAuth.
Consult the OAuth 2.0 Specifications for details about the protocols.
- OAuth 2.0
- The OAuth 2.0 Authorization Framework Specification (RFC6749)
- The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC6750)
Depending on the application mode, Dataporten supports three alternative authorization grant modes in OAuth 2.0:
- Authorization Code Grant, for traditional web services (with its own backend)
- Implicit Grant, for (client side only) web applications, mobile and desktop applications.
- Client Credentials Grant, for special use when there is no end user represented.
OAuth 2.0 client side is a very simple protocol, and may very well be implemented from scratch. However, there also exists a bunch of OAuth 2.0 libraries for a wide variety of programming languages that you may use if appropriate.
Here is an example of how to obtain an OAuth 2.0 Access Token using the authorization code flow.
First, the client generates an authorization request, and redirects the user to this endpoint:
Dataporten handles the authentication of the user and informs the user about what permissions the client is requesting.
First, user has to select which login provider to use for login. Typically, this means selecting the educational home institution of the user. On all subsequent logins, the user will instead see the account chooser.
In the authorization code flow, the authorization response involves a redirect back to the redirect_uri endpoint at the client backend, where a
code is one of the parameters. The
code may then be replaced with an access token.
Implicit grant flow
In contrast, with the implicit grant flow, the access token is returned directly at the redirect_uri, but within the hash fragment of the URL, leaving it accessible only to the frontend / client side.
Fetching the Access Token
The Dataporten OAuth 2.0 Token Endpoint requires the client to authenticate using the credentials obtained through the developer dashboard.
The request is authenticated by using HTTP Basic authentication using the client_id and the client secret.
The client application performs an Access Token Request to the token endpoint:
In return Dataporten returns a valid OAuth 2.0 Access Token representing both the client and the authenticated end user, with the appropriate permissions as requested on the Dataporten Dashboard and as granted by the end user.
Using an OAuth 2.0 Access Token
To use the OAuth 2.0 Bearer token, it has to be included in the
Authorization-header of the HTTP request, like this:
The details are specified in the specifications:
Now, as you have obtained an OAuth 2.0 token or an authenticated user, you can move on to play with all the Dataporten APIs. The first thing you might be interested in is learning more about the authenticated user: