API Gatekeeper

Note

The Feide customer portal has now replaced the Dataporten dashboard for most tasks. However, managing access to data must still be done from the dashboard.

API Gatekeeper is Feide’s functionality for access control of APIs. The API Gatekeeper enables you to make datasets available to third parties, with access control and authentication of clients and end users.

For applications where all functionality is separated into APIs, the API Gatekeeper can establish sessions and perform authentication between frontend and backend within your service.

Getting started with API Gatekeeper

The API Gatekeeper works as an HTTP proxy adding support for authentication and authorization.

Example

Let us say you operate an API at https://api.example.org.

First, register an API Gatekeeper using the dashboard.

You choose an identifier for the API on the form <myapi>.dataporten-api.no. This will be the hostname consumers of the API connect to.

You also register the URL where the API Gatekeeper can access your API endpoint. This endpoint must be secured by HTTPS.

Example of registering this API Gatekeeper using the dashboard:

Register new API gatekeeper screenshot

Register new API gatekeeper screenshot

In the dashboard, you see an API Access pane for your API Gatekeeper with a username and password that API Gatekeeper will use when accessing your API. The API gatekeeper will use HTTP Basic Authentication to authenticate.

In the API Scopes pane, you set up the access policy for the basic scope and add subscopes if needed.

Third party clients that want to access your API through the API Gatekeeper register a regular OIDC/OAuth Feide client and request access to your API under “3rd party APIs”. The client will use OIDC/OAuth to connect to the API Gatekeeper, which in turn accesses your API.

A request like this:

GET /foo/bar HTTP/1.1
Host: demoapi123.dataporten-api.no
Authorization: Bearer 12344567-1234-4998-1234-abbabababab

is passed on to your API like this:

GET /foo/bar HTTP/1.1
Host: api.example.org
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
X-Dataporten-clientid: 42b0c02e-0dda-4882-9da0-882a4b1abad6
X-Dataporten-userid: 76a7a061-3c55-430d-8ee0-6f82ec42501f
X-Dataporten-userid-sec: feide:andreas@uninett.no
X-Dataporten-gatekeeper: demoapi123
X-Dataporten-scopes: subscope1
X-Dataporten-token: abab6be7-8e87-4768-8026-e4266879a617
X-forwarded-for: 2001:700:1:21:ace8:7784:8016:8b0f
X-forwarded-proto: https

clientid is the client identifier of the requesting client.

userid is the authenticated end user’s Dataporten user identifier.

userid-sec is a list of secondary user keys, such as Feide ID. It is comma separated. It is included whenever the API is allowed access to at least one of the secondary user keys.

Read more about User IDs

gatekeeper is the identifier of the API gatekeeper

scopes contains the authorized subscopes of the request. It is included whenever there are any. It is comma separated.

token is an access token that the API can use to obtain information about groups and more.

forwarded-for and forwarded-proto identify the address and protocol of the requesting client.

Configuring your firewall

All requests coming from the Feide API Gatekeepers come from these IP ranges and IP addresses:

  • 158.36.86.32/27

  • 2001:700:0:4030::/61

  • 2a05:d014:909:ad00::/56

  • 2a05:d016:15b:5a00::/56

  • 13.49.2.131

  • 13.49.86.217

  • 13.49.194.146

  • 18.192.97.158

  • 18.193.183.248

  • 18.198.58.80

We recommend that you configure your API backend to only allow requests from these address ranges, so that you are not solely relying on the basic authentication described above.

Granting clients access to your API

In order for your API to be listed publicly for other organizations to use, it needs to checked as a Public API in the Basic info tab of the dashboard.

When client owners register new clients, they will find your third party APIs on the dashboard on a separate tab.

Depending on your policy, new clients may be automatically granted access to your API, or they will appear in a moderation queue for you at the dashboard.

In the dashboard, the API owner can moderate access to clients on the «Requests» and «Applications» tabs.

API owners who would like to automatically allow clients to access their APIs may configure this on the «Permissions» tab in the dashboard. (see below)

Granting access screenshot

Granting access screenshot

Managing access by subscope

A client is required to have the primary scope in order to access the API at all.

An API owner may configure any number of additional subscopes that have an independent moderation queue, allowing clients to e.g. be automatically assigned the primary scope, but need moderation to access clientonly or write scopes.

Managing acccess by organization

If you uncheck the Auto-accept checkbox in the Organization Accept Policy on the permissions page, you may select which organizations’ users will be able to log in to applications which use your API.

../../_images/org_policy.png

Press the Target organizations: Select button. A new page appears where you can select the organizations which should have access. When you are done, scroll down to the bottom and press Set organizations. Finally, press Save changes on the permissions page.

../../_images/org_select.png

Auto-accept can be set separately for the primary scope and each subscope. The set of target organizations will be the same for all scopes having auto-accept turned off.

Before users will be able to log in, the host organization’s administrator will have to approve the application and API. See Managing access to data.