OAuth 2.0

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.

Developer Dashboard

When registering an application, you need to know the OAuth redirect URI endpoint of your application.

HTTP or HTTPS For development you are allowed to use unsecured redirect_uri endpoints. This will result in a highlighted warning for the end user during login process. For an application in production you are required to only use HTTPS secured endpoints.

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
https://auth.dataporten.no/oauth/authorization
Dataporten OAuth Provider Token endpoint
https://auth.dataporten.no/oauth/token

For mobile applications you may want to use a custom URL scheme for your redirect URI, such as yourapplication://.

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.

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.

Authorization Request

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:

	https://auth.dataporten.no/oauth/authorization?
		client_id=42934c73-6fae-4507-92a4-c67f87923aa9&
		response_type=code&
		redirect_uri=https://example.org/callback&
		state=f47282ec-0a8b-450a-b0da-dddb393fbeca
	

User authentication

Dataporten handles the authentication of the user and informs the user about what permissions the client is requesting.

Provider Discovery

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.

Feide Login

User enter his/her username and password to login.

Authorization Grant

User gets information about what permissions the client is requesting, and decides whether to accept this.

Authorization Response

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.

HTTP/1.1 302 Found
Location: https://example.org/callback?\
  code=0f8cf5fa-dc3f-4c9d-a60c-b6016c4134fa&
  state=f47282ec-0a8b-450a-b0da-dddb393fbeca

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:

POST /oauth/token HTTP/1.1
Host: auth.dataporten.no
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=0f8cf5fa-dc3f-4c9d-a60c-b6016c4134fa
&client_id=57260bd1-fb74-485c-96a3-f0c7e96ed4db&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback

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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
	"access_token":"083a7ef0-ea97-49ec-8804-379dc1e9b54c",
	"expires_in":3600,
	"scope": "userid profile groups"
}

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:

GET /userinfo HTTP/1.1
Host: auth.dataporten.no
Authorization: Bearer 083a7ef0-ea97-49ec-8804-379dc1e9b54c

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: