Developer platform

Introduction

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.

itsme® Discovery document

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

Authorization, Token and userInfo Endpoints
Supported claims
JWKSet URL
…

Environment	URL
E2E	https://idp.e2e.itsme.services/v2/.well-known/openid-configuration
PRODUCTION	https://idp.prd.itsme.services/v2/.well-known/openid-configuration

Pre-requisites

Before you can integrate your application with itsme^® service, you MUST provide us your organisation information and set up a project.

Creating an organisation

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:

Contact details such as your email, name, phone number
Organisation details as shown on the company register for your jurisdiction.
Information about the project you want to set-up and the use case you have in mind
itsme^® terms and conditions. If you require a copy of this please contact [email protected]

Our onboarding team will review your project and be in touch within 3 days. However, this should not prevent you from starting your integration.

Crafting your URIs

Once you have created your organisation, the next step is to craft your URIs.

Cryptographic keys URI

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.

Redirect URI

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.

Request URI

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 :

The values for the 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.
Even if a 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.
The Request Object MAY be signed using the JSON Web Signature (JWS). If signed, the Request Object SHOULD contain the claims 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.
The Request Object MAY also be encrypted using JSON Web Encryption (JWE). In this case, it MUST be signed then encrypted, with the result being a Nested JWT.
You need to store the Request Object resource remotely at a URL the the Authorization Server can access. This URL is the Request URI, request_uri. Usage of localhost is not permitted.
The Request URI MUST contain the port 443 as in this example: https://test.istme.be:443/p/test.
The Request URI value is a URL using the https scheme.

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.

Exchanging your URIs

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:

client ID
service code

Front-end integration

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.

Get your bindings

.NET

$ dotnet add itsme