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.

To register OIDC/OAuth applications use the Feide customer portal and get access for API in the Developer Dashboard.

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

Screenshot of adding redirect URI after login for OIDC-configuration

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&
scope=openid&
state=whatever

User authentication and provider discorvery#

Feide handles the authentication of the user and informs the user about what permissions the client is requesting. Read more about selecting user information and login provider for you service.

Screenshot of choose affiliation in Feide login page

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.

Authorization Grant#

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

Screenshot of accepting privacy policy in the Feide login page

Screenshot of accepting application right in the Feide login page

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
{ "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:

The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC6750)

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:

Obtaining userinfo