itsme® is a trusted identity provider allowing partners to use verified identities for authentication and authorization on web desktop, mobile web and mobile applications.
The objective of this document is to provide all the information needed to integrate the itsme® services using the OpenID Connect Core 1.0 specifications.
To simplify implementations and increase flexibility, OpenID Connect allows the use of a Discovery document, a JSON document containing key-value pairs which provide details about itsme® configuration, such as the URIs of the
Environment | URL |
---|---|
E2E | https://idp.e2e.itsme.services/v2/.well-known/openid-configuration |
PRODUCTION | https://idp.prd.itsme.services/v2/.well-known/openid-configuration |
Before you can integrate your application with itsme® service, you MUST provide us your organisation information and set up a project.
Fill in the form by clicking on the following url: https://docs.google.com/forms/d/e/1FAIpQLSdyfhKiiehNg4DhFzhQeHaj9EG2VeFoyPNVaI-TSwnG5WlFfw/viewform.
Once there, you will need to fill out a basic form with the following questions:
Our onboarding team will review your project and be in touch within 3 days. However, this should not prevent you from starting your integration.
Once you have created your organisation, the next step is to craft your URIs.
The asymmetric cryptographic keys are used to protect entitlement information between interested parties. The consistent way to represent a set of cryptographic keys in a JSON structure is called a JSON Web Key Set (JWK Set).
As itsme® only support the RSA cryptosystem, it requires that each party exposes its public keys as a simple JWK Set document on a URI accessible to all. For itsme®, this URI can be retrieved from the itsme® Discovery document, using the jwks_uri
key.
Your keys can be generated via Yeoman. To get started, install Yeoman and generator-itsme with NPM:
$ npm install -g yeoman generator-itsme
After installation, run the generator:
$ yo itsme
The generator will ask you if you have existing certificates or not. If so, provide the location of both certificates you wish to use. If you don’t have any certificates available, don’t worry. The generator will create everything for you.
The output of the tool are two keys, a private and a public one. The private set needs to be known only by you. You will need it to configure the itsme® client later on. The public set needs to be made available on a publicly reachable API endpoint directly, which means you can’t have a redirect set up for example.
This is the URI to which the Authentication Response should be sent: once the User has authorised the request and has been authenticated, itsme® will redirect him to your mobile or web application.
Regardless of the application you are building you should make sure that your redirect URI support the Universal links and App links mechanism. Functionally, it will allow you to have only one single link that will either open your desktop web application, your mobile app or your mobile site on the User’s device.
The OpenID Connect Core specification defines a number of parameters to integrate in the HTTPS GET query string: client_id
, response_type
, scope
and redirect_uri
. However, if you want to add additional parameters or asking for specific user attributes, OpenID Connect specify that additional parameters MAY or MUST be added to the Authentication Request as a JWT Payload in the request_uri
parameter.
The following validations should be done when setting up a request_uri
:
response_type
and client_id
parameters MUST be filled in the Authentication Request, since they are REQUIRED in the OpenID Connect Core specifications. The values for these parameters MUST match those in the Request Object, if present.scope
parameter is present in the Request Object value, a scope
parameter – containing the openid scope value to indicate to the underlying OpenID Connect Core logic that this is an OpenID Connect request – MUST always be passed in the Authentication Request.iss
(issuer) and aud
(audience) as members. The iss
value SHOULD be your Client ID. The aud
value SHOULD be Authorization Endpoint URI which can be retrieved in the itsme® Discovery document.request_uri
. Usage of localhost
is not permitted.When using the Login service, a request URI MAY be added. If used, the JSON object will look like :
{
"aud": "https://merchant.itsme.be/oidc/authorization",
"scope": "openid service:my_service_code profile email",
"redirect_uri": "https://i/redirect",
"response_type":"code",
"client_id":"my_client_id",
"acr_values":"tag:sixdots.be,2016-06:acr_advanced",
"iss":"my_client_id",
"nonce":"a_valid_nonce",
"state":"a_valid_state",
"claims":{
"userinfo":{
"tag:sixdots.be,2016-06:claim_eid":null,
"tag:sixdots.be,2016-06:claim_city_of_birth":null,
}
}
}
When using the Share data service, a request URI MUST be added, specifying at least one user attribute (aka. claim). The JSON object will look like :
{
"aud": "https://merchant.itsme.be/oidc/authorization",
"scope": "openid service:my_service_code profile email",
"redirect_uri": "https://i/redirect",
"response_type":"code",
"client_id":"my_client_id",
"acr_values":"tag:sixdots.be,2016-06:acr_advanced",
"iss":"my_client_id",
"nonce":"a_valid_nonce",
"state":"a_valid_state",
"claims":{
"userinfo":{
"tag:sixdots.be,2016-06:claim_eid":null,
"tag:sixdots.be,2016-06:claim_city_of_birth":null,
}
}
}
If using the Confirm service, a request URI MUST be added, specifying at least the template. The JSON object will look like :
{
"aud": "https://merchant.itsme.be/oidc/authorization",
"scope": "openid service:my_service_code profile email",
"redirect_uri": "https://i/redirect",
"response_type":"code",
"client_id":"my_client_id",
"acr_values":"tag:sixdots.be,2016-06:acr_advanced",
"iss":"my_client_id",
"nonce":"a_valid_nonce",
"state":"a_valid_state",
"claims":{
"userinfo":{
"tag:sixdots.be,2016-06:claim_eid":null,
"tag:sixdots.be,2016-06:claim_city_of_birth":null,
"sub":{ "value":"the_end_user_already_known_user_code" },
"tag:sixdots.be,2016-08:claim_approval_template_name":{ "essential": true, "value": "free_text" },
"tag:sixdots.be,2016-08:claim_approval_text_key": { "essential": true, "value": "This text will be shown to the user in the ISTME<sup>®</sup> app" }
}
}
}
There are currently two templates available. More information about these can be found here.
Send an email to [email protected] listing the two or three endpoints and we’ll make sure to complete the configuration for you in no time! We will get back to you with the following details which are needed when selecting a binding:
You will need to provide a button to allow your users to authenticate with itsme®. Upon clicking this button, we will open a modal view which contains a field that need to be filled by the end user with it’s phone number. Note that mobile web users will skip the phone number step, as they use the itsme® mobile app directly to authenticate.
itsme® provides a button generator for you to use for this purpose. In order to use the button generator, you will need to include the script in your HTML file.