Authenticate UIKit to call IQL Backend APIs

The traditional way for the UIKit to correspond with Zendrive's backend is to relay those API calls via the proxy layer implemented by customers in their backend. We have devised a new mechanism that avoids this expensive setup by implementing one backend API alone that serves as a means to source an end user's identity to the UIKit. UIKit can then correspond with Zendrive's backend APIs directly by anchoring trust to this identity provided by our customer's backend. This API is required to generate an identification token - scoped to each individual end user - and pass it back to their application in response to user login or heartbeat API call.

In this section, we discuss how to authenticate UIKit to uniquely identify users so that UIKit can call Zendrive's IQL Backend APIs in a secure fashion. This is done through generation of an identification token that the app shares with UIKit.

If you implement this authentication, you no longer need to implement a proxy layer in your backend. Hence you can skip completely.

Identification Token Flow

1. Generating Identification Token

• A new token, identification_token is introduced to facilitate user identification.

• This token must be generated by the client’s backend system in response to the API call using an identity key , identity key id, and driver_id. Customers can choose to create expiring identification_tokens by adding an expiry timestamp and setting identity_v1 as the token's version. This will set the token's expiry to the timestamp (in UTC epoch seconds). Zendrive's backend APIs will not honour an identification_token beyond its expiry timestamp. Alternatively, for customers that do not wish for identification_tokens to expire can generate tokens by prefixing identity_v2 as the token's version and pass the token generation timestamp instead of an expiry timestamp. The downside of this approach is that identification_tokens remain valid forever or until the identity_key used to generate the token is invalidated. For more details on both the versions, see Identification Token Generation Code.

To get the identity key and identity key id, contact Zendrive support.

It is critical that the identification_token generation happen outside of the client app, ideally within the backend of the app. We do not recommend generating it within the app, as this could leak the identity_key to attackers, thereby allowing identity spoofing.

2. Registration Process

• The UIKit initially registers a user by passing the identification_token to the backend.

• The backend validates the identification_token and responds by sharing an access_token with the UIKit.

For more information, see .

3. Subsequent API Calls

• The UIKit utilizes the received access_token for authentication in all subsequent API calls to Zendrive’s servers.

Identification Token Generation Code

Expiring token generation

Python

import base64
import hmac
import hashlib
import time


def generate_identification_token():
    driver_id = "your_driver_id"
    identity_key_id = "your_identity_key_id"
    identity_key = "your_identity_key"
    expiry_timestamp = "your_expiry_timestamp_in_millis"

    plaintext = "userID=" + driver_id + "\n" + "keyID=" + identity_key_id + "\n" + "expiry=" + expiry_timestamp
    generated_id_token = base64.b64encode(
        hmac.new(identity_key.encode('utf-8'), plaintext.encode('utf-8'), hashlib.sha256).digest()).decode('utf-8')

    identification_token_text = "identity_v1\nid_token=" + generated_id_token + "\nkeyID=" + identity_key_id + "\nexpiry=" + expiry_timestamp
    identification_token = base64.b64encode(identification_token_text.encode('utf-8')).decode('utf-8')

    return identification_token

Java

import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static String generateIdentificationToken() throws NoSuchAlgorithmException, InvalidKeyException {
    String driverId = "your_driver_id";
    String identityKeyId = "your_identity_key_id";
    String identityKey = "your_identity_key";
    String expiryTimestamp = "your_expiry_timestamp_in_millis";

    String plaintext = "userID=" + driverId + "\n" + "keyID=" + identityKeyId + "\n" + "expiry=" + expiryTimestamp;

    Mac hmacSha256 = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(identityKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    hmacSha256.init(secretKey);
    byte[] hashedBytes = hmacSha256.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));

    String generatedIdToken = Base64.getEncoder().encodeToString(hashedBytes);

    String identificationTokenText = "identity_v1\nid_token=" + generatedIdToken + "\nkeyID=" + identityKeyId + "\nexpiry=" + expiryTimestamp;
    String finalIdentificationToken = Base64.getEncoder().encodeToString(identificationTokenText.getBytes(StandardCharsets.UTF_8));

    return finalIdentificationToken;
}

CSharp

using System;
using System.Security.Cryptography;
using System.Text;

public static string GenerateIdentificationToken()
{
    string driverId = "your_driver_id";
    string identityKeyId = "your_identity_key_id";
    string identityKey = "your_identity_key";
    string expiryTimestamp = "your_expiry_timestamp_in_millis";

    string plaintext = $"userID={driverId}\nkeyID={identityKeyId}\nexpiry={expiryTimestamp}";

    byte[] key = Encoding.UTF8.GetBytes(identityKey);
    byte[] plaintextBytes = Encoding.UTF8.GetBytes(plaintext);

    using (HMACSHA256 hmac = new HMACSHA256(key))
    {
        byte[] hashedBytes = hmac.ComputeHash(plaintextBytes);
        string generatedIdToken = Convert.ToBase64String(hashedBytes);

        string identificationTokenText = $"identity_v1\nid_token={generatedIdToken}\nkeyID={identityKeyId}\nexpiry={expiryTimestamp}";
        byte[] identificationTokenTextBytes = Encoding.UTF8.GetBytes(identificationTokenText);
        string finalIdentificationToken = Convert.ToBase64String(identificationTokenTextBytes);

        return finalIdentificationToken;
    }
}

JavaScript

const crypto = require('crypto');

function generateIdentificationToken() {
    const driverId = "your_driver_id";
    const identityKeyId = "your_identity_key_id";
    const identityKey = "your_identity_key";
    const expiryTimestamp = "your_expiry_timestamp_in_millis";

    const plaintext = `userID=${driverId}\nkeyID=${identityKeyId}\nexpiry=${expiryTimestamp}`;

    const hmacSha256 = crypto.createHmac('sha256', identityKey);
    hmacSha256.update(plaintext);
    const hashedBytes = hmacSha256.digest();

    const generatedIdToken = Buffer.from(hashedBytes).toString('base64');

    const identificationTokenText = `identity_v1\nid_token=${generatedIdToken}\nkeyID=${identityKeyId}\nexpiry=${expiryTimestamp}`;
    const finalIdentificationToken = Buffer.from(identificationTokenText).toString('base64');

    return finalIdentificationToken;
}

Go

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "strconv"
    "time"
)

func generateIdentificationToken() string {
    driverId := "your_driver_id"
    identityKeyId := "your_identity_key_id"
    identityKey := "your_identity_key"
    expiryTimestamp := "your_expiry_timestamp_in_millis";

    plaintext := "userID=" + driverId + "\n" + "keyID=" + identityKeyId + "\n" + "expiry=" + expiryTimestamp

    key := []byte(identityKey)
    h := hmac.New(sha256.New, key)
    h.Write([]byte(plaintext))
    hashedBytes := h.Sum(nil)

    generatedIdToken := base64.StdEncoding.EncodeToString(hashedBytes)

    identificationTokenText := "identity_v1\nid_token=" + generatedIdToken + "\nkeyID=" + identityKeyId + "\nexpiry=" + expiryTimestamp
    finalIdentificationToken := base64.StdEncoding.EncodeToString([]byte(identificationTokenText))

    return finalIdentificationToken
}

Non-Expiring token generation

Python

import base64
import hmac
import hashlib
import time


def generate_identification_token():
    driver_id = "your_driver_id"
    identity_key_id = "your_identity_key_id"
    identity_key = "your_identity_key"
    current_timestamp = str(int(time.time()) * 1000)

    plaintext = "userID=" + driver_id + "\n" + "keyID=" + identity_key_id + "\n" + "timestamp=" + current_timestamp
    generated_id_token = base64.b64encode(
        hmac.new(identity_key.encode('utf-8'), plaintext.encode('utf-8'), hashlib.sha256).digest()).decode('utf-8')

    identification_token_text = "identity_v2\nid_token=" + generated_id_token + "\nkeyID=" + identity_key_id + "\ntimestamp=" + current_timestamp
    identification_token = base64.b64encode(identification_token_text.encode('utf-8')).decode('utf-8')

    return identification_token

Java

import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static String generateIdentificationToken() throws NoSuchAlgorithmException, InvalidKeyException {
    String driverId = "your_driver_id";
    String identityKeyId = "your_identity_key_id";
    String identityKey = "your_identity_key";
    String currentTimestamp = String.valueOf(System.currentTimeMillis());

    String plaintext = "userID=" + driverId + "\n" + "keyID=" + identityKeyId + "\n" + "timestamp=" + currentTimestamp;

    Mac hmacSha256 = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKey = new SecretKeySpec(identityKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    hmacSha256.init(secretKey);
    byte[] hashedBytes = hmacSha256.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));

    String generatedIdToken = Base64.getEncoder().encodeToString(hashedBytes);

    String identificationTokenText = "identity_v2\nid_token=" + generatedIdToken + "\nkeyID=" + identityKeyId + "\ntimestamp=" + currentTimestamp;
    String finalIdentificationToken = Base64.getEncoder().encodeToString(identificationTokenText.getBytes(StandardCharsets.UTF_8));

    return finalIdentificationToken;
}

CSharp

using System;
using System.Security.Cryptography;
using System.Text;

public static string GenerateIdentificationToken()
{
    string driverId = "your_driver_id";
    string identityKeyId = "your_identity_key_id";
    string identityKey = "your_identity_key";
    string currentTimestamp = DateTimeOffset.Now.ToUnixTimeMilliseconds().ToString();

    string plaintext = $"userID={driverId}\nkeyID={identityKeyId}\ntimestamp={currentTimestamp}";

    byte[] key = Encoding.UTF8.GetBytes(identityKey);
    byte[] plaintextBytes = Encoding.UTF8.GetBytes(plaintext);

    using (HMACSHA256 hmac = new HMACSHA256(key))
    {
        byte[] hashedBytes = hmac.ComputeHash(plaintextBytes);
        string generatedIdToken = Convert.ToBase64String(hashedBytes);

        string identificationTokenText = $"identity_v2\nid_token={generatedIdToken}\nkeyID={identityKeyId}\ntimestamp={currentTimestamp}";
        byte[] identificationTokenTextBytes = Encoding.UTF8.GetBytes(identificationTokenText);
        string finalIdentificationToken = Convert.ToBase64String(identificationTokenTextBytes);

        return finalIdentificationToken;
    }
}

JavaScript

const crypto = require('crypto');

function generateIdentificationToken() {
    const driverId = "your_driver_id";
    const identityKeyId = "your_identity_key_id";
    const identityKey = "your_identity_key";
    const currentTimestamp = Date.now().toString();

    const plaintext = `userID=${driverId}\nkeyID=${identityKeyId}\ntimestamp=${currentTimestamp}`;

    const hmacSha256 = crypto.createHmac('sha256', identityKey);
    hmacSha256.update(plaintext);
    const hashedBytes = hmacSha256.digest();

    const generatedIdToken = Buffer.from(hashedBytes).toString('base64');

    const identificationTokenText = `identity_v2\nid_token=${generatedIdToken}\nkeyID=${identityKeyId}\ntimestamp=${currentTimestamp}`;
    const finalIdentificationToken = Buffer.from(identificationTokenText).toString('base64');

    return finalIdentificationToken;
}

Go

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "strconv"
    "time"
)

func generateIdentificationToken() string {
    driverId := "your_driver_id"
    identityKeyId := "your_identity_key_id"
    identityKey := "your_identity_key"
    currentTimestamp := strconv.FormatInt(time.Now().UnixNano()/int64(time.Millisecond), 10)

    plaintext := "userID=" + driverId + "\n" + "keyID=" + identityKeyId + "\n" + "timestamp=" + currentTimestamp

    key := []byte(identityKey)
    h := hmac.New(sha256.New, key)
    h.Write([]byte(plaintext))
    hashedBytes := h.Sum(nil)

    generatedIdToken := base64.StdEncoding.EncodeToString(hashedBytes)

    identificationTokenText := "identity_v2\nid_token=" + generatedIdToken + "\nkeyID=" + identityKeyId + "\ntimestamp=" + currentTimestamp
    finalIdentificationToken := base64.StdEncoding.EncodeToString([]byte(identificationTokenText))

    return finalIdentificationToken
}