Authentication in the Open Data Hub

Deprecated since version 2021.08: Token-based authentication in the Tourism domain has been removed

New in version 2021.08: Keycloack as default authentication method for API v2 (all domains)

The authentication layer is currently intended for internal use only, therefore it is not necessary to use authentication to access data provided by the Open Data Hub.

While the Open Data Hub project strives to offer only Open Data, it relies on third-party Data Providers, which may not offer the whole content of a dataset for public use. For this reason, an authentication mechanism has been implemented, which does however have no impact on users and on their use of the data.

Indeed, authentication in Open Data Hub is mainly used when exposing data to the consumer, which means by the Reader and in every single web service accessing the Reader, to allow the access to closed data in each dataset only to those who are allowed to, i.e., developers and members of the Open Data Hub team.

In the remainder of this section, we describe how authentication works within the Open Data Hub, because this information is of interest to users that might become app developers for the Open Data Hub project; further information about how to use authentication can be found in the dedicated howto.

There are currently two different authentication methods available:

  • Keycloack is the default authentication server for all datasets that are accessed with the API v2.

  • The OAuth2 Authentication follows the RFC 6749 and is used for all the datasets in the mobility domain when using the legacy API v1.

Warning

The Token-based Authentication was used for the datasets in the tourism domain and is now not available anymore.

Keycloack for API v2

Keycloack Server is already used as authentication method for Open Data Hub's internal infrastructure. The same directions described in that section can be used.

OAuth2 Authentication

Warning

deprecated This authentication method is supported only for accessing datasets in the mobility domain with the API v1.

The OAuth2 authentication mechanism Authentication tokens are based on JSON Web Token (JWT) as defined in RFC 7519#section-3, to send claims.

For those not familiar with the OAuth2 mechanism, here is a quick description of the client-server interaction:

  1. The client requests the permission to access restricted resources to the authorisation server.

  2. The authorisation server replies with a refresh token and an access token. The access token contains an expire date.

  3. The access token can now be used to access protected resources on the resource server. To be able to use the access token, add it as a Bearer token in the Authorization header of the HTTP call. Bearer is a means to use tokens in HTTP transactions. The complete specification can be found in RFC 6750.

  4. If the access token has expired, you’ll get a HTTP 401 Unauthorized response. In this case you need to request a new access-token, passing your refresh token in the Authorization header as Bearer token. As an example, in Open Data Hub datasets Bearer tokens can be inserted in a curl call like follows:

    ~$ curl -X GET "$HTTP_URL_WITH_GET_PARAMETERS" -H "accept: */*" -H "Authorization: Bearer $TOKEN"
    

Here, $HTTP_URL_WITH_GET_PARAMETERS is the URL containing the API call and $TOKEN is the string of the token.

Authentication To Internal Infrastructure

Access to the Open Data Hub’s internal infrastructure requires authentication, which is provided by Keycloack, an Open Source software that provides Identity and Access Management. In a nutshell, it acts as a broker to provide Single Sign On to different web sites and services; it also seamlessly interacts with Kerberos. More information and use cases can be found in the official documentation.

Note

By internal infrastructure we mean also the access to Open Data that are already available to the Open Data Hub Team but not yet to the Data Consumers, and therefore require authentication.

Source code for both the authentication server and a few pre-cooked examples of applications configured to connect to it can be found in dedicated repository created by the Open Data Hub Team: the authentication server.

Quick howto

Note

This howto describes the old guidelines to access authentication to Open Data Hubs internal infrastructure. A newer version of odh-generic-client has been implemented, that does not require anymore credentials and a client_secret. Therefore, all curl examples below can be safely used without all the corresponding options; credentials can be used for testing purposes, as explained in the repository’s README.md file.

More information in the dedicated repository.

In order to access the internal infrastructure, you need first to get a token, then use it together with the API. Both steps can be achieved using command-line tools, for a programmatic access to the date, which is the method shown here.

Request an access token

In order to receive an access token, you need in advance to have credentials for the Open Data Hub. If you do not have them, please open a ticket on issues.opendatahub.bz.it or send an email to . The same holds, if you plan to create an application that retrieves closed data from the Open Data Hub. For this, also other OAuth2 flows exist.

With your username and password, and a client secret (my_username, my_password, the_client_secret), the access token is granted to you with the following call:

Listing 3 Receiving an access topic
~$ curl -X POST -L "https://auth.opendatahub.bz.it/auth/realms/noi/protocol/openid-connect/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=my_username' \
--data-urlencode 'password=my_password' \
--data-urlencode 'client_id=odh-generic-client' \
--data-urlencode 'client_secret=the_client_secret'

Since the token expires after a given amount of time, it might prove necessary to refresh it, an action that can be done by replacing the parameters given in the query above with

Listing 4 Refreshing the access token
~$ curl -X POST -L "https://auth.opendatahub.bz.it/auth/realms/noi/protocol/openid-connect/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=the_refresh_token' \
--data-urlencode 'client_id=odh-generic-client' \
--data-urlencode 'client_secret=the_client_secret'

Here, use the refresh token received from Listing 3.

Retrieve data with the token.

Once you received the access token, it is easy to use it in actual requests. The following API call shows how to get all snames and mvalues from the VMS dataset:

Listing 5 Retrieving data with the access token
~$ curl -X GET "https://mobility.api.opendatahub.bz.it/v2/flat/VMS/*/latest?select=sname,mvalue" \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer your-access-token'

Currently, data retrieved from the Open Data Hub are always open, except for some of the latest values and historical data: Only a subset of m-prefixed data from the /latest and /from/to API calls can be closed date. See section Structure of the API calls and Payload) for more information about the API calls.