Certification Process

In order for a user to be able to confirm authentication transactions or to sign documents, they need to have first completed the certification process.

This process involves three steps : Verification, Registration & Certification.

Verification

The device that the app is running on needs to be verified before the user can be certified.

NB Even if the app supports multiple entities, the device only needs to be verified the once.

Before the device is verified, the user has a status of UNVERIFIED

To verify the device the user first needs to request a verification code:

Swift3

    SDK.getClient.requestUserDeviceVerification(
        onSuccess: {
            // Verification Request Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onDeviceVerificationLimitError: { (error) in
                // Handle device verification limit error
        }, onClientError:  { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestUserDeviceVerificationOnSuccess:^ {
          // Verification Request Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onDeviceVerificationLimitError:^void(NSError * _Nonnull error) {
            // Handle device verification limit error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
     ];

Documentation

If the verification request is successfully made, an SMS with a verification code is sent to the phone number of the device the user registered with.

When the user receives the code, it can be used to verify the device as follows:

Swift3

    SDK.getClient.verifyUserDevice(withVericationCode: code,
        onSuccess: {
            // Handle Verification Success
        }, onNoConnection: {
                // Handle no connection Error
        }, onInvalidToken: { (error) in
                // Handle invalid token error
        }, onValidationError: { (error) in
                // Handle validation error
        }, onExpiredVerificationCodeError: { (error) in
                // Handle expired verification code error
        }, onUserLockedError: { (error) in
                // Handle locked user error
        }, onClientError: { (error) in
                // Handle client error
    })

ObjC

    [biidCoreSDK.getClient verifyUserDeviceWithVericationCode:code
        onSuccess:^{
            // Handle Verification Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onValidationError:^void(NSError * _Nonnull error) {
                // Handle validation error
        }
        onExpiredVerificationCodeError:^void(NSError * _Nonnull error) {
                // Handle expired verification code error
        }
        onUserLockedError:^void(NSError * _Nonnull error) {
                // Handle locked user error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
     ];

Documentation

Registration

After verification the user will have a status of UNREGISTERED.

NB To check the status of a user, the requestUser API Call can be used as follows.

Swift3

    SDK.getClient.requestUser(
        onSuccess: { (user) in
            if user.status == User.Status.unregistered {
                // Unregistered
            }
        }, onNoConnection: {
            // Handle no connection
        }, onInvalidToken: { (error) in
            // Handle invalid token
        }, onClientError:  { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient requestUserOnSuccess:^(User * _Nonnull user) {
            if (user.status == UserStatusUnregistered) {
                // Unregistered
            }
        }
        onNoConnection:^void() {
         // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
         // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
          // Handle client error
        }
     ];

Documentation

To register, the user needs to fill in a registration form. The fields for the current entity can be retrieved and populated as follows :

Swift3

    var user = User()
    SDK.getClient.requestEntityDetails(
        onSuccess: { (entityDetails) in
            if let userFieldDefinitions = entityDetails.userFieldDefinitions {
                // Populate the user object for each field
                for field in userFieldDefinitions {
                    if let fieldName = field.name {
                        user[fieldName] = "XXX"
                    }
                }
            }
        }, onClientError: { (error) in
            // Handle client error
        }
    )

ObjC

    User *user = [[User alloc] init];
    [biidCoreSDK.getClient requestEntityDetailsOnSuccess:^(EntityDetails * _Nonnull entityDetails) {
            NSArray<FieldDefinition*> *userFieldDefinitions = entityDetails.userFieldDefinitions;
            // Populate the user object for each field
            for (FieldDefinition *field in userFieldDefinitions) {
                user[field.name] = @"XXX";
            }
        }
        onClientError:^void(NSError * _Nonnull error) {
           // Handle client error
        }
    ];

NB In the above examples no checks are being made on the type of field being populated. In real world code, checks should be made and the values assigned to the field adjusted accordingly i.e. correctly formatted dates should be assigned to date fields, numbers only to numeric fields etc.

Documentation

The populated User object can then be used to register the user as follows:

Swift3

    SDK.getClient.registerUser(withUser: user,
        onSuccess: {
            // Handle Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token Error
        }, onValidationError: { (error) in
            // Handle field validation Error
        }, onUserAlreadyRegisteredError: { (error) in
            // Handle user already registered Error
        }, onClientError: { (error) in
            // Handle client error
        }
    )

ObjC

    [biidCoreSDK.getClient registerUser:(User * _Nonnull)user
        onSuccess:^{
          // Handle Success
        }
        onNoConnection:^void() {
        // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
        // Handle invalid token error
        }
        onValidationError:^void(NSError * _Nonnull error) {
        // Handle client error
        }
        onUserAlreadyRegisteredError:^void(NSError * _Nonnull error) {
        // Handle client error
        }
        onClientError:^void(NSError * _Nonnull error) {
        // Handle client error
        }
     ];

Documentation

Certification

A registered user on a verified device will have a status of UNCERTIFIED.

A user can be certified in two ways depending on the accreditation level required for certification.

Accreditation level L1

If an entity is setup to allow accreditation level L1, then the user can be accredited without any formal accreditation checks i.e. they can self certify. However it is important to note that there may be restrictions on what a user with L1 certification can do.

Certify a user for accreditation level L1 as follows:

Swift3

    SDK.getClient.certifyUserAtLevelL1(
        onSuccess: {
            // Handle Certification Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onUserNotAccreditedError: { (error) in
            // Handle user not accredited error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient SDK.getClient.certifyUserAtLevelL1OnSuccess^{
            // Handle Certification Success
        }
        onNoConnection:^void() {
             // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
        }
        onUserNotAccreditedError:^void(NSError * _Nonnull error) {
            // Handle user not accredited error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

On a successful response, the user’s status will be set to CERTIFIED

NB It is highly recommended if a user has a status of UNCERTIFIED and accreditation level of L1, then the app auto certifies the user to L1 as described above.

Documentation

Accreditation level L2 and L3

Level 2 and level 3 accreditation requires that a formal accreditation process is undertaken and once completed a Digital Identity Access Code (DIAC) can be generated and sent via the post to the user.

Level 2 accreditation (known as low in the eIDAS Regulation) does not require the user to visit a checkpoint or undertake a video call in order to verify their identity, it does require that they still provide proof of their identity.

Level L3 accreditation (known as substantial in the eIDAS Regulation) requires that the user must visit a certified checkpoint or undertake a video call and go through a certification process.

Full details of the eIDAS Regulation can be found here.

NB Locations at which a user can be accredited can be retrieved using the checkpoint APIs: requestCheckpoints, requestNearestCheckpoints and requestCheckpointDetails

Once the DIAC is received the user can complete certification by entering the DIAC and calling the certifyUser API as follows:

Swift3

    SDK.getClient.certifyUser(withDiac: diacCode,
        onSuccess: {
             // Handle Certification Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token error
        }, onValidationError: { (error) in
            // Handle validation error
        }, onUserNotAccreditedError: { (error) in
            // Handle user not accredited error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient certifyUserWithDiac:diacCode
        onSuccess:^{
            // Handle Certification Success
        }
        onNoConnection:^void() {
           // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
           // Handle invalid token error
        }
        onValidationError:^void(NSError * _Nonnull error) {
            // Handle validation error
        }
        onUserNotAccreditedError:^void(NSError * _Nonnull error) {
            // Handle user not accredited error
        }
        onClientError:^void(NSError * _Nonnull error) {
           // Handle client error
        }
    ];

In the background the certifyUser process is made up of a number of steps as follows:

  1. An asymmetric key pair is created on the device.
  2. A signing request (CSR is generated, signed with the private key and sent along with the DIAC as part of the API request.
  3. If the DIAC and CSR are valid, the CSR is sent off to a Certificate Authority (CA) with a request for signing and the certifyRequest returns a success response and the user’s status is set to CERTIFICATE_PENDING.
  4. If the CA issues a signed certificate the next call to requestUser will show the user’s status has now been set CERTIFIED, and the signed certificate is retrieved and securely stored on the device.

NB If requestUser is called immediately after a request for certification and the user is successfully certified, then it likely that the request will return an InvalidTokenError error as the cached token will nolonger be valid. This can be resolved by initiating the action detailed in the resolution property of the error. See InvalidTokenError for further details.

Once certified the user will then be able to authenticate and sign documents.

Documentation