Obtaining tokens with Feide

Most of the APIs of the Feide platform require that you have obtained a token with OpenID Connect (OIDC). You need to register your application/client and implement or configure a flow. We recommend that you gain a basic understanding of OpenID Connect and OAuth before using the Feide platform. OAuth 2.0 is a general purpose framework for web authorization, and OIDC is an identity layer on top of it.

Registering your application

In order to access the Feide APIs, you need to register your application and obtain credentials for it.

It is not yet possible to register OIDC/OAuth applications using the regular Feide customer portal. For now, you may register your application using the Developer Dashboard.

Developer Dashboard

When registering an application, you need to know the redirect URI endpoint for it.

Registering new application screenshot

Registering new application screenshot

HTTP or HTTPS For development you are allowed to use unsecured redirect_uri endpoints. This will result in warnings 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 OIDC/OAuth endpoints of Feide, in order to configure your application:

Feide OIDC discovery endpoint:

https://auth.dataporten.no/.well-known/openid-configuration

The discovery endpoint will tell you that the other endpoints are:

Feide OIDC/OAuth Authorization endpoint

https://auth.dataporten.no/oauth/authorization

Feide OIDC/OAuth Token endpoint

https://auth.dataporten.no/oauth/token

Feide OIDC Userinfo endpoint

https://auth.dataporten.no/openid/userinfo

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

Obtaining an Access Token

To access the Feide APIs, you need an Access Token. The Access Token represents an authenticated and authorized session at your application for the end user. This way your application may obtain information on behalf of the end user.

Consult the OpenID Connect and OAuth 2.0 Specifications for details about the protocols.

Depending on the application mode, Feide supports three alternative authorization grant modes in OIDC/OAuth:

  • Authorization Code Grant, recommended for all application types.
  • Implicit Grant, formerly recommended for (client side only) web applications, mobile and desktop applications.
  • Client Credentials Grant, for special use when there is no end user represented.

Implicit grant used to be recommended for mobile, native and single page applications, but best current practice is to use authorization code grant with Proof Key for Code Exchange (PKCE).

OIDC/OAuth 2.0 libraries are available for a wide variety of programming languages.

Authorization Request

Here is an example of how to obtain an 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

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

Screenshot of login provider discovery

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.

Screenshot of Feide login page

Feide Login

User enters his/her username and password to login.

Screenshot of authorization grant page

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 Feide OIDC/OAuth Token Endpoint requires the client to authenticate using the credentials obtained through the developer dashboard.

The request is authenticated with 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

Feide returns a valid Access Token associating the client with the authenticated end user and a set of permissions. The permissions are as requested on the dashboard and approved 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":28800, "scope": "openid userid profile groups" }

Using an Access Token

To use the access 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 a token for an authenticated user, you can move on to play with all the Feide APIs. The first thing you might be interested in is learning more about the authenticated user: