API Gatekeeper

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 identifer 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:

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

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.

Development and testing

If you are interested in experimenting with the API Gatekeeper, you may use the HTTPjs service.

Go to httpjs.net and register, and you will automatically obtain an API hostname. Register a new API gatekeeper in the dashboard pointing to this.

HTTPSjs screenshot

HTTPSjs screenshot

Next, in order to test access to your API, you need a client set up with Feide, with access to your API granted. You may then reuse the same token that you use for authentication, userinfo and groups to get access to this third party API. On the httpjs.net service, you will then see the content of the request and response that your API is sending for each request.

HTTPSjs screenshot

HTTPSjs screenshot

Granting clients access to your API

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

More fine-grained access control to API

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.

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

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