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 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.
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.
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
:
request_uri
. Usage of localhost
is not permitted.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.