API Gatekeeper is Dataporten’s functionality for access controll of APIs. The API Gatekeeper enables 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.
Getting started with API Gatekeeper¶
The API Gatekeeper works as an HTTP proxy adding convenient and easy support for authentication and authorization workflow management.
Let us say you operate an API at
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 an API Access 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 API Scopes pane, you set up 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-Userid-sec: feide:firstname.lastname@example.org X-dataporten-gatekeeper: demoapi123 X-dataporten-scopes: subscope1 X-forwarded-for: 2001:700:1:21:ace8:7784:8016:8b0f X-forwarded-proto: https X-dataporten-token: abab6be7-8e87-4768-8026-e4266879a617
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. It is included whenever the API is allowed access to at least one of the secondary user keys.
Gatekeeper is the identifier of the API gatekeeper forwarded-for and forwarded-proto identify the address and protocol of the requesting client.
Scopes contains the authorized subscopes of the request. It is included whenever there are any. It is comma separated.
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:
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 set up with Dataporten, 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.
Granting clients access to your API¶
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 allow 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 have
an independent moderation queue, allowing clients to e.g. be
automatically assigned the primary scope, but need moderation to access
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.