Strong Player Authentication

This describes how to use a strong authentication method provided by Checkin.com. These examples shows how to use a Swedish BankID, but there are several other strong person authentication methods available in other countries which are covered with the same integration.

For more details and a description of the standard Checkin.com solution please see Integrate Checkin.com in 3 Quick Steps

Triggering Sign-in with strong authentication

The Authentication module is added as a part of the normal flow and is loaded by your standard Regily script. It is also triggered in the same way.

For authentication to be initiated as a first step, set regilyMode: 'signin' before the module is triggered and instead of the registration flow the user will get prompted for the Strong Authentication method (such as BankID).

document.documentElement.dataset.regilyMode = 'signin';

Capture and handle the authentication callback (after login)

The regilyAuthenticationCallback will happen after the strong authentication is completed successfully. The handling of the authentication result is done with a promise in the same way as the other callbacks. By using resolve(...) you will be able to return information to the Checkin.com module.

Object.defineProperty(window, 'regilyAuthenticationCallback', {
  value: function (data) {
    return new Promise(function (resolve, reject) {

       // Check that the PNO authenticated by Bankid is valid
      const personalNumber = data.authentication.ssn
      console.log('Validating login for: ', personalNumber)

      // EXAMPLE: Call back-end to check if user is logged in (use "await" or "then")
      const result = await api.loginUserWithSSN(data.authentication)

      if(result === 'OK'){
         //Sending OK  will close the Regily Module
         resolve({auth: 'OK'})
         // EXAMPLE, then use internal mechanism for Redirect/push route to logged in page here
         window.location = 'https://www.targetdomain.com/sv/loggedin'
      }else if(result === 'REQUIRE_LIMITS'){
         // No log in, Regily module will collect player limits first
         resolve({auth: 'REQUIRE_LIMITS'})                  
      }else if(result === 'NOT_FOUND'){
         // No log in, Regily module will go to the sign up flow.
         resolve({auth: 'NOT_FOUND'})
      }else {
         //Error at the end if login did not work
         reject()
      }
    })
  }
})

You need to capture the regilyAuthenticationCallback and resolve the callback promise in different ways depending on the expected result.

• resolve({'auth':OK}. This should be used if the user already exists in your database and should be logged in. This closes the module and you can re-direct the user.
• resolve({'auth':REQUIRE_LIMITS}. This should be used if the user is found but has not set any player limits (mainly for gambling/casino scenarios)
• resolve({'auth':NOT_FOUND}. The user is not found and should get your Checkin.com registration flow.

The data structure for the regilyAuthenticationCallback is as follows:

{
   authentication:  {
      personalNumber: '199012295555',
      name: 'John Doe',
      authProvider: 'bankid_swe',
      transactionId: '131daac9-16c6-4618-beb0-365768f37288',
      authenticatorSpecificData: { ... }, // (see "Authenticator specific information")
      jwtSignData: 'DSFAWERQWEZADXASDFQWER....' (jwt signed data of all above)
   }
}

Data validation on server side

The authentication.jwtSignData data is encrypted using a Checkin.com secret key and will include all data in the authentication block (except the jwtSignData). This must be validated on server side to make sure that the Authentication is legitimate.

Reading all data from the token to do backend authentication is the preferred way of using the data. The Clear-text data in the structure is for convenience in the frontend. See Public verification token for how to validate using the Checkin.com public token

🚧

Back-end JWT token validation is mandatory

It is important to implement the token validation to ensure that the data is not manipulated in any way.

Changes to existing registration flow callbacks

All flows initiated with signin in Sweden will have a BankID authentication and login at the beginning. This also means that the data.authentication block will be sent in both the regilyUpdateCallback and the regilyDoneCallback alongside all existing fields. The authentication block should be sent to the backend as well in order to extract the token and verify that it has been signed by the Checkin.com Framework.

Authenticator specific information

Depending on the type of Strong Player Authentication method you are using, there will be additional unique data available for each method.

This unique data sent by the authenticator service is contained within authentication.authenticatorSpecificData and may be used for further analysis, tracking or validation. For Swedish BankId this will include Bank ID specific fields from the provider. See bankid docs for more info.

// ------ EXAMPLE DATA IN authentication.authenticatorSpecificData, relayed from BankID ------
{
 "orderRef":"131daac9-16c6-4618-beb0-365768f37288",
 "status":"complete",
 "completionData":{
   "user":{
      "personalNumber":"190000000000",
      "name":"Karl Karlsson",
      "givenName":"Karl",
      "surname":"Karlsson"
   },
 "device":{
   "ipAddress":"192.168.0.1"
   },
 "cert":{
   "notBefore":"1502983274000",
   "notAfter":"1563549674000"
 },
 "signature":"<base64-encoded data>",
 "ocspResponse":"<base64-encoded data>"
 }

📘

The data may change

Authenticator specific information is dependent on the country and type of identification and may change depending on provider