Authentication

Sequence diagram

As you can see, there are 2 calls your backend should make to the linkID API

authStart

This call will start a new linkID authentication. The result of this call will contain the sessionId to be used for polling later on and a LinkIDQRInfo object containing the linkID QR Code. This object will also contain a qr code URL to be displayed in mobile environments so when the user taps the link with that URL, the linkID app will be opened.

authPoll

This call will poll linkID for the status of the authentication. The LinkIDAuthenticationState field will tell you where the user is in the authentication process. Once the user has completed the authentication process, the LinkIDAuthnResponse field will contain all the details about the user ( userId, attributes, ... )

Code

Below are the bare minimum calls needed to start and poll a linkID authentication session.

Java

LinkIDServiceClient linkIDServiceClient = LinkIDServiceFactory.getLinkIDService( LinkIDConfig.get() );

LinkIDAuthenticationContext context = new LinkIDAuthenticationContext.Builder( LinkIDConfig.get().name() ).build();

LinkIDAuthSession linkIDAuthSession = linkIDServiceClient.authStart( context, userAgent );

...

LinkIDAuthPollResponse pollResponse = linkIDServiceClient.authPoll( sessionId, null );

.NET

LinkIDServiceClient linkIDServiceClient = new LinkIDServiceClientImpl("service.linkid.be", username, password);

LinkIDAuthenticationContext context = new LinkIDAuthenticationContext();
context.applicationName = applicationName;

LinkIDAuthSession linkIDAuthSession = authStart(context, HttpContext.Current.Request.UserAgent);

...

LinkIDAuthPollResponse pollResponse = linkIDServiceClient.authPoll(sessionId, null);

PHP

$client = new LinkIDClient("service.linkid.be, $username, $password);

$authenticationContext = new LinkIDAuthenticationContext($applicationName);

$linkIDAuthnSession = $client->authStart($authenticationContext, null);

...

LinkIDAuthPollResponse pollResponse = $client.authPoll($sessionId, null);

LinkIDAuthenticationContext

This is the object that defines the configuration of the authentication session. All parameters are optional except for the applicationName.

applicationName

The technical name of the linkID application you are creating a linkID session for. This name will be supplied to you from a linkID operator when he has setup your linkID application configuration.

language

The language for this linkID session. For this we except the language in the 2 letter ISO 639-1 code format

authenticationMessage

A custom authentication message to be displayed on the linkID mobile client.

Note that this field will be ignored if you are creating a payment linkID session. We do not allow to override this in the case of a payment to ensure the user is guaranteed to see a message with the valid amount to be payed. In this case you can use the LinkIDPaymentContext.description field for additional info.

finishedMessage

A custom message to be displayed when the linkID mobile client has finished the session.

identityProfile

A custom identify profile you wish to use for this session. Identity profiles define a set of attributes you require the user to provide to you before finalizing his session. When creating your linkID application configuration via a linkID operator ( or afterwards ) you can request several identity profiles suited for different situations.

For example during a signup process, you'd maybe want to only ask minimal info such as e-mail, firstName, lastName. But during a payment process, you'd want to also receive mobile, address, ...

sessionExpiryOverride

Each linkID session has an expiration date. By default this is 15 minutes. If you wish to change this, you can use this value. The value is provided in seconds

theme

Here you can specify a specific theme for this linkID session.
Read more about themes here

notificationLocation

If you wish to receive linkID notifications for this session at a different endpoint than the default configuration in your application, you can specify this here.
Read more about notifications here

mobileLandingSuccess, mobileLandingError, mobileLandingCancel

These landing pages only apply if you are starting a linkID session from a iOS mobile browser. Due to the way iOS works, it's not possible to land back on the page that started the linkID session. You can define custom landing pages for this situation to get your user where he should be in your webapp.

linkID defaults to respectively

• https://service.linkid.be/linkid-mobile/#/external/cb-success
• https://service.linkid.be/linkid-mobile/#/external/cb-error
• https://service.linkid.be/linkid-mobile/#/external/cb-cancel

attributeSuggestions

Attribute suggestions are a way where you can provide default values for attributes in the identity profile for the linkID session. For example, for a linkID session, you want an identity profile with the mobile phone attributes required. But for certain users you already have this data in your local database, yet for others you have not. To facilitate the login process you can provide this in the attribute suggestions and linkID will, if the linkID user data does not have the mobile phone attribute yet, default the missing attribute value to this.

paymentContext

Specify this to have your linkID authentication session be a linkID payment session.
Read more about linkID payments here

callback

If you wish to let the linkID user land on a callback page after he has finished the linkID session, you can provide this here.
Read more about linkID callbacks here