API Gatekeeper

API Gatekeeper is Dataporten's functionality for access controll of APIs. The API Gatekeeper enable you to make available datasets that could be of interest for service providers, with access control with authentication of clients and end users.

If you are developing mobile apps or other applications with a modern architechture where all the functionality is separated into APIs, then the API Gatekeeper can work well to establish sessions and perform authentication between frontend and backend within your service.

The API Gatekeeper works as an HTTP proxy adding convenient and easy support for authentication and authorization workflow management.

Example

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

First, register an API Gatekeeper using the Dataporten Dashboard.

You would need to register the URL of your API endpoint.

HTTP or HTTPS Dataporten requires you to register only secured HTTPS endpoints for your APIs.

Example of registering this API Gatekeeper using the Dataporten Dashboard:

In the Dataporten Dashboard, you see a trust pane for your API Gatekeeper, where you see a password that API Gatekeeper will use when accessing your API.

The default authentication type of your API, will be that API gatekeeper uses HTTP Basic Authentication to authenticate.

In the Scopes-pane, you setup the accept policy of the basic scope and can add subscopes.

Third party clients that want to access your API through the API Gatekeeper, register a regular client on Dataporten, and then request access to your API under "3rd party APIs". The third party client will then use OAuth to connect to your API through the API Gatekeeper. You choose the hostname yourself.

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-token: abab6be7-8e87-4768-8026-e4266879a617
X-Dataporten-Userid-sec: feide:andreas@uninett.no
X-forwarded-for: 2001:700:1:21:ace8:7784:8016:8b0f
X-forwarded-proto: https

The client id is the client identifer of the requesting client.

The userid is the authenticated end user's Dataporten user identifier.

UserID_sec is a list of secondary user keys, such as Feide ID and more. It is comma separated.

Read more about User IDs

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

Dataporten also issues a generic OAuth 2.0 Token to the API, that the API may use to obtain information about groups and more.

Configuring your firewall

All requests coming from the Dataporten API Gatekeepers comes from these IP ranges:

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

To safe-guard your API from attackers trying to bypass the API gatekeeper you may configure your API backend to only allow requests from these address ranges in addition to enforcing the basic authentication described above.

Developement and testing

If you are interested in experimenting with the API Gatekeeper to better understand how it works, 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 Dataporten Dashboard pointing on this.

Next, in order to test access to your API, you need a client setup with Dataporten, with granted access to your API. 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.

By default clients that would like to access your API would need to request access, which will end up in the moderation queue of the API owner.

In Dataporten Dashboard the API owner will be able to moderate access to clients on the «Requests» and «Applications» tabs.

API owners that would like to automatically accept clients to access their APIs, may configure this on the «Permissions» tab in Dataporten Dashboard. (see below)

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 sub-scopes that has an independent moderation queue, allowing clients to in example be automatically assigned the primary scope, but needs moderation to access clientonly or write scopes.

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 Dataporten Dashboard.

When client owners register new clients, they will find your third party APIs on the Dataporten 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.