An Identity and Access Management platform is a service that allows companies to manage identities in a centralized way. These identities can be collected from different parties (Identity Providers) and different ways can be offered to end-users to prove their identity (password, itsme…).
Integrating itsme® on an IAM platform
Most IAM platforms allow for the usage of different Identity Providers (IdP), either as pre-configured partners or via standardized communication protocols to be configured with the right parameters.
OpenId Connect is the most common of those protocols and the one that itsme® strictly adheres to, which means that itsme® can be used as an IdP on pretty much any IAM platform. However, depending on the way each platform implemented the protocol and on the configurability they offer, not all features of itsme® will always be available. In general, we outline 3 attention points:
1) Type of service from itsme®: In general, only Identification and Authentication are available through an IAM platform. The Confirmation service from itsme® implies not only data communication from itsme® to the platform, but also communication from the platform to itsme® of the content to be confirmed. IAM platforms in general are not equipped for bi-directional communication.
2) Authentication Method: itsme® allows partners to authenticate via 2 of the authentication specified by OpenId Connect: private_key_jwt is the most secure way, relying on asymmetric cryptography, while client_secret_post relies on symmetric cryptography. Most platforms will only support integration with itsme® through the Client Secret option either because they don’t support private_key_jwt at all or because they have only basic support for it, not allowing signed and encrypted tokens at each step of the flow.
3) Available attributes: While itsme® offers a broad range of identity attributes for each user (called “claims” in OIDC), not all IAM platforms allow you to take advantage of all claims:
OIDC makes use of the concept of “scopes”, regrouping a predefined set of claims. Some platforms only allow to request scopes, not individual claims, making it impossible to retrieve claims that are not part of a scope.
Most of our claims are returning a string value (“Name”:”John Smith”) but some are returning a structured JSON object, like address: {“street_adress”:”Station Street 34”, “postal_code”:”12345”}. Some platforms are only able to handle simple strings, not objects.
Based on past experiences, we put together a list of the main platforms we encountered with the characteristics we noticed for each of them. This table is given without any formal guarantee and some of this information might be outdated when you read it.
Platform
Supported claims
Note
MS Azure AD B2C
String only
The GUI "User Flow" method only gives access to sub, name and email. Other claims require to use the Identity Experience Framework with custom policies, configured via complex XML files. Client Secret only.
ForgeRock Identity Platform
All
Complete support of jwt_private_key and Client Secret
Amazon Cognito
Scopes only
Client Secret only
Auth0
Scopes only
Client Secret only
Okta
Scopes only
Client Secret only
+ IAM - itsme OIDC DocumentationIAM | itsme OIDC Documentation
What is an IAM platform?
An Identity and Access Management platform is a service that allows companies to manage identities in a centralized way. These identities can be collected from different parties (Identity Providers) and different ways can be offered to end-users to prove their identity (password, itsme…).
Integrating itsme® on an IAM platform
Most IAM platforms allow for the usage of different Identity Providers (IdP), either as pre-configured partners or via standardized communication protocols to be configured with the right parameters.
OpenId Connect is the most common of those protocols and the one that itsme® strictly adheres to, which means that itsme® can be used as an IdP on pretty much any IAM platform. However, depending on the way each platform implemented the protocol and on the configurability they offer, not all features of itsme® will always be available. In general, we outline 3 attention points:
1) Type of service from itsme®: In general, only Identification and Authentication are available through an IAM platform. The Confirmation service from itsme® implies not only data communication from itsme® to the platform, but also communication from the platform to itsme® of the content to be confirmed. IAM platforms in general are not equipped for bi-directional communication.
2) Authentication Method: itsme® allows partners to authenticate via 2 of the authentication specified by OpenId Connect: private_key_jwt is the most secure way, relying on asymmetric cryptography, while client_secret_post relies on symmetric cryptography. Most platforms will only support integration with itsme® through the Client Secret option either because they don’t support private_key_jwt at all or because they have only basic support for it, not allowing signed and encrypted tokens at each step of the flow.
3) Available attributes: While itsme® offers a broad range of identity attributes for each user (called “claims” in OIDC), not all IAM platforms allow you to take advantage of all claims:
OIDC makes use of the concept of “scopes”, regrouping a predefined set of claims. Some platforms only allow to request scopes, not individual claims, making it impossible to retrieve claims that are not part of a scope.
Most of our claims are returning a string value (“Name”:”John Smith”) but some are returning a structured JSON object, like address: {“street_adress”:”Station Street 34”, “postal_code”:”12345”}. Some platforms are only able to handle simple strings, not objects.
Based on past experiences, we put together a list of the main platforms we encountered with the characteristics we noticed for each of them. This table is given without any formal guarantee and some of this information might be outdated when you read it.
Platform
Supported claims
Note
MS Azure AD B2C
String only
The GUI "User Flow" method only gives access to sub, name and email. Other claims require to use the Identity Experience Framework with custom policies, configured via complex XML files. Client Secret only.
ForgeRock Identity Platform
All
Complete support of jwt_private_key and Client Secret
The concepts of JWT, JWS, JWE and JWK are part of the JSON Object Signing and Encryption (JOSE) framework that intends to provide a method to securely transfer claims between parties.
All these technologies can be used collectively to encrypt and/or sign content using a variety of algorithms. While the full set of permutations is extremely large, and might be daunting to some, it is expected that most applications will only use a small set of algorithms to meet their needs.
Definitions
The JSON Object Signing and Encryption (JOSE) framework consists of several technologies:
JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure, as the plaintext of a JSON Web Encryption (JWE) structure or enclosed in another JWE or JWS structure to create a Nested JWT, enabling nested signing and encryption to be performed. In fact a JWT does not exist itself — either it has to be a JWS and/or a JWE. It’s like an abstract class — the JWS and JWE are the concrete implementations.
JSON Web Signature (JWS) represents signed content using JSON data structures and base64url encoding as defined in the specifications.
JSON Web Encryption (JWE) specification standardizes the way to represent an encrypted content in a JSON-based data structure.
JSON Web Key (JWK) defines a consistent way to represent a cryptographic key in a JSON structure which is used to sign (JWS) and/or encrypt (JWE) a specific content. The JSON Web Key Set (JWKS) extension defines a consistent way to represent a set of cryptographic keys in a JSON structure. 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.
Your JWK Set document MUST be accessible via the URI communicated when setting up your project in the itsme® B2B portal or via email to onboarding@itsme-id.com.
Creating your JWK Set URI
The JWK is nothing more than another representation of the (public) key of a certificate keypair and the JWK Set is simply a list of one or more JWK.
So, you need to have/create your certificate key pairs (a key pair consists of a public key and a private key): you will need one pair for encryption and one pair for signing actions.
You can use your certificates or (preferably) get them through a certificate authority.
Next, you will need to ‘convert’ the PUBLIC keys (NOT the private key. You MUST keep the private key always private) to JWK and group them in a JWK Set. There are various tools that can be used and all major programming languages support have libraries available to do this for you.
The resulting JWK Set MUST contain (at least) 2 JWK: one whereby the “use” parameter is ”enc” (for encryption) and another with “sig” (for signature).
This JWK Set is nothing more than a plain text file (“JSON” format) and you should place that on a publicly available website under https schema (with EV/OV certificate) and share that link with us if you have no access to itsme® B2B portal yet. As these are the PUBLIC keys, there is no problem to share this information publicly: in other words, it should not be placed behind a password or login screen. We expect that your server where jwkset is hosted responds fast, e.g. faster than 1000ms.
A signed content can be serialized in two ways: the JWS compact serialization and the JWS JSON serialization. Because the OpenID Connect specification mandates to use JWS compact serialization whenever necessary, we will not explain the JWS JSON serialization signing process in this document.
Following steps will show you how to generate a JWS Compact Serialization object:
Build a JSON object including the below header elements, which express the cryptographic properties of the JWS object — this is known as the JWS Header.
alg
Required
Identifies the cryptographic algorithm used to secure the JWS. This MUST be set to "RS256"
kid
Optionnal
Hint indicating which key was used to secure the JWS. The structure of the kid value is a case-sensitive string. In case there are multiple signing keys referenced in your JWK Set document then a kid MUST be present.
The JWS Header will then be encoded using UTF-8 and base64url to produce the string below.
The concepts of JWT, JWS, JWE and JWK are part of the JSON Object Signing and Encryption (JOSE) framework that intends to provide a method to securely transfer claims between parties.
All these technologies can be used collectively to encrypt and/or sign content using a variety of algorithms. While the full set of permutations is extremely large, and might be daunting to some, it is expected that most applications will only use a small set of algorithms to meet their needs.
Definitions
The JSON Object Signing and Encryption (JOSE) framework consists of several technologies:
JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure, as the plaintext of a JSON Web Encryption (JWE) structure or enclosed in another JWE or JWS structure to create a Nested JWT, enabling nested signing and encryption to be performed. In fact a JWT does not exist itself — either it has to be a JWS and/or a JWE. It’s like an abstract class — the JWS and JWE are the concrete implementations.
JSON Web Signature (JWS) represents signed content using JSON data structures and base64url encoding as defined in the specifications.
JSON Web Encryption (JWE) specification standardizes the way to represent an encrypted content in a JSON-based data structure.
JSON Web Key (JWK) defines a consistent way to represent a cryptographic key in a JSON structure which is used to sign (JWS) and/or encrypt (JWE) a specific content. The JSON Web Key Set (JWKS) extension defines a consistent way to represent a set of cryptographic keys in a JSON structure. 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.
Your JWK Set document MUST be accessible via the URI communicated when setting up your project in the itsme® B2B portal or via email to onboarding@itsme-id.com.
Creating your JWK Set URI
The JWK is nothing more than another representation of the (public) key of a certificate keypair and the JWK Set is simply a list of one or more JWK.
So, you need to have/create your certificate key pairs (a key pair consists of a public key and a private key): you will need one pair for encryption and one pair for signing actions.
You can use your certificates or (preferably) get them through a certificate authority.
Next, you will need to ‘convert’ the PUBLIC keys (NOT the private key. You MUST keep the private key always private) to JWK and group them in a JWK Set. There are various tools that can be used and all major programming languages support have libraries available to do this for you.
The resulting JWK Set MUST contain (at least) 2 JWK: one whereby the “use” parameter is ”enc” (for encryption) and another with “sig” (for signature).
This JWK Set is nothing more than a plain text file (“JSON” format) and you should place that on a publicly available website under https schema (with EV/OV certificate) and share that link with us if you have no access to itsme® B2B portal yet. As these are the PUBLIC keys, there is no problem to share this information publicly: in other words, it should not be placed behind a password or login screen. We expect that your server where jwkset is hosted responds fast, e.g. faster than 1000ms.
A signed content can be serialized in two ways: the JWS compact serialization and the JWS JSON serialization. Because the OpenID Connect specification mandates to use JWS compact serialization whenever necessary, we will not explain the JWS JSON serialization signing process in this document.
Following steps will show you how to generate a JWS Compact Serialization object:
Build a JSON object including the below header elements, which express the cryptographic properties of the JWS object — this is known as the JWS Header.
alg
Required
Identifies the cryptographic algorithm used to secure the JWS. This MUST be set to "RS256"
kid
Optionnal
Hint indicating which key was used to secure the JWS. The structure of the kid value is a case-sensitive string. In case there are multiple signing keys referenced in your JWK Set document then a kid MUST be present.
The JWS Header will then be encoded using UTF-8 and base64url to produce the string below.
itsme® is a trusted identity provider allowing partners to use verified identities for authentication, authorization and signature on web desktop, mobile web and mobile applications.
The objective of this document is to provide all the information needed to integrate the AUTH service using the OAuth specifications.
At this moment only the Hash(es) Signing variant is available and documented. In this variant, an external Signature Creation Application (SCA) will provide the What You See Is What You Sign (WYSIWYS) experience to the User, provide the hash of the data to be signed to the itsme® service and use the returned digital signature value to format the signature in one of the AdES formats.
Particularities compared to the CSC Specification
No implementation of / no support for:
Auth/Login method
Credentials/Authorize
Credentials/ExtendTransaction
Credentials/sendOTP
Signatures/Timestamp
OAuth2/Token request
This operation supports both application/json and application/x-www-form-urlencoded
Audience
This document is intended to be read by developers of any Signature Creation Application party. Partners who wish to use the itsme sign service through an existing SCA should refer to this SCA instead.
Prerequisites
Before you can integrate your application with itsme® Sign service, you MUST set up a project in the itsme® B2B portal to obtain all the needed information.
Please be aware that we support performing up to 70 signatures within 1 itsme® action, but this is an extra option. If you want to make use of it, be sure to mention it to the Onboarding team while setting up your project.
Integrating Sign services
The itsme® Sign flow goes through the steps shown in the sequence diagram below.
1. Getting endpoint info
To simplify implementations and increase flexibility, a JSON document is available containing key-value pairs which provide details about CSC configuration, such as the different endpoints, the base URI, region and so on.
The method requires a post with a JSON body where you can provide the language of the document you want to retrieve. Supported languages are; EN, FR, NL, DE and their respective ISO language codes. If the language is not supported, English will be used.
itsme® is a trusted identity provider allowing partners to use verified identities for authentication, authorization and signature on web desktop, mobile web and mobile applications.
The objective of this document is to provide all the information needed to integrate the AUTH service using the OAuth specifications.
At this moment only the Hash(es) Signing variant is available and documented. In this variant, an external Signature Creation Application (SCA) will provide the What You See Is What You Sign (WYSIWYS) experience to the User, provide the hash of the data to be signed to the itsme® service and use the returned digital signature value to format the signature in one of the AdES formats.
Particularities compared to the CSC Specification
No implementation of / no support for:
Auth/Login method
Credentials/Authorize
Credentials/ExtendTransaction
Credentials/sendOTP
Signatures/Timestamp
OAuth2/Token request
This operation supports both application/json and application/x-www-form-urlencoded
Audience
This document is intended to be read by developers of any Signature Creation Application party. Partners who wish to use the itsme sign service through an existing SCA should refer to this SCA instead.
Prerequisites
Before you can integrate your application with itsme® Sign service, you MUST set up a project in the itsme® B2B portal to obtain all the needed information.
Please be aware that we support performing up to 70 signatures within 1 itsme® action, but this is an extra option. If you want to make use of it, be sure to mention it to the Onboarding team while setting up your project.
Integrating Sign services
The itsme® Sign flow goes through the steps shown in the sequence diagram below.
1. Getting endpoint info
To simplify implementations and increase flexibility, a JSON document is available containing key-value pairs which provide details about CSC configuration, such as the different endpoints, the base URI, region and so on.
The method requires a post with a JSON body where you can provide the language of the document you want to retrieve. Supported languages are; EN, FR, NL, DE and their respective ISO language codes. If the language is not supported, English will be used.
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 Sign service. This implementation of the Sign service is based on Oasis Digital Signature Services (DSS) protocol, using an asynchronous pattern in a pre-2.0 fashion.
At this moment only the Hash(es) Signing variant is available and documented. In this variant, an external Signature Creation Application (SCA) will provide the What You See Is What You Sign (WYSIWYS) experience to the User, provide the hash of the data to be signed to the itsme® service and use the returned digital signature value to format the signature in one of the AdES formats.
Audience
This document is intended to be read by developers of any Signature Creation Application party. Partners who wish to use the itsme sign service through an existing SCA should refer to this SCA instead.
Prerequisites
Before you can integrate your application with itsme® Sign service, you MUST set up a project in the itsme® B2B portal to obtain all the needed information.
Please be aware that we support performing up to 70 signatures within 1 itsme® action, but this is an extra option. If you want to make use of it, be sure to mention it to the Onboarding team while setting up your project.
Integrating Sign services
The itsme® Sign flow goes through the steps shown in the sequence diagram below.
The User indicates on your end he wishes to sign a document with itsme®
Your web desktop, mobile web or mobile SCA application sends a request to itsme® Integration Layer Back-End in order to create the User’s Identification session and obtain the User’s signing certificate to be include in the data to be signed.
itsme® returns the session id and the redirect URL specific to the User to your SCA Back-End.
Your SCA Front-End redirects the User to the Integration Layer Front-End of itsme®, meaning that the User will be identified in the meanwhile (in case the "userCode" is transmitted by the SCA, this step will be skipped as the user will already be identified). If the User has no signature certificate yet, the certificate creation process will be initiated automatically.
Finally, when the User is authenticated and has a signature certificate, he is redirected to the your SCA Front-End. The redirection to your SCA Front-End SHOULD be (almost) transparent to the User (with a possible displaying of a spinner) as the laps of time between step 5 and step 11 of this diagram SHOULD be extremely short.
Your SCA Back-End contacts the itsme® Integration Layer Back-End to get the signature certificate of the User.
The itsme® Integration Layer Back-End returns your SCA Back-End the signer information as well as the signature certificate of the User.
Your SCA Back-End constructs the data to be signed and the hash(es) of the signature(s) will be computed by yourself. We support up to 70 hashes in 1 flow. The value of a hash MUST be base64url encoded.
Your SCA Back-End will provide the hash(es) to the itsme® Integration Layer Back-End to request the digital signature value.
A session id and redirect URL are returned by itsme® to your SCA Back-End.
Your SCA frontend will then redirect the User to the signature webpage of itsme®, where he is guided through the itsme part of the signing flow.
The session of the User at itsme® side ends as the process is finished and the User is redirected to your SCA Front-End.
Your SCA Back-End will contact the itsme® Integration Layer Back-End to check the signature status (same endpoint as for creating the signature session).
itsme® then returns the signature completion status and the digital signature value(s).
At this stage, your SCA is able to confirm the success of the operation and display a success message.
1. Checking itsme® Sign configuration
Two JSON documents are available to ease the integration of itsme sign service:
The discovery document
The swagger of the B2B interface
Discovery document
To simplify implementations and increase flexibility, the following key-value pairs about itsme® configuration can be retrieved from a JSON document:
Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication. If you need to access the discovery document before setting up the connectivity, you can use the public version here (this one is updated manually, while the previous one is automatically generated): https://belgianmobileid.github.io/doc/public/resources/qesdiscovery.json
This section relates to the step 2 of the sequence diagram.
First, you will forge a HTTPS POST request that MUST be sent to the itsme® User Identification Endpoint, which is BASE_URL/qes-partners/1.0.0/user_identification. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication.
Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:
partnerCode
REQUIRED
This MUST be the client identifier you received when registering your application during the onboarding process. This parameter will be translated to a label describing the customer for which the User is signing the document.
userCode
OPTIONAL
The userCode is the unique identifier created by itsme for a user connecting with a Service Provider. A user has a different user code at each Service Provider. You SHOULD provide a "userCode" known by itsme if you already have authenticated the User who needs to sign the document. Providing a userCode will bypass the identification screen (user won't have to enter his phone number).
serviceCode
REQUIRED
It MUST contain the value of the serviceCode defined for your application during the onboarding process.
lang
REQUIRED
This parameters defines the recommended language to be used for GUI interaction.
redirectUrl
REQUIRED
This is the URL to which the User will be redirected to your remote SCA. This MUST exactly match the redirect URL of the specified service defined when registering your application during the [onboarding process](#prerequisites).
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 Sign service. This implementation of the Sign service is based on Oasis Digital Signature Services (DSS) protocol, using an asynchronous pattern in a pre-2.0 fashion.
At this moment only the Hash(es) Signing variant is available and documented. In this variant, an external Signature Creation Application (SCA) will provide the What You See Is What You Sign (WYSIWYS) experience to the User, provide the hash of the data to be signed to the itsme® service and use the returned digital signature value to format the signature in one of the AdES formats.
Audience
This document is intended to be read by developers of any Signature Creation Application party. Partners who wish to use the itsme sign service through an existing SCA should refer to this SCA instead.
Prerequisites
Before you can integrate your application with itsme® Sign service, you MUST set up a project in the itsme® B2B portal to obtain all the needed information.
Please be aware that we support performing up to 70 signatures within 1 itsme® action, but this is an extra option. If you want to make use of it, be sure to mention it to the Onboarding team while setting up your project.
Integrating Sign services
The itsme® Sign flow goes through the steps shown in the sequence diagram below.
The User indicates on your end he wishes to sign a document with itsme®
Your web desktop, mobile web or mobile SCA application sends a request to itsme® Integration Layer Back-End in order to create the User’s Identification session and obtain the User’s signing certificate to be include in the data to be signed.
itsme® returns the session id and the redirect URL specific to the User to your SCA Back-End.
Your SCA Front-End redirects the User to the Integration Layer Front-End of itsme®, meaning that the User will be identified in the meanwhile (in case the "userCode" is transmitted by the SCA, this step will be skipped as the user will already be identified). If the User has no signature certificate yet, the certificate creation process will be initiated automatically.
Finally, when the User is authenticated and has a signature certificate, he is redirected to the your SCA Front-End. The redirection to your SCA Front-End SHOULD be (almost) transparent to the User (with a possible displaying of a spinner) as the laps of time between step 5 and step 11 of this diagram SHOULD be extremely short.
Your SCA Back-End contacts the itsme® Integration Layer Back-End to get the signature certificate of the User.
The itsme® Integration Layer Back-End returns your SCA Back-End the signer information as well as the signature certificate of the User.
Your SCA Back-End constructs the data to be signed and the hash(es) of the signature(s) will be computed by yourself. We support up to 70 hashes in 1 flow. The value of a hash MUST be base64url encoded.
Your SCA Back-End will provide the hash(es) to the itsme® Integration Layer Back-End to request the digital signature value.
A session id and redirect URL are returned by itsme® to your SCA Back-End.
Your SCA frontend will then redirect the User to the signature webpage of itsme®, where he is guided through the itsme part of the signing flow.
The session of the User at itsme® side ends as the process is finished and the User is redirected to your SCA Front-End.
Your SCA Back-End will contact the itsme® Integration Layer Back-End to check the signature status (same endpoint as for creating the signature session).
itsme® then returns the signature completion status and the digital signature value(s).
At this stage, your SCA is able to confirm the success of the operation and display a success message.
1. Checking itsme® Sign configuration
Two JSON documents are available to ease the integration of itsme sign service:
The discovery document
The swagger of the B2B interface
Discovery document
To simplify implementations and increase flexibility, the following key-value pairs about itsme® configuration can be retrieved from a JSON document:
Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication. If you need to access the discovery document before setting up the connectivity, you can use the public version here (this one is updated manually, while the previous one is automatically generated): https://belgianmobileid.github.io/doc/public/resources/qesdiscovery.json
This section relates to the step 2 of the sequence diagram.
First, you will forge a HTTPS POST request that MUST be sent to the itsme® User Identification Endpoint, which is BASE_URL/qes-partners/1.0.0/user_identification. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication.
Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:
partnerCode
REQUIRED
This MUST be the client identifier you received when registering your application during the onboarding process. This parameter will be translated to a label describing the customer for which the User is signing the document.
userCode
OPTIONAL
The userCode is the unique identifier created by itsme for a user connecting with a Service Provider. A user has a different user code at each Service Provider. You SHOULD provide a "userCode" known by itsme if you already have authenticated the User who needs to sign the document. Providing a userCode will bypass the identification screen (user won't have to enter his phone number).
serviceCode
REQUIRED
It MUST contain the value of the serviceCode defined for your application during the onboarding process.
lang
REQUIRED
This parameters defines the recommended language to be used for GUI interaction.
redirectUrl
REQUIRED
This is the URL to which the User will be redirected to your remote SCA. This MUST exactly match the redirect URL of the specified service defined when registering your application during the [onboarding process](#prerequisites).
Example:
POST /BASE_URL/qes-partners/1.0.0/user_identification HTTP/1.1
{
"partnerCode":"myClientID",
"serviceCode":"myServiceCode",
diff --git a/TestLinks/index.html b/TestLinks/index.html
index 462846182..4f3bdc763 100644
--- a/TestLinks/index.html
+++ b/TestLinks/index.html
@@ -1 +1 @@
- App to App test links - itsme OIDC DocumentationApp to App test links | itsme OIDC Documentation
Requested data
The login links request all data available. The confirm links request a basic set of data (profile, eid, address, email and phone number).
Please note also the Confirm links are only valid for a limited amount of time. Under some occasions, the JWKSet of the test partner is re-generated, making the request object in the links below obsolete. To re-create new ones, please consult How to create A2A confirm links (hosted on BMID Confluence).
+ App to App test links - itsme OIDC DocumentationApp to App test links | itsme OIDC Documentation
Requested data
The login links request all data available. The confirm links request a basic set of data (profile, eid, address, email and phone number).
Please note also the Confirm links are only valid for a limited amount of time. Under some occasions, the JWKSet of the test partner is re-generated, making the request object in the links below obsolete. To re-create new ones, please consult How to create A2A confirm links (hosted on BMID Confluence).
pass generated callback url to onboarding@itsme-id.com
All other fields can be left on the default settings.
Save and return to Authentication => Enterprise => OpenID Connect, click “Try” under newly created connection to test the flow.
Under User Management, find test user and see raw json with requested data.
Reference
diff --git a/authentication/index.html b/authentication/index.html
index b268a2e81..4409c4a26 100644
--- a/authentication/index.html
+++ b/authentication/index.html
@@ -1,4 +1,4 @@
- Authentication API - itsme OIDC DocumentationAuthentication API | itsme OIDC Documentation
Overview
itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.
The diagram below describes the Authentication process and how your systems should integrate with itsme® :
To get to this result please make sure you
add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
to enter his phone number on the itsme® sign-in page
authorize the release of some information to your application
to provide his credentials (itsme® code, fingerprint or FaceID)
It is also in this Authorization Request that you will be able to request claims about the user and the Authentication event.
collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
Confirm the success of the operation and display a success message.
Onboarding
To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.
Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.
For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.
Guides
Generate itsme® button
First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.
Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their authentication”.
Securing the exchange of information
To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:
"Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
"Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases
Public-private key pair and JWKSet URI
This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.
You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.
Secret key method
Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.
This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.
Key rotation procedure
for public-private key pair and JWKSet URI
itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.
Rotating signing key:
Add the new key to JWK set, with a new “kid”
Start using the new key to sign JWTs
When the flow is validated with the new key, remove the old one from the JWK set
Rotating encryption key:
Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
Wait 24h (or wait for “max-age” amount of time, if specified)
Decommission the old key completely
Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:
Copy the old jwkSet on the new URL
the URL is communicated & registered by itsme®
Rotate the keys in the jwkSet on the new URL as per rotating keys info above
for secret key method
Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.
PKCE-enhanced flow
Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.
PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.
code_challenge can then be obtained via this kind of instructions:
var hash = code_verifier.createHash('sha256');
+ Authentication API - itsme OIDC DocumentationAuthentication API | itsme OIDC Documentation
Overview
itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.
The diagram below describes the Authentication process and how your systems should integrate with itsme® :
To get to this result please make sure you
add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
to enter his phone number on the itsme® sign-in page
authorize the release of some information to your application
to provide his credentials (itsme® code, fingerprint or FaceID)
It is also in this Authorization Request that you will be able to request claims about the user and the Authentication event.
collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
Confirm the success of the operation and display a success message.
Onboarding
To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.
Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.
For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.
Guides
Generate itsme® button
First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.
Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their authentication”.
Securing the exchange of information
To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:
"Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
"Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases
Public-private key pair and JWKSet URI
This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.
You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.
Secret key method
Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.
This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.
Key rotation procedure
for public-private key pair and JWKSet URI
itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.
Rotating signing key:
Add the new key to JWK set, with a new “kid”
Start using the new key to sign JWTs
When the flow is validated with the new key, remove the old one from the JWK set
Rotating encryption key:
Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
Wait 24h (or wait for “max-age” amount of time, if specified)
Decommission the old key completely
Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:
Copy the old jwkSet on the new URL
the URL is communicated & registered by itsme®
Rotate the keys in the jwkSet on the new URL as per rotating keys info above
for secret key method
Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.
PKCE-enhanced flow
Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.
PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.
code_challenge can then be obtained via this kind of instructions:
var hash = code_verifier.createHash('sha256');
var code_challenge = base64url.encode(hash);
Signing, encrypting and decoding JWTs
Libraries implementing JWT and the JOSE specs JWS, JWE, JWK, and JWA are listed here. For testing purposes only, we could advise the use of https://mkjwk.org/ for JWK generation and https://mkjose.org/ for payload check => these are 2 open-source tools which will help you visualize JWK mechanisms, client assertion construct. Please DO NOT generate production private keys on any website. Rather opt for the relevant SDK library mentioned here.
Certificates and website security
itsme® requires https connections to guarantee security. With the https protocol, a web site operator obtains a certificate by applying to a certificate authority with a certificate signing request. The certificate request is an electronic document that contains the web site name, company information and the public key. The certificate provider signs the request, thus producing a public certificate. During web browsing, this public certificate is served to any web browser that connects to the web site and proves to the web browser that the provider believes it has issued a certificate to the owner of the web site.
A certificate provider can opt to issue three types of certificates, each requiring its own degree of vetting rigor. In order of increasing rigor (and naturally, cost) they are: Domain Validation, Organization Validation and Extended Validation.
The Domain Validation certificate doesn’t provide sufficient identity guarantees to itsme. So, only the Organization Validation and Extended Validation certificates are supported. For example, using the Let’s Encrypt open certificate authority is not suffcient because it only provide standard Domain Validation certificates.
Handling responses
Whenever a partner is sending a request to the itsme OIDC endpoints he will get a response back. According to the OIDC protocol, and depending on the endpoint that was contacted, partners can get a
response where some parameters are added to the query component of the redirection URI using the application/x-www-form-urlencoded format, or
response displayed directly on our itsme® sign-in page ;
response using the application/json media type
Alongside the type of response an HTTP status code is sent that shows whether the request was successful or not. If it was not, you can tell by the code and the message in the response what went wrong, why it went wrong and whether there is something the partner can do about it.
A successful response
An HTTP status 200 OK or 302 Found is issued whenever your request was a success. You see this type of response in our examples like the one where we successfully retrieve the Token Response :
Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.
The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.
GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://idp.[e2e/prd].itsme.services/v2/authorization
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. Currently, only the page value is supported but in the future we might support additional display modes like touch.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token.
Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate claim: at least one of the 2 SHALL return a value. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch or Lux ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
This is a metadata. Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
This is a metadata. Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
This is a metadata. Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the ID document number, represented as a string. If requested, a value SHALL always be returned for this claim: BE: The BE eID number is a string with 12 digits in the form xxx-xxxxxxx-yy (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. NL: A 9-chars string with letters at positions 1 and 2, letters or digits in positions 3 to 8 and a digit at position 9. The letter ‘O’ is not used in the NL document numbers. The digit ‘0’ (zero) MAY be used. LU: Format not documented.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDIssuingCountry
OPTIONAL
This is a metadata. Returns the 3-letters iso code of the country that issued the identity document.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
This is a metadata. Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/app
OPTIONAL
Returns a JSON object with 3 members: appInstalledDate contains the date when the app was installed on the user's device, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. appName contains the name of the app and appRelease contains a string identifying the release (example: "4.9.1"). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/account
OPTIONAL
Returns a JSON object with 3 members: activationDate contains the date when the account was last activated (enrolled or unblocked), represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. activationMechanism contains a string identifying the way this account was created. Possible values are "CARD_READER" (enrollment via a physical reading of the ID document chip), "CONTACT_LESS" (enrollment via a NFC reading of the ID document) or "ID_PROVIDER" (enrollment via a trusted partner, i.e. a bank). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/transaction_ip
OPTIONAL
Returns the IP address of the smartphone approving the transaction. This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
request_uri
OPTIONAL
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MUST contain the TCP port number 443. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
OPTIONAL
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.
The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.
GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://idp.[e2e/prd].itsme.services/v2/authorization
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. Currently, only the page value is supported but in the future we might support additional display modes like touch.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token.
Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate claim: at least one of the 2 SHALL return a value. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch or Lux ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
This is a metadata. Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
This is a metadata. Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
This is a metadata. Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the ID document number, represented as a string. If requested, a value SHALL always be returned for this claim: BE: The BE eID number is a string with 12 digits in the form xxx-xxxxxxx-yy (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. NL: A 9-chars string with letters at positions 1 and 2, letters or digits in positions 3 to 8 and a digit at position 9. The letter ‘O’ is not used in the NL document numbers. The digit ‘0’ (zero) MAY be used. LU: Format not documented.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDIssuingCountry
OPTIONAL
This is a metadata. Returns the 3-letters iso code of the country that issued the identity document.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
This is a metadata. Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/app
OPTIONAL
Returns a JSON object with 3 members: appInstalledDate contains the date when the app was installed on the user's device, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. appName contains the name of the app and appRelease contains a string identifying the release (example: "4.9.1"). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/account
OPTIONAL
Returns a JSON object with 3 members: activationDate contains the date when the account was last activated (enrolled or unblocked), represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. activationMechanism contains a string identifying the way this account was created. Possible values are "CARD_READER" (enrollment via a physical reading of the ID document chip), "CONTACT_LESS" (enrollment via a NFC reading of the ID document) or "ID_PROVIDER" (enrollment via a trusted partner, i.e. a bank). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/transaction_ip
OPTIONAL
Returns the IP address of the smartphone approving the transaction. This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
request_uri
OPTIONAL
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MUST contain the TCP port number 443. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
OPTIONAL
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
POST https://idp.[e2e/prd].itsme.services/v2/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
client_assertion_type
REQUIRED
Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
REQUIRED
Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The JWT contains the following claims.
iss
REQUIRED
The issuer of the token. This value MUST be the same as the client_id.
sub
REQUIRED
The subject of the token. This value MUST be the same as the client_id.
aud
REQUIRED
The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token.
jti
REQUIRED
An unique identifier for the token, containing maximum 255 characters.
exp
REQUIRED
The expiration time of the token in seconds since January 1, 1970 UTC.
iat
OPTIONAL
The time at which the JWT was issued.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
client_secret
REQUIRED
Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://idp.[e2e/prd].itsme.services/v2/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
client_assertion_type
REQUIRED
Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
REQUIRED
Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The JWT contains the following claims.
iss
REQUIRED
The issuer of the token. This value MUST be the same as the client_id.
sub
REQUIRED
The subject of the token. This value MUST be the same as the client_id.
aud
REQUIRED
The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token.
jti
REQUIRED
An unique identifier for the token, containing maximum 255 characters.
exp
REQUIRED
The expiration time of the token in seconds since January 1, 1970 UTC.
iat
OPTIONAL
The time at which the JWT was issued.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
client_secret
REQUIRED
Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://idp.[e2e/prd].itsme.services/v2/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://idp.[e2e/prd].itsme.services/v2/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke
The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.
Parameters
token
REQUIRED
The access_token previously obtained that you want to revoke.
token_type_hint
OPTIONAL
A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.
Response
200
itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke
The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.
Parameters
token
REQUIRED
The access_token previously obtained that you want to revoke.
token_type_hint
OPTIONAL
A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.
Response
200
itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
Whether your set-up is via user flow (normally, via graphical user-interface (GUI) on Azure portal) or Identity Experience Framework (IEF), custom policies, configured via .xml files, will depend what ID data you wish (and entitled by commercial & legal agreements) to receive.
As of 2023, Azure B2C technical limitation is no possibility to process JSON objects, only strings. Please, cosult to see what claims returned by itsme® are strings or JSON object data type. User flow is limited to sub, names & email. While IEF will allow you to process the rest of ID Data listed above in data type string.
User Flows
User flows is a portal (GUI) configurable flow, which is based on built-in user attributes (values collected on sign up) and application claims, which are values about the user, returned to the application in the token. One can create custom attributes, but Azure B2C does not process any claims from itsme®, except the ones mapped during general idp setup (idp claims mapping), i.e. sub, given_name, family_name, email. Only those were returned consistently during testing of 2023.
End-user will see in the app request to approve all data which is mentioned on the scope, e.g. if full scope defined => all data will be displayed to approve, but Azure B2C will process and return only mapped claims, i.e. sub, given_name, family_name, emails (returned as string collection).
Identity Experience Framework (IEF) or custom policy
IEF is advanced method to configure Azure B2C via .xml files. Due to Azure B2C limitations, JSON Objects returned by itsme® can not be processed or transformed by Azure B2C, thus one could ask & receive data which is returned as strings only.
IEF configuration to retrieve custom OIDC claims (string or boolean data type)
Microsoft has elaborate documentation custom policy definition and how to work with . Below we attempt to provide guidance from partner perspective to smooth the configuration flow. We advise however always fall back to Azure B2C official documentation.
Prerequisites
An Azure B2C Tenant
Your itsme® provided ClientID aka PartnerCode
Your itsme® provided ServiceCode
Your client secret for your itsme® account
Getting started with Custom Policies
Add Signing and Encryption keys
Open the B2C tenant and, under Policies, select Identity Experience Framework.
Create the signing key
Select Policy Keys and then select Add.
For Options, choose Generate.
In Name, enter TokenSigningKeyContainer. The prefix B2C_1A_ is added automatically.
For Key type, select RSA.
For Key usage, select Signature.
Select Create.
Create the encryption key
Select Policy Keys and then select Add.
For Options, choose Generate.
In Name, enter TokenEncryptionKeyContainer. The prefix B2C_1A_ is added automatically.
Open the B2C tenant and select under Manage App registrations.
Select App registrations, and then select New registration.
For Name, enter IdentityExperienceFramework.
Under Supported account types, select Accounts in this organizational directory only.
Under Redirect URI, select Web, and then enter https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com, where your-tenant-name is your Azure AD B2C tenant domain name.
Under Permissions, select the Grant admin consent to openid and offline_access permissions check box.
Select Register.
Record the Application (client) ID for use in a later step.
Next, expose the API by adding a scope:
Under Manage, select Expose an API.
Select Add a scope, then select Save and continue to accept the default application ID URI.
Enter the following values to create a scope that allows custom policy execution in your Azure AD B2C tenant:
Admin consent description: Allow the application to access IdentityExperienceFramework on behalf of the signed-in user.
Select Add scope
Register the ProxyIdentityExperienceFramework application
(cf. )
Open the B2C tenant and select under Manage App registrations.
Select App registrations (Preview), and then select New registration.
For Name, enter ProxyIdentityExperienceFramework.
Under Supported account types, select Accounts in this organizational directory only.
Under Redirect URI, use the drop-down to select Public client/native (mobile & desktop).
For Redirect URI, enter myapp://auth.
Under Permissions, select the Grant admin consent to openid and offline_access permissions check box.
Select Register.
Record the Application (client) ID for use in a later step.
Next, specify that the application should be treated as a public client:
Under Manage, select Authentication.
Select Try out the new experience (if shown).
Under Advanced settings, enable Treat application as a public client (select Yes). Ensure that ”allowPublicClient”: true is set in the application manifest.
Select Save.
Now, grant permissions to the API scope you exposed earlier in the IdentityExperienceFramework registration:
Under Manage, select API permissions.
Under Configured permissions, select Add a permission.
Select the My APIs tab, then select the IdentityExperienceFramework application.
Under Permission, select the user_impersonation scope that you defined earlier.
Select Add permissions. As directed, wait a few minutes before proceeding to the next step.
Select Grant admin consent for (your tenant name).
Select your currently signed-in administrator account, or sign in with an account in your Azure AD B2C tenant that’s been assigned at least the Cloud application administrator role.
Select Accept.
Select Refresh, and then verify that “Granted for …” appears under Status for the scopes - offline_access, openid and user_impersonation. It might take a few minutes for the permissions to propagate.
App Registration
Open the B2C tenant and select under Manage select App Registrations
New registration
Support account type: Account in this organizational directory only
Redirect URL: the redirect URL to your app.
For testing purposes, you can use https://jwt.ms
click on Register
For testing purposes, go to Authentication and select in the section implicit grant “Access Tokens” and “ID Tokens”.
Client Secret Registration
Open the B2C tenant and select under Policies Identity Experience Framework.
Edit the files from the “SocialAndLocalAccounts” folder in the downloaded starter pack
In all XML files in the starter pack, replace “yourtenant” with the name of your tenant
In TrustFrameworkExtensions.xml, fill in the AppID of the two Identity Experience Framework applications
replace “ProxyIdentityExperienceFrameworkAppId”
replace “IdentityExperienceFrameworkAppId”
remove the “” with the DisplayName ‘Facebook’
<Metadata>
<Item Key="client_id">ProxyIdentityExperienceFrameworkAppID</Item>
diff --git a/confirmation/index.html b/confirmation/index.html
index 33f26d291..c37122344 100644
--- a/confirmation/index.html
+++ b/confirmation/index.html
@@ -1,4 +1,4 @@
- Confirmation API - itsme OIDC DocumentationConfirmation API | itsme OIDC Documentation
Overview
itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.
The diagram below describes the Confirmation process and how your systems should integrate with itsme® :
To get to this result please make sure you
add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
to enter his phone number on the itsme® sign-in page
authorize the release of some information to your application
to provide his credentials (itsme® code, fingerprint or FaceID)
It is also in this Authorization Request that you will be able to request claims about the user and the Confirmation event.
collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
Confirm the success of the operation and display a success message.
Onboarding
To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.
Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.
For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.
Guides
Generate itsme® button
First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.
Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their authentication.
Securing the exchange of information
To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:
"Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
"Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases
Public-private key pair and JWKSet URI
This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.
You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.
Secret key method
Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.
This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.
Key rotation procedure
for public-private key pair and JWKSet URI
itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.
Rotating signing key:
Add the new key to JWK set, with a new “kid”
Start using the new key to sign JWTs
When the flow is validated with the new key, remove the old one from the JWK set
Rotating encryption key:
Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
Wait 24h (or wait for “max-age” amount of time, if specified)
Decommission the old key completely
Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:
Copy the old jwkSet on the new URL
the URL is communicated & registered by itsme®
Rotate the keys in the jwkSet on the new URL as per rotating keys info above
for secret key method
Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.
PKCE-enhanced flow
Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.
PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.
code_challenge can then be obtained via this kind of instructions:
var hash = code_verifier.createHash('sha256');
+ Confirmation API - itsme OIDC DocumentationConfirmation API | itsme OIDC Documentation
Overview
itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.
The diagram below describes the Confirmation process and how your systems should integrate with itsme® :
To get to this result please make sure you
add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
to enter his phone number on the itsme® sign-in page
authorize the release of some information to your application
to provide his credentials (itsme® code, fingerprint or FaceID)
It is also in this Authorization Request that you will be able to request claims about the user and the Confirmation event.
collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
Confirm the success of the operation and display a success message.
Onboarding
To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.
Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.
For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.
Guides
Generate itsme® button
First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.
Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their authentication.
Securing the exchange of information
To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:
"Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
"Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases
Public-private key pair and JWKSet URI
This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.
You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.
Secret key method
Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.
This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.
Key rotation procedure
for public-private key pair and JWKSet URI
itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.
Rotating signing key:
Add the new key to JWK set, with a new “kid”
Start using the new key to sign JWTs
When the flow is validated with the new key, remove the old one from the JWK set
Rotating encryption key:
Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
Wait 24h (or wait for “max-age” amount of time, if specified)
Decommission the old key completely
Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:
Copy the old jwkSet on the new URL
the URL is communicated & registered by itsme®
Rotate the keys in the jwkSet on the new URL as per rotating keys info above
for secret key method
Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.
PKCE-enhanced flow
Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.
PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.
code_challenge can then be obtained via this kind of instructions:
var hash = code_verifier.createHash('sha256');
var code_challenge = base64url.encode(hash);
Signing, encrypting and decoding JWTs
Libraries implementing JWT and the JOSE specs JWS, JWE, JWK, and JWA are listed here. For testing purposes only, we could advise the use of https://mkjwk.org/ for JWK generation and https://mkjose.org/ for payload check => these are 2 open-source tools which will help you visualize JWK mechanisms, client assertion construct. Please DO NOT generate production private keys on any website. Rather opt for the relevant SDK library mentioned here.
Certificates and website security
itsme® requires https connections to guarantee security. With the https protocol, a web site operator obtains a certificate by applying to a certificate authority with a certificate signing request. The certificate request is an electronic document that contains the web site name, company information and the public key. The certificate provider signs the request, thus producing a public certificate. During web browsing, this public certificate is served to any web browser that connects to the web site and proves to the web browser that the provider believes it has issued a certificate to the owner of the web site.
A certificate provider can opt to issue three types of certificates, each requiring its own degree of vetting rigor. In order of increasing rigor (and naturally, cost) they are: Domain Validation, Organization Validation and Extended Validation.
The Domain Validation certificate doesn’t provide sufficient identity guarantees to itsme. So, only the Organization Validation and Extended Validation certificates are supported. For example, using the Let’s Encrypt open certificate authority is not suffcient because it only provide standard Domain Validation certificates.
Handling responses
Whenever a partner is sending a request to the itsme OIDC endpoints he will get a response back. According to the OIDC protocol, and depending on the endpoint that was contacted, partners can get a
response where some parameters are added to the query component of the redirection URI using the application/x-www-form-urlencoded format, or
response displayed directly on our itsme® sign-in page ;
response using the application/json media type
Alongside the type of response an HTTP status code is sent that shows whether the request was successful or not. If it was not, you can tell by the code and the message in the response what went wrong, why it went wrong and whether there is something the partner can do about it.
A successful response
An HTTP status 200 OK or 302 Found is issued whenever your request was a success. You see this type of response in our examples like the one where we successfully retrieve the Token Response :
Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.
The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.
GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://idp.[e2e/prd].itsme.services/v2/authorization
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. Currently, only the page value is supported but in the future we might support additional display modes like touch.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token. Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned if the user doesn't gave us an email address.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the Dutch ID card/passport number, represented as a string composed of letters at positions 1 and 2 ; letters or digits from positions 3-8: ; and a digit at position 9. The letter ‘O’ is not used in the document numbers. The digit ‘0’ (zero) MAY be used.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
sub
OPTIONAL
Allows the user to bypass the itsme® identification page if he is already logged into your application, by using the user's unique identifier key as value (aka. the user's sub value returned in the ID Token response)
request_uri
REQUIRED if no "request"
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MUST contain the TCP port number 443. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
REQUIRED if no "request_uri"
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. If set to touch, it SHOULD displays the itsme® sign-in page with a device that leverages a touch interface. If set to page, the itsme® sign-in UI SHOULD be consistent with a full page view of the User-Agent. If the display parameter is not specified, this is the default display mode.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims together with indication whether the claim is voluntary (returned if available) or essential (flow will stop if unavailable) - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token. Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate claim: at least one of the 2 SHALL return a value. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned if the user doesn't gave us an email address.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the Dutch or Luxembourgish ID card/passport number, represented as a string. (NL doc SN is composed of letters at positions 1 and 2 ; letters or digits from positions 3-8: ; and a digit at position 9. The letter ‘O’ is not used in the NL document numbers. The digit ‘0’ (zero) MAY be used.)
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDIssuingCountry
OPTIONAL
Returns the 3-letters iso code of the country that issued the identity document.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
sub
OPTIONAL
Allows the user to bypass the itsme® identification page if already logged into your application, by using the user's unique identifier key as value (aka. the user's sub value returned in a previous Token response). Please, use the following syntax: "sub":{"value":"YOUR_SUB"}
</tr>
request_uri
REQUIRED if no "request"
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MAY contain any TCP port number. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
REQUIRED if no "request_uri"
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.
The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.
GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://idp.[e2e/prd].itsme.services/v2/authorization
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. Currently, only the page value is supported but in the future we might support additional display modes like touch.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token. Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned if the user doesn't gave us an email address.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the Dutch ID card/passport number, represented as a string composed of letters at positions 1 and 2 ; letters or digits from positions 3-8: ; and a digit at position 9. The letter ‘O’ is not used in the document numbers. The digit ‘0’ (zero) MAY be used.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
sub
OPTIONAL
Allows the user to bypass the itsme® identification page if he is already logged into your application, by using the user's unique identifier key as value (aka. the user's sub value returned in the ID Token response)
request_uri
REQUIRED if no "request"
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MUST contain the TCP port number 443. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
REQUIRED if no "request_uri"
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. If set to touch, it SHOULD displays the itsme® sign-in page with a device that leverages a touch interface. If set to page, the itsme® sign-in UI SHOULD be consistent with a full page view of the User-Agent. If the display parameter is not specified, this is the default display mode.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims together with indication whether the claim is voluntary (returned if available) or essential (flow will stop if unavailable) - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token. Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: If requested, a value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate claim: at least one of the 2 SHALL return a value. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned if the user doesn't gave us an email address.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the Dutch or Luxembourgish ID card/passport number, represented as a string. (NL doc SN is composed of letters at positions 1 and 2 ; letters or digits from positions 3-8: ; and a digit at position 9. The letter ‘O’ is not used in the NL document numbers. The digit ‘0’ (zero) MAY be used.)
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDIssuingCountry
OPTIONAL
Returns the 3-letters iso code of the country that issued the identity document.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
sub
OPTIONAL
Allows the user to bypass the itsme® identification page if already logged into your application, by using the user's unique identifier key as value (aka. the user's sub value returned in a previous Token response). Please, use the following syntax: "sub":{"value":"YOUR_SUB"}
</tr>
request_uri
REQUIRED if no "request"
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MAY contain any TCP port number. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
REQUIRED if no "request_uri"
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
POST https://idp.[e2e/prd].itsme.services/v2/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
client_assertion_type
REQUIRED
Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
REQUIRED
Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The JWT contains the following claims.
iss
REQUIRED
The issuer of the token. This value MUST be the same as the client_id.
sub
REQUIRED
The subject of the token. This value MUST be the same as the client_id.
aud
REQUIRED
The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token.
jti
REQUIRED
An unique identifier for the token, containing maximum 255 characters.
exp
REQUIRED
The expiration time of the token in seconds since January 1, 1970 UTC.
iat
OPTIONAL
The time at which the JWT was issued.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
client_secret
REQUIRED
Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://idp.[e2e/prd].itsme.services/v2/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
client_assertion_type
REQUIRED
Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
REQUIRED
Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The JWT contains the following claims.
iss
REQUIRED
The issuer of the token. This value MUST be the same as the client_id.
sub
REQUIRED
The subject of the token. This value MUST be the same as the client_id.
aud
REQUIRED
The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token.
jti
REQUIRED
An unique identifier for the token, containing maximum 255 characters.
exp
REQUIRED
The expiration time of the token in seconds since January 1, 1970 UTC.
iat
OPTIONAL
The time at which the JWT was issued.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
client_secret
REQUIRED
Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://idp.[e2e/prd].itsme.services/v2/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://idp.[e2e/prd].itsme.services/v2/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke
The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.
Parameters
token
REQUIRED
The access_token previously obtained that you want to revoke.
token_type_hint
OPTIONAL
A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.
Response
200
itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke
The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.
Parameters
token
REQUIRED
The access_token previously obtained that you want to revoke.
token_type_hint
OPTIONAL
A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.
Response
200
itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
POST/connect/revokeHTTP/1.1Host:server.example.comContent-Type:application/x-www-form-urlencodedAuthorization:Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
diff --git a/feed.xml b/feed.xml
index 098797b00..8f53b7143 100644
--- a/feed.xml
+++ b/feed.xml
@@ -1,4 +1,4 @@
-Jekyll2024-01-13T02:14:12+00:00https://belgianmobileid.github.io/doc/feed.xmlitsme OIDC DocumentationThis website documents how to use the itsme OpenID Connect interface.Welcome to Jekyll!2020-09-24T10:11:55+00:002020-09-24T10:11:55+00:00https://belgianmobileid.github.io/doc/jekyll/update/2020/09/24/welcome-to-jekyll<p>You’ll find this post in your <code class="language-plaintext highlighter-rouge">_posts</code> directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run <code class="language-plaintext highlighter-rouge">jekyll serve</code>, which launches a web server and auto-regenerates your site when a file is updated.</p>
+Jekyll2024-01-14T02:15:56+00:00https://belgianmobileid.github.io/doc/feed.xmlitsme OIDC DocumentationThis website documents how to use the itsme OpenID Connect interface.Welcome to Jekyll!2020-09-24T10:11:55+00:002020-09-24T10:11:55+00:00https://belgianmobileid.github.io/doc/jekyll/update/2020/09/24/welcome-to-jekyll<p>You’ll find this post in your <code class="language-plaintext highlighter-rouge">_posts</code> directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run <code class="language-plaintext highlighter-rouge">jekyll serve</code>, which launches a web server and auto-regenerates your site when a file is updated.</p>
<p>Jekyll requires blog post files to be named according to the following format:</p>
diff --git a/forgerock/index.html b/forgerock/index.html
index 5230f8249..0aae6ef40 100644
--- a/forgerock/index.html
+++ b/forgerock/index.html
@@ -1 +1 @@
- Forgerock | Ping Identity - itsme OIDC DocumentationForgerock Ping Identity | itsme OIDC Documentation
Prerequisites
This integration relies on the ForgeRock Social Provider Handler Node which is available in ForgeRock Platform 7 and assumes integration between AM and IDM has been configured. Please, refer to .
A Forgerock account/subscription. If you don’t have a subscription, please contact Forgerock at https://www.forgerock.com/contact
A Forgerock tenant that is linked to your forgerock subscription.
Your Client ID, also known as Partner code, provided by itsme®.
Your Service code provided by itsme®.
Your public jwkset_uri (please, provide it to onboarding@itsme-id.com) or the secret provided by itsme® (in case of client secret)
Your redirect_uri you will be redirecting the user to (please, provide it to onboarding@itsme-id.com), e.g. https://openam-itsme-demo.forgeblocks.com/am
Scenario
On your website or application, include the Log in with itsme® button by adapting in the Forgerock user flow. The interaction flow starts when the user clicks on this button.
Forgerock starts the OpenID connect flow by sending an Authorize request to the itsme® API. is pre-configured within Forgerock ecosystem & contains information about the endpoints.
itsme® environment redirects the user to the itsme® identify yourself page, allowing the user to fill in their phone number.
itsme® receives the phone number from the user and validates it.
If the phone number belongs to an active itsme® user, an Action is created for the itsme® app.
The user opens the itsme® app, checks the request, and confirms the action.
The app informs the itsme® environment the action has been confirmed.
The itsme® environment returns the authorization code to Forgerock.
Using the authorization code, Forgerock makes a token request.
The itsme® environment checks the token request, and if still valid, returns the OAuth access token and the ID token containing the requested user information.
Finally, the user is redirected to the redirect_uri as an authenticated user.
Configuration between Forgerock and itsme®
Step 1: Setup itsme® to ForgeRock AM
Log in to the forgerock Identity cloud
Go to “native consoles” > “access management”
Go to “services” > “social identity provider service” > “secondary configuration”
Select itsme®
Populate the details with the parameters you got from itsme®: (NOTE: Forgerock automatically populates these fields with production endpoints. Initially, these need to be changed to E2E endpoints in order to function.)
Parameter
Value
ClientID
Your Client ID, also known as Partner code
Client Secret
Your client_secret (leave empty in case of public-private key pair, i.e. jwkset_uri)
Authentication Endpoint URL
“https://idp.e2e.itsme.services/v2/authorization”
Token Endpoint
“https://idp.e2e.itsme.services/v2/token”
User Profile Service URL
“https://idp.e2e.itsme.services/v2/userinfo”
RedirectURI
your redirectURI NOTE: for itsme® to function in production, the Forgerock tenant needs to be installed with a custom domain (https://backstage.forgerock.com/docs/idcloud/latest/realms/custom-domains.html#set_up_a_custom_domain_in_identity_cloud) and an OV/EV certificate. Please contact Forgerock support to make sure this is installed on your tenant.
All other fields can be left on the default settings from Forgerock.
Select ‘itsme® profile normalization’ in the transform script drop-down menu.
Step 2: Define your itsme® journey
Go to Journeys and select itsme® to build your workflow. There is already a custom flow ready for you to use with itsme®. By default, it includes a username/password flow with itsme® added as a secondary option, but this can be adapted as you wish.
This integration relies on the ForgeRock Social Provider Handler Node which is available in ForgeRock Platform 7 and assumes integration between AM and IDM has been configured. Please, refer to .
A Forgerock account/subscription. If you don’t have a subscription, please contact Forgerock at https://www.forgerock.com/contact
A Forgerock tenant that is linked to your forgerock subscription.
Your Client ID, also known as Partner code, provided by itsme®.
Your Service code provided by itsme®.
Your public jwkset_uri (please, provide it to onboarding@itsme-id.com) or the secret provided by itsme® (in case of client secret)
Your redirect_uri you will be redirecting the user to (please, provide it to onboarding@itsme-id.com), e.g. https://openam-itsme-demo.forgeblocks.com/am
Scenario
On your website or application, include the Log in with itsme® button by adapting in the Forgerock user flow. The interaction flow starts when the user clicks on this button.
Forgerock starts the OpenID connect flow by sending an Authorize request to the itsme® API. is pre-configured within Forgerock ecosystem & contains information about the endpoints.
itsme® environment redirects the user to the itsme® identify yourself page, allowing the user to fill in their phone number.
itsme® receives the phone number from the user and validates it.
If the phone number belongs to an active itsme® user, an Action is created for the itsme® app.
The user opens the itsme® app, checks the request, and confirms the action.
The app informs the itsme® environment the action has been confirmed.
The itsme® environment returns the authorization code to Forgerock.
Using the authorization code, Forgerock makes a token request.
The itsme® environment checks the token request, and if still valid, returns the OAuth access token and the ID token containing the requested user information.
Finally, the user is redirected to the redirect_uri as an authenticated user.
Configuration between Forgerock and itsme®
Step 1: Setup itsme® to ForgeRock AM
Log in to the forgerock Identity cloud
Go to “native consoles” > “access management”
Go to “services” > “social identity provider service” > “secondary configuration”
Select itsme®
Populate the details with the parameters you got from itsme®: (NOTE: Forgerock automatically populates these fields with production endpoints. Initially, these need to be changed to E2E endpoints in order to function.)
Parameter
Value
ClientID
Your Client ID, also known as Partner code
Client Secret
Your client_secret (leave empty in case of public-private key pair, i.e. jwkset_uri)
Authentication Endpoint URL
“https://idp.e2e.itsme.services/v2/authorization”
Token Endpoint
“https://idp.e2e.itsme.services/v2/token”
User Profile Service URL
“https://idp.e2e.itsme.services/v2/userinfo”
RedirectURI
your redirectURI NOTE: for itsme® to function in production, the Forgerock tenant needs to be installed with a custom domain (https://backstage.forgerock.com/docs/idcloud/latest/realms/custom-domains.html#set_up_a_custom_domain_in_identity_cloud) and an OV/EV certificate. Please contact Forgerock support to make sure this is installed on your tenant.
All other fields can be left on the default settings from Forgerock.
Select ‘itsme® profile normalization’ in the transform script drop-down menu.
Step 2: Define your itsme® journey
Go to Journeys and select itsme® to build your workflow. There is already a custom flow ready for you to use with itsme®. By default, it includes a username/password flow with itsme® added as a secondary option, but this can be adapted as you wish.
diff --git a/identification/index.html b/identification/index.html
index 7f577ad7b..37a4e575e 100644
--- a/identification/index.html
+++ b/identification/index.html
@@ -1,4 +1,4 @@
- Identification API - itsme OIDC DocumentationIdentification API | itsme OIDC Documentation
Overview
itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.
The diagram below describes the Identification process and how your systems should integrate with itsme® :
To get to this result please make sure you
add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
to enter his phone number on the itsme® sign-in page
authorize the release of some information to your application
to provide his credentials (itsme® code, fingerprint or FaceID)
It is also in this Authorization Request that you will be able to request claims about the user and the Identification event.
collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
Confirm the success of the operation and display a success message.
Onboarding
To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.
Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.
For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme®. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.
Guides
Generate itsme® button
First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.
Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their identification.
Securing the exchange of information
To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:
"Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
"Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases
Public-private key pair and JWKSet URI
This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.
You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.
Secret key method
Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.
This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.
Key rotation procedure
for public-private key pair and JWKSet URI
itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.
Rotating signing key:
Add the new key to JWK set, with a new “kid”
Start using the new key to sign JWTs
When the flow is validated with the new key, remove the old one from the JWK set
Rotating encryption key:
Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
Wait 24h (or wait for “max-age” amount of time, if specified)
Decommission the old key completely
Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:
Copy the old jwkSet on the new URL
the URL is communicated & registered by itsme®
Rotate the keys in the jwkSet on the new URL as per rotating keys info above
for secret key method
Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.
PKCE-enhanced flow
Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.
PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.
code_challenge can then be obtained via this kind of instructions:
var hash = code_verifier.createHash('sha256');
+ Identification API - itsme OIDC DocumentationIdentification API | itsme OIDC Documentation
Overview
itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.
The diagram below describes the Identification process and how your systems should integrate with itsme® :
To get to this result please make sure you
add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
to enter his phone number on the itsme® sign-in page
authorize the release of some information to your application
to provide his credentials (itsme® code, fingerprint or FaceID)
It is also in this Authorization Request that you will be able to request claims about the user and the Identification event.
collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
Confirm the success of the operation and display a success message.
Onboarding
To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.
Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.
For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme®. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.
Guides
Generate itsme® button
First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.
Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their identification.
Securing the exchange of information
To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:
"Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
"Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases
Public-private key pair and JWKSet URI
This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.
You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.
Secret key method
Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.
This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.
Key rotation procedure
for public-private key pair and JWKSet URI
itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.
Rotating signing key:
Add the new key to JWK set, with a new “kid”
Start using the new key to sign JWTs
When the flow is validated with the new key, remove the old one from the JWK set
Rotating encryption key:
Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
Wait 24h (or wait for “max-age” amount of time, if specified)
Decommission the old key completely
Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:
Copy the old jwkSet on the new URL
the URL is communicated & registered by itsme®
Rotate the keys in the jwkSet on the new URL as per rotating keys info above
for secret key method
Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.
PKCE-enhanced flow
Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.
PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.
code_challenge can then be obtained via this kind of instructions:
var hash = code_verifier.createHash('sha256');
var code_challenge = base64url.encode(hash);
Signing, encrypting and decoding JWTs
Libraries implementing JWT and the JOSE specs JWS, JWE, JWK, and JWA are listed here. For testing purposes only, we could advise the use of https://mkjwk.org/ for JWK generation and https://mkjose.org/ for payload check => these are 2 open-source tools which will help you visualize JWK mechanisms, client assertion construct. Please DO NOT generate production private keys on any website. Rather opt for the relevant SDK library mentioned here.
Certificates and website security
itsme® requires https connections to guarantee security. With the https protocol, a web site operator obtains a certificate by applying to a certificate authority with a certificate signing request. The certificate request is an electronic document that contains the web site name, company information and the public key. The certificate provider signs the request, thus producing a public certificate. During web browsing, this public certificate is served to any web browser that connects to the web site and proves to the web browser that the provider believes it has issued a certificate to the owner of the web site.
A certificate provider can opt to issue three types of certificates, each requiring its own degree of vetting rigor. In order of increasing rigor (and naturally, cost) they are: Domain Validation, Organization Validation and Extended Validation.
The Domain Validation certificate doesn’t provide sufficient identity guarantees to itsme. So, only the Organization Validation and Extended Validation certificates are supported. For example, using the Let’s Encrypt open certificate authority is not suffcient because it only provide standard Domain Validation certificates.
Handling responses
Whenever a partner is sending a request to the itsme OIDC endpoints he will get a response back. According to the OIDC protocol, and depending on the endpoint that was contacted, partners can get a
response where some parameters are added to the query component of the redirection URI using the application/x-www-form-urlencoded format, or
response displayed directly on our itsme® sign-in page ;
response using the application/json media type
Alongside the type of response an HTTP status code is sent that shows whether the request was successful or not. If it was not, you can tell by the code and the message in the response what went wrong, why it went wrong and whether there is something the partner can do about it.
A successful response
An HTTP status 200 OK or 302 Found is issued whenever your request was a success. You see this type of response in our examples like the one where we successfully retrieve the Token Response :
Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.
The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.
GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://idp.[e2e/prd].itsme.services/v2/authorization
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. Currently, only the page value is supported but in the future we might support additional display modes like touch.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token.
Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate claim: at least one of the 2 SHALL return a value. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch or Lux ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
This is a metadata. Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
This is a metadata. Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
This is a metadata. Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the ID document number, represented as a string. If requested, a value SHALL always be returned for this claim: BE: The BE eID number is a string with 12 digits in the form xxx-xxxxxxx-yy (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. NL: A 9-chars string with letters at positions 1 and 2, letters or digits in positions 3 to 8 and a digit at position 9. The letter ‘O’ is not used in the NL document numbers. The digit ‘0’ (zero) MAY be used. LU: Format not documented.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDIssuingCountry
OPTIONAL
This is a metadata. Returns the 3-letters iso code of the country that issued the identity document.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
This is a metadata. Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/app
OPTIONAL
Returns a JSON object with 3 members: appInstalledDate contains the date when the app was installed on the user's device, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. appName contains the name of the app and appRelease contains a string identifying the release (example: "4.9.1"). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/account
OPTIONAL
Returns a JSON object with 3 members: activationDate contains the date when the account was last activated (enrolled or unblocked), represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. activationMechanism contains a string identifying the way this account was created. Possible values are "CARD_READER" (enrollment via a physical reading of the ID document chip), "CONTACT_LESS" (enrollment via a NFC reading of the ID document) or "ID_PROVIDER" (enrollment via a trusted partner, i.e. a bank). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/transaction_ip
OPTIONAL
Returns the IP address of the smartphone approving the transaction. This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
request_uri
OPTIONAL
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MUST contain the TCP port number 443. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
OPTIONAL
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.
The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.
GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration
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
Authorization, Token and userInfo EndpointsSupported claims...
GET https://idp.[e2e/prd].itsme.services/v2/authorization
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize
Parameters
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
response_type
REQUIRED
This defines the processing flow to be used when forming the response. Because itsme® supports the Authorization Code Flow, this value MUST be code.
scope
REQUIRED
It allows your application to express the desired scope of the access request. Each scope returns a set of user attributes. The scopes an application should request depend on which user attributes your application needs. Once the user authorizes the requested scopes, his details are returned in an ID Token and are also available through the UserInfo Endpoint.
All scope values must be space-separated.
The basic (and required) scopes are openid and service. Beyond that, your application can ask for additional standard scopes values which map to sets of related claims are: profileemailaddressphoneeid
service
REQUIRED
It indicates the itsme® service your application intends to use, e.g. service:TEST_code by replacing "TEST_code" with the service code generated during registration.
openid
REQUIRED
It indicates that your application intends to use the OpenID Connect protocol to verify a user's identity by returning a sub claim which represents a unique identifier for the authenticated user.
profile
OPTIONAL
Returns claims that represent basic profile information, specifically family_name, given_name, name, gender, locale, picture and birthdate.
If requested, a value SHALL always be returned for the above claims except for the given_name claim which MAY NOT be returned if the user doesn't have any first name(s).
email
OPTIONAL
Returns the email claim, which contains the user's email address, and email_verified, which is a boolean indicating whether the email address was verified by the user.
If requested, a value SHALL always be returned for the email_verified claim only if email claim is filled with a value, whereas the email claim SHALL always be returned only if the user gave us an email address.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members formattedstreet_addresspostal_codelocality
If requested, a value SHALL always be returned for users with a Belgian ID document, and SHALL NOT be returned for users with a Dutch ID documents.
phone
OPTIONAL
Returns the phone_number claim, which contains the user's phone number, and phone_number_verified, which is a boolean indicating whether the phone number was verified by the user.
If requested, a value SHALL always be returned for the above claims.
eid
OPTIONAL
Returns the http://itsme.services/v2/claim/BENationalNumber claim, which contains the unique identification number of natural persons who are registered in Belgium, and http://itsme.services/v2/claim/BEeidSn, which is a string indicating the Belgian ID card number.
If requested, a value SHALL always be returned for the above claims.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete.
The following restrictions apply to redirect URIs: The redirect URI MUST match the value preregistered during the registration.The redirect URI MUST begin with the scheme https (refer to this section for more information). There is an exception for localhost redirect URIs that are only permitted for development purposes, it’s not for use in production.The redirect URI SHALL NOT be a custom URL.The fragment identifier introduced by a hash mark # SHALL NOT be used.The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc MAY be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.If relevant (in case you have a mobile app) make sure that your redirect URIs 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. Universal links and App links are standard web links (http://mydomain.com) that point to both a web page and a piece of content inside an app. When a Universal Link is opened, the app OS checks to see if any installed app is registered for that domain. If so, the app is launched immediately without ever loading the web page. If not, the web URL is loaded into the webbrowser.
state
Strongly RECOMMENDED
Specifies any string value that your application uses to maintain state between your Authorization Request and the Authorization Server's response. You can use this parameter for several purposes, such as directing the user to the correct resource in your application and mitigating cross-site request forgery.
nonce
Strongly RECOMMENDED
A string value used to associate a session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authorization Request to the ID Token.
ui_locales
OPTIONAL
Indicates the user's preferred languages for the itsme® sign-in page, represented as a space-separated list of language tag values, ordered by preference.
Possible values : frnldeen
display
OPTIONAL
Specify how the itsme® sign-in page should be displayed to the user. Currently, only the page value is supported but in the future we might support additional display modes like touch.
acr_values
OPTIONAL
Indicates the authentication method required to process the request, represented as a space-separated list of tag values, ordered by preference.
Possible values : http://itsme.services/v2/claim/acr_basichttp://itsme.services/v2/claim/acr_advanced
Note : if these two values are provided only the most constraining authentication method will be applied, e.g. http://itsme.services/v2/claim/acr_advanced.
http://itsme.services/v2/ claim/acr_basic
It lets the user to choose either fingerprint usage (if device is compatible) or itsme® code. If the acr_values parameter is not specified, this is the default authentication method.
http://itsme.services/v2/ claim/acr_advanced
It forces the user to use his itsme® code.
claims
OPTIONAL
Allows to request specific user's details ("claims"). You can choose to receive those claims either in the ID Token (from /token endpoint) or in the UserInfo object (from /userinfo endpoint). It MUST be a JSON object containing an {"id_token":{...}} member or a {"userinfo":{...}} member respectively. This member will then contain all the desired claims - see example below. Note: to avoid the need of a /userinfo request, itsme® recommends to retrieve the claims directly from the ID Token.
Supported claims are listed below.
name
OPTIONAL
Returns user's full name in displayable form including all name parts, possibly including titles and suffixes.
If requested, a value SHALL always be returned for this claim.
given_name
OPTIONAL
Returns user's given name(s) or first name(s). Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
If requested, a value MAY NOT be returned if the user doesn't have any first name(s).
family_name
OPTIONAL
Returns user's surname(s) or last name(s). Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
If requested, a value SHALL always be returned for this claim.
birthdate
OPTIONAL
Return user's birthdate, represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate_as_string claim: at least one of the 2 SHALL return a value. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Returns user's birthdate in an unprocessed way, as mentioned on the ID document. itsme® users are always 16 years old or more.
BE: A value MAY NOT be returned for users with a Belgian ID document. It forms a pair with the birthdate claim: at least one of the 2 SHALL return a value. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
gender
OPTIONAL
Returns user's gender. Possible values are : femalemaleunknownn/a
BE: A value SHALL always be returned for users with a Belgian ID document. Belgian accounts can only be female or male NL: A value MAY NOT be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
locale
OPTIONAL
Returns user's mobile phone language, represented as a string format. Possible values are : NLFRDEEN
If requested, a value MAY NOT be returned for this claim.
picture
OPTIONAL
Returns user's ID picture, represented as a URL string. This URL refers to an image file (for example, a JPEG, JPEG2000, or PNG image file). This image is the raw (unprocessed) image contained on the ID document.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
Accessing this URL has to be done with your bearer token. Example: GET /v2/picture HTTP/1.1 Host: idp.prd.itsme.services Authorization: Bearer SlAV32hkKG
Returns user's ID picture, represented as a JSON Object containing these members: format: the MIME type value: the base64 encoded image.
This picture is read from the ID document but converted to always return a 200x140 px, 24 BPP JPEG image.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
email
OPTIONAL
Returns user's email address.
If requested, a value MAY NOT be returned.
email_verified
OPTIONAL
Returns true if the user's e-mail address is verified; otherwise false.
Note : currently, itsme® always returns false for this claim because the email verification feature is not yet implemented in our systems.
If requested, a value SHALL NOT be returned if the email claim is not filled with a value.
phone_number
OPTIONAL
Returns user's phone number, represented as a string format. For example : [+][country code] [subscriber number including area code].
If requested, a value SHALL always be returned for this claim.
phone_number_verified
OPTIONAL
Returns true if the user's phone number is verified; otherwise false.
If requested, a value SHALL always be returned for this claim. Note: currently, all phone numbers are verified so this claims always returns true.
address
OPTIONAL
Returns user's postal address, represented as JSON Object containing some or all of these members: formattedstreet_addresspostal_codelocality.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_citizenship
OPTIONAL
Returns user's nationality. The format is directly depending on the underlying ID document: for Belgian ID documents this is represented as a string, and for Dutch or Lux ID documents this is represented in the ISO 3166-1 alpha-3 format.
If requested, a value SHALL always be returned for this claim.
BE: Please be aware that this claim is computed by itsme® for users with a Belgian ID document on a best effort basis. For the original value as stored on the ID document, see http://itsme.services/v2/claim/claim_citizenship above. Therefore, a value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/place_of_birth
OPTIONAL
Returns user's place of birth, represented as a JSON Object containing some or all of these members formattedcitycountry.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/BEeidSn
OPTIONAL
Returns user's Belgian ID document number, represented as a string with 12 digits in the form xxx-xxxxxxx-yy. (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. This claim is made redundant by the IDDocumentSN claim below which we advise to use instead.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/claim_device
OPTIONAL
Returns user's phone information, represented as a JSON Object containing some or all of these members osappNameappReleasedeviceLabeldebugEnableddeviceIDosReleasemanufacturerdeviceLockLevelsmsEnabledrootedmsisdndeviceModelsdkRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/transaction_info
OPTIONAL
Returns information about the itsme® transaction, represented as a JSON Object containing some or all of these members securityLevelbindLevelappRelease.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/BENationalNumber
OPTIONAL
Returns user's Belgian unique identification number, represented as a string with 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the birthdate of the person, xxx a sequential number (odd for males and even for females) and cd a check-digit. Some exceptions could apply.
BE: A value SHALL always be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityFrom
OPTIONAL
This is a metadata. Returns user's Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn. BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL NOT be returned for users with a Dutch ID document. LU: A value SHALL NOT be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/validityTo
OPTIONAL
This is a metadata. Returns user's Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. Can only be returned in combination with claim http://itsme.services/v2/claim/BEeidSn.
If requested, a value MAY NOT be returned for users with a Belgian ID document, and MAY NOT be returned for users with a Dutch ID document.
http://itsme.services/v2/ claim/verificationDate
OPTIONAL
This is a metadata. Returns the date when the user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss date format specified by ISO 8601.
BE: A value MAY NOT be returned for users with a Belgian ID document. NL: A value SHALL always be returned for users with a Dutch ID document. LU: A value SHALL always be returned for users with a Luxembourgish ID document.
http://itsme.services/v2/ claim/IDDocumentSN
OPTIONAL
Returns the ID document number, represented as a string. If requested, a value SHALL always be returned for this claim: BE: The BE eID number is a string with 12 digits in the form xxx-xxxxxxx-yy (the check-number yy is the remainder of the division of xxxxxxxxxx by 97) for Belgian citizens, or starting with a letter and nine digits in the form B xxxxxxx xx for EU/EEA/Swiss citizens. NL: A 9-chars string with letters at positions 1 and 2, letters or digits in positions 3 to 8 and a digit at position 9. The letter ‘O’ is not used in the NL document numbers. The digit ‘0’ (zero) MAY be used. LU: Format not documented.
http://itsme.services/v2/ claim/IDDocumentType
OPTIONAL
Returns the ID document type. This is a 1 or 2 characters code defined by the ICAO. Identity cards have a code with first letter I while passports have a code starting with P.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/IDIssuingCountry
OPTIONAL
This is a metadata. Returns the 3-letters iso code of the country that issued the identity document.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/issuance_locality
OPTIONAL
This is a metadata. Returns the locality that issued the ID document used to create the itsme® account.
If requested, a value MAY NOT be returned for this claim.
http://itsme.services/v2/ claim/app
OPTIONAL
Returns a JSON object with 3 members: appInstalledDate contains the date when the app was installed on the user's device, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. appName contains the name of the app and appRelease contains a string identifying the release (example: "4.9.1"). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/account
OPTIONAL
Returns a JSON object with 3 members: activationDate contains the date when the account was last activated (enrolled or unblocked), represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. activationMechanism contains a string identifying the way this account was created. Possible values are "CARD_READER" (enrollment via a physical reading of the ID document chip), "CONTACT_LESS" (enrollment via a NFC reading of the ID document) or "ID_PROVIDER" (enrollment via a trusted partner, i.e. a bank). This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
http://itsme.services/v2/ claim/transaction_ip
OPTIONAL
Returns the IP address of the smartphone approving the transaction. This claim is intended to help partners detect fraudulent use cases.
If requested, a value SHALL always be returned for this claim.
request_uri
OPTIONAL
A URL using the https scheme referencing a resource containing a JWT whose claims are the request parameters. The request_uri parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request_uri parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The following restrictions apply to request URIs: The request URI MUST be preregistered during the registration.The request URI MUST contain the TCP port number 443. Example : https://test.istme.be:443/p/testThe request URI MUST begin with the scheme https (refer to this section for more information). The usage of localhost request URIs that are not permitted.The request URI JWT MUST be publicly accessible.
request
OPTIONAL
It represents the request as a JWT whose Claims are the request parameters. The request parameter is used to secure parameters in the Authorization Request from tainting or inspection when sending the request to the itsme® Authorization Endpoint.
If the request parameter is used, the JWT MUST be signed and MUST contain the claims iss (issuer) and aud (audience) as members. The iss value SHOULD be your client_id. The aud value SHOULD be set to https://idp.[e2e/prd].itsme.services/v2/authorization. The JWT MUST also be encrypted and more precisely: it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
code_challenge
OPTIONAL
A challenge derived from the code verifier by applying a S256 hash. This parameter is REQUIRED if you requested PKCE to be enforced.
code_challenge_method
OPTIONAL
Code verifier transformation method.
It MUST be set to S256.
Response
302application/x-www-form-urlencoded
code
An intermediate opaque credential of 36 characters used to retrieve the ID Token and Access Token.
Note : the code has a lifetime of 3 minutes.
state
The string value provided in the Authorization Request. You SHOULD validate that the value returned matches the one supplied.
POST https://idp.[e2e/prd].itsme.services/v2/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
client_assertion_type
REQUIRED
Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
REQUIRED
Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The JWT contains the following claims.
iss
REQUIRED
The issuer of the token. This value MUST be the same as the client_id.
sub
REQUIRED
The subject of the token. This value MUST be the same as the client_id.
aud
REQUIRED
The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token.
jti
REQUIRED
An unique identifier for the token, containing maximum 255 characters.
exp
REQUIRED
The expiration time of the token in seconds since January 1, 1970 UTC.
iat
OPTIONAL
The time at which the JWT was issued.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
client_secret
REQUIRED
Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://idp.[e2e/prd].itsme.services/v2/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
client_assertion_type
REQUIRED
Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
REQUIRED
Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information).
The JWT contains the following claims.
iss
REQUIRED
The issuer of the token. This value MUST be the same as the client_id.
sub
REQUIRED
The subject of the token. This value MUST be the same as the client_id.
aud
REQUIRED
The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token.
jti
REQUIRED
An unique identifier for the token, containing maximum 255 characters.
exp
REQUIRED
The expiration time of the token in seconds since January 1, 1970 UTC.
iat
OPTIONAL
The time at which the JWT was issued.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token
To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.
Parameters
grant_type
REQUIRED
Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
client_id
REQUIRED
It identifies your application. This parameter value is generated during registration.
code
REQUIRED
The intermediate opaque credential received in the Authorization Response.
redirect_uri
REQUIRED
It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
client_secret
REQUIRED
Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
code_verifier
OPTIONAL
High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
Response
200application/json
access_token
Allows an application to retrieve consented user information from the UserInfo Endpoint.
token_type
Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
id_token
A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://idp.[e2e/prd].itsme.services/v2/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://idp.[e2e/prd].itsme.services/v2/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo
The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.
This is illustrated in the example below.
Response
200application/json
The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke
The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.
Parameters
token
REQUIRED
The access_token previously obtained that you want to revoke.
token_type_hint
OPTIONAL
A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.
Response
200
itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke
The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.
Parameters
token
REQUIRED
The access_token previously obtained that you want to revoke.
token_type_hint
OPTIONAL
A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.
Response
200
itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
Customer Identity Cloud is the Customer IAM product from Okta. It can be configured to use itsme® as an Identity Provider via the OpenID Connect standardized protocol.
Prerequisite
Contact onboarding@itsme-id.com to request the creation of your account, specifying that your authentication method will be “Client Secret”. You will then receive a Client ID and a Client Secret (= password, handle with care) that will be needed in the Okta configuration. You will also receive a Service Name to be included in your config.
Add an ID provider
The first step is to add a new Identity Provider in your Okta portal. This can be done by selecting the “Security” tab, then “Identity Providers” and clicking “Add identity provider”.
On the next screen, choose “OpenID Connect IdP”. After that, you need to fill in your IdP configuration:
Name can be anything, “itsme” is a good example.
IdP Usage depends on your use case.
Scopes will depend on which attributes you need to receive, but must contain at least openid and service:servicename
Authentication type should be Client Secret
Client ID and Client Secret are the one you received from Customer Care
Enable signed request and PKCE should be supported as well, but are not mandatory
The endpoints to be configured have to be the ones described in our Discovery Document:
The Authentication Settings will depend on your use case. In the example above, the reconciliation of a connecting user with a known user in Okta DB is done via their Belgian National Register Number, but the ID key could be an email or any other attribute you see fit.
Customer Identity Cloud is the Customer IAM product from Okta. It can be configured to use itsme® as an Identity Provider via the OpenID Connect standardized protocol.
Prerequisite
Contact onboarding@itsme-id.com to request the creation of your account, specifying that your authentication method will be “Client Secret”. You will then receive a Client ID and a Client Secret (= password, handle with care) that will be needed in the Okta configuration. You will also receive a Service Name to be included in your config.
Add an ID provider
The first step is to add a new Identity Provider in your Okta portal. This can be done by selecting the “Security” tab, then “Identity Providers” and clicking “Add identity provider”.
On the next screen, choose “OpenID Connect IdP”. After that, you need to fill in your IdP configuration:
Name can be anything, “itsme” is a good example.
IdP Usage depends on your use case.
Scopes will depend on which attributes you need to receive, but must contain at least openid and service:servicename
Authentication type should be Client Secret
Client ID and Client Secret are the one you received from Customer Care
Enable signed request and PKCE should be supported as well, but are not mandatory
The endpoints to be configured have to be the ones described in our Discovery Document:
The Authentication Settings will depend on your use case. In the example above, the reconciliation of a connecting user with a known user in Okta DB is done via their Belgian National Register Number, but the ID key could be an email or any other attribute you see fit.
