JWT Enrolment

This is a generic mechanism that can be used whenever the user was already validated in a previous step. If the user is already known (was validated on the mobile app through credentials, was just enrolled in the system through a self-service), biometric information can be attached to that identity. This identity can be sent to the VeridiumID server through a JWT message signed with a predefined public-private key pair properly setup on the integration server and the VeridiumID server.

The Integration server needs to generate a JWT message using user identity from its data store. The minimum requirement is that the token contains the sub claim with a unique value that can be used to identify the user, iss (issuer), aud (audience) and exp (expiration time - ms epoch time System time ). The sub value will be saved as a user primary key in the VeridiumID database. The signature is done with a chosen private key.

Other attributes read by Veridium are name, email and phone_number.

JWT Token Generation

To generate a JWT token jwt.io can be used. Default pub - priv from jwt.io can be used for testing, for private environments custom crypto pair should be used. First use these commands to generate the necessary crypto information (pub-priv keys used for signing).

CODE

openssl genrsa -out key.pem 2048
openssl rsa -in key.pem -outform PEM -pubout -out pubkey.pem
base64 pubkey.pem > pubkey.pem.b64

Paste the content of pubkey.pem and key.pem in the appropriate jwt.io fields, choose RS256 as signing algorithm and fill in the JWT payload:

Payload Data :
- sub - subject
- iss - issuer
- aud - audience
- exp - expiry time System time
- iat - issued at System time
Example: { "sub": "userId", "iss": "generic@veridiumid.com", "aud": "VeridiumID", "exp": 1657631390, "iat": 1619184075 }

The resulting JWT can be used as input for the JWT Enrollment step in VeridiumID.c

Alternatives for generating Pub-Priv pairs:

certificate generation / extraction

CODE

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes

openssl x509 -pubkey -noout -in cert.pem > pubkey.pem

openssl x509 -outform der -in cert.pem -out cert.der

base64 cert.pem > cert.b64

Eliptic Curve keys

CODE

openssl ecparam -name prime256v1 -genkey -noout -out key.pem

openssl ec -in key.pem -pubout -out pubkey.pem

base64 pubkey.pem > pubkey.pem.b64

Admin Dashboard Configuration

In the Admin Dashboard two actions are required to enable the JWT enrolment:

Choose JWT Enrolment step in the corresponding Integration’s details page. Edit the Jwt Enrollment step, navigate to 'Options' tab and set the issuer to the value configured in JWT above.
Setup the integration to have Desktop Biometry as Server side only (for Kiosk)
Policy should have “Has Desktop Touch Id Biometry” set to TRUE (for Kiosk)
Create a journey with 4F Browser biometry ONLY. To make authentications with it, if it is not the only journey, the default selector can have a transition with the condition 'input.session.exploiterDeviceContext.serviceIdentifier == null'
Setup the corresponding Public Key to be used for JWT validation under Configuration->adaptors->jwt.config.json. The Public key must be base64 encoded PEM (e.g. the cert.pem or pubkey.pem.b64 generated above). Also the config json needs to contain the audience and issuer expected claims values.

With these settings in place the VeridiumID server is capable of validating the JWT claims, extract necessary information for user creation and return a result back to the caller.

NOTE

Starting 3.2 server version the supported PublicKey formats are Public keys (RSA or EC) in PEM format or Certificates with public key in PEM format. Until that version only Certificate format wes accepted.

Mobile calls

The JWT message can be requested explicitly by the Mobile app or passed as a registration response from the Integration server. The Mobile app will then call the MobileSDK enroll() API call with this value passed in the userEnrollmentToken parameter.

iOS

CODE

VIDMobileSDK.shared().enrollDelegate = self
let config = VIDEnrollmentConfig()
let jwt_msg = "<insert jwt_token>"
config.userEnrollmentToken = "{\"JWT\":\"\(jwt_msg)\"}"
VIDMobileSDK.shared().enroll(config: config)

Android

CODE

String userToken = "{\"JWT\": \"<jwt_msg>\"}";
VeridiumIdPendingIntent pendingIntent = VeridiumMobileSDK.getInstance().enroll(BuildConfig.VERIDIUMID_SERVER_PAIRING_TOKEN, null);
if (pendingIntent.hasPendingIntent()) {
  try {
    pendingIntent.launchPendingIntent(getActivity(), MainActivity.RC_ENROLL);
  } catch (IntentSender.SendIntentException e) {
    e.printStackTrace();
    }
}