Server-side authentication with Keyri is a WebAuthn-like cryptographic flow whereby ECDSA signature verification is used to log the user in. A signed data object is sent to your server from your mobile app, routed through the Widget, and the signature is verified with the user's public key that you have stored in a database.
Keyri installation on your login page with server-side auth is broadly the same as that described in the widget quickstart (https://docs.keyri.com/browser-keyri-widget-quickstart), with the key difference being that the event listener must pass the data that it receives from the Widget along to your server for validation. Example below:
The following Node.js example demonstrates the basic backend setup required to run Keyri authentication. Simplistically, it assumes you have a database that only stores users' public keys, with each public key occupying its own row. This architecture supports multiple public keys for individual users, such as would be the case when users log into your service using multiple mobile devices. You can architect your backend setup however you would like - the only requirement for logging users in is verification of the SHA256 ECDSA signatures that the mobile app sends to your system through the Keyri mobile SDK, API, and Widget when the user scans the login QR code.
For registration, create an API endpoint that accepts the user's association key (pubKey) whenever they register a new account in your mobile app or log in to an existing account on a new mobile device.
Login is based on ECDSA signature verification. The mobile app will send four pieces of data:
- pubKey: The user's device-specific ECDSA public key in base64
- username: The user's non-cryptographic identifier
- data: Timestamp_nonce
- signature: The ECDSA signature, a SHA256 digest, of the data
Please refer to the Mobile SDK documentation for a full description of installation and configuration.
The goal with registration is to make sure that the user's public key present on their phone is also present in your database.
Given that keys are not necessarily synced across all of a user's devices, you should go through the "registration" flow when users log into existing accounts on their phones as well as when they create new accounts. As a result, your database will likely include multiple public keys for the same user - one for each of their devices.
Please use the following methods of the mobile SDK to complete the registration process:
- getAssociationKey(publicUserId: String): This will either retrieve the public key for a given user or indicate that a public key for that user does not exist on that specific device.
- generateAssociationKey(publicUserId: String): Use this to generate a new key pair for the user, followed by getAssociationKey() to return the public key as a string. Once you have the public key string, POST it to the registration endpoint you created on your backend in conjunction with the user's public id / username.
Login refers to the stage at which a user who is logged into your app on their mobile device scans a Keyri QR code to log in on the device on which the QR code is displayed. You can use methods like easyKeyriAuth(), initializeQrSession(), or processLink() to complete the login process. Note that the four data items listed in the backend login endpoint above (and reproduced below) are strictly necessary to include in the payload.
- pubKey: Retrieve this using getAssociationKey(publicUserId: String)
- username: This is simply the public user ID with which the public key is associated
- data: This is the current Unix epoch and a random number, concatenated with an underscore in between
- signature: Generate the signature with getUserSignature(publicUserId: String, data: String), which data being the timestamp_nonce listed above