The following sequence diagram denotes partially the steps executed, with regards to the user who needs to be authenticated.
Start a new Session
The initial call sets the context for a new session. The context must be unique for each user who needs to log in. Once the context has been created a JWT is issued and can be used to redirect the user to the authentication page.
// Example redirect URL
https://auth.t1t.eu?token={{received JWT from SET context}}
Set Context
A new session can be started by initiating a POST request with your provided 'apikey':
A UNIQUE identifier created by the service consumer
useCase
string
predefined use case: "auth" starts the authentication flow
means
list of strings
denotes which means should be available for the end-user; when 'beid' and 'luxid' are added, user device will search for Belgian eID and Luxembourg ID tokens in connected readers. The abbreviations allign with the Trust1Connector module names. All registered tokens from the Trust1Connector can be uses
redirectUri
Option[string]
This is the page where the user is redirected towards, once the flow has been completed (for both success AND failure scenario)
webhookUri
Option[string]
this is the URI which will be used by the service to POST a HTTP (Json) request with the authentication flow result
sessionTimeInMinutes
integer
this defines the expiration time of the issues JWT token, and hence the time in which the session will stay valid
pubKey
Optional[string]
base64 encoded PEM for the public key provided by the integration provider (consuming web application); the key is used to encrypt sensitive data (biometric property in the webhook response) received from the authenticating user
lang
Optional[string]
nl, fr, en, de (the languaged loaded by default)
The pubKey used must be a
4096 bit RSA
, the encryption padding uses is:
PKCS1_OAEP
The webhooUri and redirectUri, when not provided, no feedback is provided to the consumer, the consumer needs to GET the information using the HTTP/REST API.
Example Response
The HTTP reponse contains a Json reponse with a token property
{
"token": "eyJ0eXAiOiJKV1Qi...wtZpmCWoJVQ"
}
The token MUST be set for the end-user to start the flow on the Authentication web page.
The token is added as a query parameter on the URL for the Authentication web page:
// Example redirect URL
https://auth.t1t.eu?token=eyJ0eXAiOiJKV1Qi...wtZpmCWoJVQ
From here the user will be guided through the authentication flow
Optional: Provide a public key for response encryption
In the set context request, an optional public key can be provided by the web application who wants to use the Trust1Authentication service.
When a public key is provided, the biometric information from the authentication user will be encrypted with the provided public key, on the user's device itself, avoiding any data to be leaked during the authentication flow.
No sensitive data is stored on the Trust1Authentication service.
Parse the received result (success)
Once the user has completed the flow, the webhookUri will be used, prior to initiating the redirect (redirectUri).
The webhook MUST be a POST HTTP endpoint, who will expect the following data to be received:
{"sessionContext": {"id":"66961584-a00d-46dc-96e6-c494582e99f2","org_id":"187144be-e4ef-4826-8845-93057ac4fae3","org_name":"Trust1Team","correlation_id":"06c74b0b-f5f5-4b71-847d-5813bde62e63","use_case":"auth","means":"beid,luxid","redirect_uri":"https://trust1team.com","webhook_uri":"https://mbwgm22d.ngrok.app","webhook_http_method":"POST","session_time_in_minutes":30,"created_at":"2024-05-02T07:10:44.490751" },"sessionTracker": {"id":"66961584-a00d-46dc-96e6-c494582e99f2","token_issued":true,"token_validated":true,"connector_installed":true,"reader_connected":true,"identity_found":true,"mean_pin_result":true,"mean_cert_valid":true,"gsm_input":true,"gsm_otp_input":true,"gsm_otp_code":"1938","gsm_nr":"+32...","auth_digest_signed":"ZmVkZGJlMmM5NWNiYzA1YmI2N2ZlOGI4YTg2ZGE0Mzk5NzAxZTkwN2Y3NmFhMjQyOGE3Mjg1ZTM0YzZlNjljNg==","error_state":false,"cancel_state":false,"success_state":true,"result_state":"SEND","created_at":"2024-05-02T07:10:44.500004","updated_at":"2024-05-02T09:12:10.315752" },"bio":"bio OR encrypted(bio)","validationReport":"https://acc-auth-api.t1t.eu/v1/auth/report/06c74b0b-f5f5-4b71-847d-5813bde62e63","isSuccess":true}
The included bio data is provided as a Json string (encrypted only if the session has been created with a public key property).
The Json has the following format:
{"birthDate":"03 MEI 2001","birthLocation":"Leuven","cardDeliveryMunicipality":"Brussel","cardNumber":"000001244125","cardValidityDateBegin":"05.07.2022","cardValidityDateEnd":"05.07.2032","chipNumber":"U0xHkAJRAAAiJSiPEpIDYw==","documentType":"1","firstNames":"Nora Angèle","name":"Specimen","nationalNumber":"01050399963","nationality":"BELG","nobleCondition":"","pictureHash":"R2osQHL1+wdkLiVtXt/XnGpnX8aSYtMn+ZeQUVF7CAE=","rawData":"AQwwMDAwMDEyNDQxMjUCEFNMR5ACUQAAIiUojxKSA2MDCjA1LjA3LjIwMjIECjA1LjA3LjIwMzIFB0JydXNzZWwGCzAxMDUwMzk5OTYzBwhTcGVjaW1lbggMTm9yYSBBbmfDqGxlCQAKBEJFTEcLBkxldXZlbgwLMDMgTUVJIDIwMDENAVYOAA8BMRABMBEgR2osQHL1+wdkLiVtXt/XnGpnX8aSYtMn+ZeQUVF7CAE=","sex":"V","signature":"MGYCMQDRA/MOgdMSE3GoJFTanZOILLdEH14T/O489tLFa1g4AsI/S0q+uw5mZzuXHKE3WXwCMQDHqPdSSfrsxsnMG1SKKz02N1X64JAORW/CdYqrAWjrI08lJVa68zgezM3FdXXGt4oAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==","specialStatus":"0","thirdName":"","version":"0" }
When there is no bio information available (typically for PKCS11 only tokens), the bio not be provided upon a successful authentication response
Parse the received result (failed)
When the session has been expirect, and no successfull result has been pushed OR when the use case fails in a way that the end-user is blocked, a response will be sent to the webhook with isSuccess: false An additional error property is added with more explanation. The session context and tracker is always provided in the respone:
When a user cancels, the webhook is called with a similar response as the failure response. The main difference is that the cancel_state property will be set to false
Examples
Generate 4096 bit RSA Keypair
The RSA keypair generated MUST have a size of 4096 bit:
