Identification and Authentication
This page is part of the Developer Documentation and zooms in on how identification and authentication works in JoinData. All our services require a security token to use. Our Identification and Authentication Service must be used to retrieve a token. There are also personal accounts that give you to access our My JoinData portal where you can create manage and report on your JoinData projects.
Note: the EDI-Circle API uses a different authentication system. This will be aligned with the authentication as described in this document.
- Client Accounts
- Public Client
- Confidential Client
- When to use what
- Personal Accounts and Test Accounts
- Getting the Credentials
Client Accounts
Your software requires an account to call our API’s. We use the commonly used OAuth2 with OpenID Connect protocol.
Your application needs a client account to be able to access our API’s. You will receive accounts for our integration environment from your JoinData contact person. When you are ready to go to production, you will receive the production account.
Depending on how your software is deployed there are different accounts. If your software is single tenant, e.g. you typically have a single user (farmer) in your system, or if your software doesn’t run on your own hardware but instead on a farmer’s device (e.g., an on-premise company management system or mobile app) you will get a public client. If you access data of multiple farmers at the same time and the software runs on your own servers, you may apply for a confidential client.
Using the client credentials you can retrieve tokens. Typically, there are two types of tokens: an access token that gives you access to our API’s for a limited time, and a refresh token that allows you to fetch a new access token.
For those familiar with OpenID Connect, here are the most important URL’s:
Production
- the well-known endpoint, describing the configuration:
https://production.join-data.net/auth/realms/datahub/.well-known/openid-configuration - the authorization endpoint, for authenticating the farmer:
https://production.join-data.net/auth/realms/datahub/protocol/openid-connect/auth - the token endpoint, for retrieving tokens:
https://production.join-data.net/auth/realms/datahub/protocol/openid-connect/token
Integration
- the well-known endpoint, describing the configuration:
https://integration.join-data.net/auth/realms/datahub/.well-known/openid-configuration - the authorization endpoint, for authenticating the farmer:
https://integration.join-data.net/auth/realms/datahub/protocol/openid-connect/auth - the token endpoint, for retrieving tokens:
https://integration.join-data.net/auth/realms/datahub/protocol/openid-connect/token
For developers unfamiliar with OAuth2, we recommend to search for an existing library that fits your platform. For reading material, the sites https://aaronparecki.com/oauth-2-simplified/ and https://oauth.net/2/ are good resources.
To help you interpret the terms used in OAuth2:
- Client: that would be (the account used by) your application;
- Resource Server: that would be JoinData’s Datahub API’s;
- Authorization Server: that would be JoinData’s IAM (the endpoints listed above);
- Resource Owner: that would typically be the farmer.
Public Client
The most common account is a public client (in OAuth2 terminology), which allows you to call our API’s on behalf of a farmer. Using the OAuth2 Authorization Code Flow, your application allows a farmer to login and retrieve a token specifically for your application. Using that token you can then call our API’s. Note that this token is specifically limited to this farmer.
The Onboarding Client can help you with all this; it is a convenient javascript library provided by JoinData which is meant for integrating JoinData into your (web) application. It implements the Authorization Code Flow, logs in the farmer, and can ask for consent for a specific purpose and returns the farmers identification as well as if he/she has accepted your purpose.
Note that the redirect url, the one where JoinData redirects back to, is only configurable by JoinData for security reasons. By default, the most common redirect urls for developer workstations are created on the integration environment:
When you are close to production, JoinData will ask you for the production redirect url’s so that your production account can be set up.
You can also use the token retrieved by following the authorization code flow (or by calling the onboarding client) to authenticate the user against your own systems. The token includes the company for which the user is authorised (to use the JoinData services). This would typically be the chamber of commerce number or equivalent scheme in your country.
Confidential Client
If your application does not interact with a farmer, e.g. you are building a backend system that aggregates over many farms, you may ask for service-client-credentials. This allows for server2server communication without interaction with the farmer. Tokens retrieved with this client will not have a scope limited to a single farmer but gives the client full access to all data (that you are mandated for). You will then use the OAuth2 Client Credentials Flow.
You can also use our authentication service to authenticate farmers for your own application. If you need a way to login farmers, you can use our authentication service as a trusted source.
When to use what
If you need to ask for consent of the farmer, use the onboarding client (and thus the authorization code flow). If you have a public client, the application runs in an environment you do not control (e.g. an on premise farm management system), you also need to use the authorization code flow.
If you already have approved participations and you fully control the environment the software runs on, use the client credentials flow.
Personal Accounts and Test Accounts
To be able to access My JoinData, our website for managing your account, you need a personal account. This account is strictly personal and gives you access to use JoinData on behalf of a company. A personal account can be linked to a farmer or to a partner. A farmer personal account allows you to access My JoinData from a perspective of that farmer and thus allowing you to grant or revoke mandates and inspect data usage of that farm. A partner personal account allows you to access My JoinData for Partners where you can view the data from an application provider or data source perspective. Here you can create and update purposes and participations.
We use an off-the-shelf identity broker that we have integrated with a.o. the Dutch eHerkenning to authenticate users. eHerkenning is commonly used by farmers (and other entrepreneurs) in the Netherlands. This provides us (and optionally our customers) a way to authenticate natural persons and see if they are authorised to make (JoinData datahub) decisions for a company (KVK). Other authentication mechanisms, such as the eIDAS family of national (European) authentication mechanisms will become available soon.
When you use My JoinData or My JoinData for Partners for the first time, you need to login using one of the provided methods. You will be asked to create an account and accept the terms and conditions. The websites can be found at:
Production
- https://production.join-data.net/my-join-data(for a farmer account)
- https://production.join-data.net/my-join-data-partners (for a partner account)
Integration
- https://integration.join-data.net/my-join-data(for a farmer account)
- https://integration.join-data.net/my-join-data-partners (for a partner account)
On the production environment, the use of a strong and official authentication mechanism is required. E.g., in the Netherlands this means that the use of eHerkenning is compulsary. These requirements are different per country.
Please note that some of these authentication methods have a strict separation between test and production environments and thus that you may require a different set of credentials for these environments. For testing purposes only, it is possible to receive an e-mail/password account for both the authorising (i.e. farmer) and authorised (i.e. application owner) companies. These accounts can only be used on our integration environment. To request such an account, please contact tech@join-data.nl. You can also use one of the supported authentication methods which offers a more realistic experience.
Getting the Credentials
In order to gain acces to JoinData account, a client and secret are needed. These credentials will be provided to you by the JoinData support-desk. The client along with the documentation will be provided by your JoinData contact person. The secrets are distributed via a different channel, normally that would be via text message to your mobile phone.