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 yo 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

If you want to add additional parameters or asking for specific user attributes, you can add a request_uri parameter to the Authentication request containing a URL holding a signed and encrypted JWT.

The following validations should be done when setting up a request_uri :

  1. Create the Request Object using one of available bindings.
  2. 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.
  3. The Request URI MUST contain the port 443 as in this example: https://test.istme.be:443/p/test.
  4. The Request URI value is a URL using the https scheme.
  • When using the Login service, a request URI MAY be added.
  • When using the Share data service, a request URI MUST be added, specifying at least one claim (see binding samples).
  • When using the Confirm service, a request URI MUST be added, specifying at least the template (see binding samples).

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

Read more