Using Dataporten with Client Credentials Flow

OAuth defines many different flows, depending on the use case. One of these flow does not include an authenticated end-user. This is called the Client Credentials flow. This flow allows a client to immediately obtain an OAuth Access token without involving any end-users. This flow is typically used in system to system interactions.

Most of the built in APIs on Dataporten requires the enduser to be authenticated, but is very relevant for access to third party APIs protected by the Dataporten API Gatekeeper. A good practice when desining APIs to access user data is to prepare for access both from systems and systems on behalf of authenticated end-users.

Any clients can be used with client credentials flow, and no special steps is needed in order to prepare a client registration for using client credentials flow.

Here are some references:

To obtain an access token, the client must send a GET request to the Dataporten token endpoint, authenticated with the client id and client secret, using a form post (application/x-www-form-urlencoded). The query string parameter grant_type=client_credentials identifies the use of client credentials flow, and Dataporten with issue a token that is not associated with any end-user.

Here is an example curl command to obtain an access token:

export CLIENT_ID=4cc40647-0d56-4de2-9f8f-975ff1ca55a8
export CLIENT_SECRET=b54cbb37-1a75-41bc-8471-c44045d6b0e2
curl https://auth.dataporten.no/oauth/token -u $CLIENT_ID:$CLIENT_SECRET -d 'grant_type=client_credentials'

Here is an example of expected output:

{
    "access_token": "9c256322-7c11-4220-93d6-fc5ffad3cb13",
    "token_type": "Bearer",
    "expires_in": 28799,
    "scope": "gk_kdto99 gk_tokenissuer"
}

Notice in particular scopes for accessing third party APIs. They are all prefixed with gk_. Other scopes are mostly relevant only when a user is authenticated. In example you may not use the userinfo endpoint with a token obtained through client credentials flow, even if you have in example the profile and email scope.

Accessing a protected third party API using such a access token is no different from using regular access tokens.

GET /foo/bar HTTP/1.1
Host: kdto99.dataporten-api.no
Authorization: Bearer 9c256322-7c11-4220-93d6-fc5ffad3cb13

When preparing an API for use with system client, make sure that you verify whether or not the request is a system request or an authenticated user request.

Requsts containing a X-Dataporten-Userid header is representing an authenticated user. And requests without this header is system requests obtained using client credentials flow.

If your system is granted permissions to APIs, make sure to verify that the token is not representing a user. Depending on your configuration it might be possible for end users to obtain access to tokens and these should not be confused with system tokens.