Link Search Menu Expand Document

Introduction

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 CSC API is an API built based on the CSC specification version 1.0.4.0. See https://cloudsignatureconsortium.org and https://cloudsignatureconsortium.org/resources/download-api-specifications to get the specification. The spec is implemented based on the OAuth2 specification.

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.

Sequence diagram describing the CSC Hash Signing flow

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.

Example:

POST /info
{
  "lang": ""
}

response:

{
  "specs": "1.0.3.0",
  "name": "itsme®",
  "logo": "https://itsmeprdweucscgeneral.blob.core.windows.net/public/logo.jpg",
  "region": "BE",
  "lang": "EN-US",
  "description": "itsme®, your digital ID and a smarter way to sign with your smartphone.",
  "authType": [ "oauth2code" ],
  "oauth2": "https://sign.prd.itsme.services/csc/v0/oauth2/authorize",
  "methods": [ "info", "auth/revoke", "oauth2/authorize", "oauth2/token", "credentials/list", "credentials/info", "signatures/signHash" ]
}

2. Authorization request

Starts the OAuth 2.0 authorization server using an Authorization Code flow to request authorization for the user to access the remote service resources. The authorization is returned in the form of an authorization code, which the signature application SHALL then use to obtain an access token with the oauth2/token method. After a successful authorization, the server shall send a redirect to the given redirect URI.

Below you will find the mandatory and optional query parameters to integrate in the HTTPS GET request:

client_id
REQUIRED
The ClientId you received during the onboarding process.
redirect_uri
REQUIRED
The URI to which the authentication response should be sent. This must exactly match the redirect URI or regex redirect URI (including query string) configured during the onboarding process.
scope
REQUIRED
The value has to be service.
response_type
REQUIRED
The value has to be code.
lang
optional
The language in which the authorization request is displayed. Supported values are NL, DE, EN FR and their respective ISO language codes. If no value is specified or the language isn't supported, defaults to EN.
state
optional
The state property is an optional value and is returned in the response of the authorize request. This allows you to maintain a session between your request and our response.
account_token
REQUIRED
This is the JWT token as defined in RFC 7519 and the CSC documentation.
account_token = base64UrlEncode(<JWT_Header>) + "." + base64UrlEncode(<JWT_Payload>) + "." + base64UrlEncode(<JWT_Signature>)
whereby
<JWT_Header> = {
          "typ": "JWT",
          "alg": "HS256"
        }
<JWT_Payload> = {
          "sub": "<Account_ID>", ‘Account ID
          "iat": <Unix_Epoch_Time>, ‘Issued At Time
          "jti": "<Token_Unique_Identifier>", ‘JWT ID
          "iss": "<Signature_Application_Name>", ‘Issuer
          "azp": "<client_id>" ‘Authorized presenter
        }
<JWT_Signature> = HMACSHA256(
          base64UrlEncode(<JWT_Header>) + "." +
          base64UrlEncode(<JWT_Payload>),
          SHA256(<client_secret>)
        )
Parameters:
typ
REQUIRED
MUST be the value JWT.
alg
REQUIRED
MUST be the value HS256.
sub
REQUIRED
The client-defined account_id that allows the RSSP to identify the account or user initiating the authorization transaction.
iat
REQUIRED
The Unix Epoch time when the account_token was issued. The value is used to determine the age of the JWT. The RSSP SHOULD define the lifetime of the JWT and SHALL accept or reject an account_token based on its own expiration policy.
jti
REQUIRED
A unique identifier for the JWT. This protects from replay attacks performed by reusing the same account_token.
iss
OPTIONAL
The name of the issuer of the token (e.g. the commercial name of the signature application).
azp
REQUIRED
The unique client_id previously assigned to the signature application by the remote service.
Implementation notes
  • itsme SHALL securely share the OAuth 2.0 client_id and client_secret with the SCA as part of the onboarding process.
  • The JWT_signature required to generate the account_token SHALL be calculated with the HMAC function, using as shared secret the SHA256 hash of the OAuth 2.0 client_secret.
  • The SCA MUST register in advance with itsme the list of Account_ID parameters associated with those users that are authorized to access a restricted authorization server.
clientData
not supported
As clientData can expose confidential data, we do not support it.

Example:

GET /oauth/authorize?
response_type=code
&client_id={ClientId}}
&redirect_uri={RedirectUrl}
&scope=service
&lang={EN | FR | NL | DE}
&state=example
&account_token={AccountToken}

3. Capturing the authorization code

If the user is successfully authenticated and authorizes access to the Identification Request, the authorization server will return an authorization code and the provided state.

Example:

{
  302  Found
  Location: {RedirectUrl}?
  code=66353038303864632D306665392D346563352D393633352D3565616431383639376261357C426561726572
  &state=example
}

4. Requesting a token

Obtain an access token from the authorization server by passing the clientId and clientSecret in the body. After a successful request, the authorization server will return a bearer or SAD token, depending on the scope in the oauth2/authorize method.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

grant_type
REQUIRED
For the moment authorization_code is the only supported value.
client_id
REQUIRED
The ClientId you received during the onboarding process.
client_secret
REQUIRED
The Client Secret you received during the onboarding process.
code
REQUIRED
The code returned by the authorize request.
redirect_url
REQUIRED
Should be equal to the redirect URI provided in the authorize request.

Example:

POST /oauth2/token
{
  "grant_type": "authorization_code",
  "client_id": "{ClientId}",
  "client_secret": "{ClientSecret}",
  "code": "66353038303864632D306665392D346563352D393633352D3565616431383639376261357C426561726572",
  "redirect_uri": "{RedirectUrl}"
}

response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ",
  "refresh_token": null,
  "token_type": "Bearer",
  "expires_in": 3600
}

5. Getting credential id(‘s)

Returns the list of credentials associated with a user identifier, an itsme® user will always have exactly 1 credential.

This POST request contains only 1 parameter:

maxResults
REQUIRED
The maximum number of items to return from this call. The value MUST be between 1 and 300.

Example:

POST /credentials/list
Content-Type: application/json
Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ
{
  "maxResults": 10
}

response:

{
  "credentialIDs": [
      "f7642e62-72eb-4e83-8825-80c67d402c03"
  ]
}

6. Obtaining credential info

Retrieve the credential and return the certificate chain associated with it. Using the Certificate Info, the SCA can calculate the hash of the document to be signed.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

credentialID
REQUIRED
The credentialId obtained in the credentials/list method.
certificates
REQUIRED
The only value supported right now is chain. This means that the full certificate chain will be returned.
certInfo
Optional
Supported values are true or false. If set to true various parameters will contain information from the end entity certificate. The default value is is false.
authInfo
Optional
We do not support this setting.
lang
Optional
The same value as provided in the authorize request.

Example:

{
  POST /credentials/info
  Content-Type: application/json
  Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ
  {
    "credentialID": "f7642e62-72eb-4e83-8825-80c67d402c03",
    "certificates": "chain",
    "certInfo": true,
    "lang": "{EN | FR | NL | DE}"
  }
}

response:

{
  "description": null,
  "key": {
      "status": "enabled",
      "algo": [
          "1.2.840.113549.1.1.11"
      ],
      "len": 2048
  },
  "cert": {
      "status": "valid",
      "certificates": [
          ...
      ],
      "issuerDN": "Provided if certInfo is true",
      "serialNumber": "Provided if certInfo is true",
      "subjectDN": "Provided if certInfo is true",
      "validFrom": "Provided if certInfo is true",
      "validTo": "Provided if certInfo is true"
  },
  "authMode": "oauth2code",
  "SCAL": "2",
  "PIN": {
      "presence": "false",
      "label": null,
      "description": null
  },
  "OTP": {
      "presence": "false",
      "type": null,
      "ID": null,
      "provider": null,
      "format": null,
      "label": null,
      "description": null
  },
  "multiSign": true
}

7. Authorization request (Dance 2)

This GET request should include the following query parameters:

client_id
REQUIRED
The ClientId you received during the onboarding process.
redirect_uri
REQUIRED
The URI to which the authentication response should be sent. This must exactly match the redirect URI or regex redirect URI (including query string) configured during the onboarding process.
scope
REQUIRED
The value has to be credential.
response_type
REQUIRED
The value has to be code.
lang
optional
The language in which the authorization request is displayed. Supported values are NL, DE, EN FR and their respective ISO language codes. If no value is specified or the language isn't supported, defaults to EN.
state
optional
The state property is an optional value and is returned in the response of the authorize request. This allows you to maintain a session between your request and our response.
account_token
REQUIRED
This is the JWT token as defined in RFC 7519 and the CSC documentation. See description above.
credentialID
REQUIRED
The credentialId obtained in the credentials/list method.
numSignatures
REQUIRED
This value must be the number of hashes you are sending. Must be between 1 and 70.
hash
REQUIRED
A (list of) base64url-encoded hash value(s) to be signed. It allows the server to bind the SAD to the hash, thus preventing an authorization to be used to sign a different content. Multiple (up to 70) hashes are supported in the form of a comma-seperated list.
description
Optional
An optional description about the (package of) document(s) being signed. This value will be visible in the itsme application.
clientData
not supported
As clientData can expose confidential data, we do not support it.

Example:

GET /oauth/authorize?
response_type=code
&client_id=
&redirect_uri=
&scope=credential
&lang=
&state=test
&credentialID=f7642e62-72eb-4e83-8825-80c67d402c03
&numSignatures=2
&hash=w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI%3d,11rkeh832bdhwzc99iuvwegst9bfi8hgirfr5Rms8iXi
&description=exampleDescription

8. Capturing the authorization code

If the user is successfully authenticated and authorizes access to the Identification Request, the authorization server will return an authorization code and the provided state.

Example:

{
  302  Found
  Location: {RedirectUrl}?
  code=66353038303864632D306665392D346563352D393633352D3565616431383639376261357C426561726572
  &state=example
}

9. Requesting a token

Obtain an access token from the authorization server by passing the clientId and clientSecret in the body. After a successful request, the authorization server will return a bearer or SAD token, depending on the scope in the oauth2/authorize method.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

grant_type
REQUIRED
For the moment authorization_code is the only supported value.
client_id
REQUIRED
The ClientId you received during the onboarding process.
client_secret
REQUIRED
The Client Secret you received during the onboarding process.
code
REQUIRED
The code returned by the authorize request.
redirect_url
REQUIRED
Should be equal to the redirect URI provided in the authorize request.

Example:

POST /oauth2/token
{
  "grant_type": "authorization_code",
  "client_id": "{ClientId}",
  "client_secret": "{ClientSecret}",
  "code": "61316261316233612D383732392D346239312D613534322D3037643635393933623134617C534144",
  "redirect_uri": "{RedirectUrl}"
}

response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ",
  "refresh_token": null,
  "token_type": "Bearer",
  "expires_in": 3600
}

10. Sign hash

Calculate the remote digital signature of the hash value provided in the request. This method requires credential authorization in the form of Signature ctivation Data (SAD) in the request body and the bearer token in the headers.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

credentialID
Required
The credentialId retrieved from the credentials/list method.
SAD
Required
The SAD token retrieved from the oauth2/token method.
hash
Required
Array containing the base64 value(s) of the hash(es) provided in the oauth2/authorize method.
signAlgo
Required
The OID of the algorithm to use for signing as provided in the credentials/info response.

Example:

POST /signatures/signhash
Content-Type: application/json
Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ
{
  "credentialID": "f7642e62-72eb-4e83-8825-80c67d402c03",
  "SAD": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZmZhMDZlNy1lNmUyLTQ2NTgtYmE4OC1hODFiMzMwN2JkZGUiLCJuYW1lIjoiaGN3OWpoYzFuNmdqODN3OGlwYWx3endmeG16a2Vmc2x4MGl0IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJaUjdRUFNIVjNJWFJSS0k3WlZSQVlPR0hQNlRJR0ZWUyIsIkNyZWRlbnRpYWwiOiJ0cnVlIiwiZXhwIjoxNTYyMTQyNDE4LCJpc3MiOiJjc2NfYXBpIiwiYXVkIjoiY3NjX2FwaSJ9.KJvjsN6Ao3ZqJBaifoku2MlUNdwdhJX8RZ_IO68Z5hg",
  "hash": [
    "w6uP8Tcg6K2QR905Rms8iXTlksL6OD1KOWBxTK7wxPI=",
    "11rkeh832bdhwzc99iuvwegst9bfi8hgirfr5Rms8iXi"
  ],
  "signAlgo": "1.2.840.113549.1.1.11"
}

response:

{
  "signatures": [
    "i0H6bbiwVcxGDjGeNn2qhY...gbWbs6/pp9lWe4w6o5UG3BZhiZUfQ==",
    "uiainrstinertanierstn398aiu...iueldvpa65enzdljr98lvvddq="
  ]
}

11. Revoke session

Revoke an active active token with this request. When the signature application needs to terminate a session, it is RECOMMENDED to invoke this method to prevent further access by reusing the token. Otherwise the session will be deleted after one hour.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

token
Required
The access token retrieved in the first oauth2/token method.
token_type_hint
Required
This value MUST be access_token
clientData
Not supported
As clientData can expose confidential data, we do not support it.

Example:

POST /auth/revoke
Content-Type: application/json
Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmN2VlM2ZiNS0yOWRhLTQ5OTktYTZmMy01NTE1YTYwN2RlYTYiLCJuYW1lIjoiOXdxOWlpOG5kaWxmMzZrM3VvemVoOGdua2pzODRzY210aTc3IiwiQXNwTmV0LklkZW50aXR5LlNlY3VyaXR5U3RhbXAiOiJZSU02T0lVM0RNNUhUSEhGUEpUU09FSUM3Rk9ORzVXNiIsImV4cCI6MTU4MDM5ODYyOCwiaXNzIjoiY3NjX2FwaSIsImF1ZCI6ImNzY19hcGkifQ.kJERr_vNQaRabwSulL0Xbi2RBmrpXypvrxcGDC58nUQ",
  "token_type_hint": "access_token"
}

response:

204 NOCONTENT

Appendixes

Supported character set

The character set we support for free text fields is ISO 8859-15. You can buy the specification on ISO website or find a free version on Wikipedia. You might be interested in knowing that, although most usual characters are supported, some softwares-generated characters like curly apostrophes and long dashes are not part of ISO 8859-15. If you provide a non-supported character in a free text field the signing flow will be stopped and you will receive an error message back.