Build Server-Side Endpoints

OwnID provides templates for the three request handlers you’ll host on your web server. These form the endpoints called from the OwnID platform, using signed HTTP requests.

These endpoints provide the connection between OwnId and your server for exchange user authentication data. That data is what you save in the ownIdData field you created in your database user table.

​

Add Web Server Request Handlers

Below are code templates for each of the three request handlers needed to implement your server-side endpoints:

• Set OwnIdData - setOwnIDDataByLoginId

• Get OwnIdData - getOwnIDDataByLoginId

• Get Session - getSessionByLoginId

When the OwnID server receives a login event from your frontend, it then makes the appropriate HTTP requests to these endpoints.

The user’s login id (typically the user’s email address) is the unique identifier used to look up and save records in the ownIdData field.

Select the tab matching your server-side language in the sample templates below.

​

Endpoint 1 - Set OwnIdData

This endpoint handles a request to save an ownIdData record for a given loginId when the user enrolls a new device. This is the VARCHAR field you created previously. It holds the public key of the device used for biometric authentication.

router.post('/setOwnIDDataByLoginId', async (req, res) => {
    const email = req.body.loginId; //The unique id of a user in your database, usually email or phone
    const ownIdData = req.body.ownIdData; //OwnID authentication information as string
    const user = await User.findOne({ email: email }).exec();
    user.ownIdData = ownIdData;
    await user.save();
    return res.sendStatus(204);
}

Response
Implement these responses for setOwnIDDataByLoginId:

Example:

{}

​

Endpoint 2 - Get OwnIdData

This endpoint handles a request to fetch an ownIdData record for a given user’s login id.

router.post('/getOwnIDDataByLoginId', async (req, res) => {
    const email = req.body.loginId; // The unique id of a user in your database, usually email or phone
    
    try {
        const user = await User.findOne({ email: email }).exec();
        
        if (!user) {
            // User not found
            return res.status(404).send();
        }
        
        if (user.ownIdData) {
            // User found and has ownIdData
            return res.status(200).json({ ownIdData: user.ownIdData });
        } else {
            // User found but doesn't have ownIdData
            return res.status(204).send();
        }
    } catch (error) {
        console.error('Error fetching user:', error);
        return res.status(500).json({ error: 'Internal server error' });
    }
});

Response

Implement these responses for getOwnIDDataByLoginId:

Examples:

{
  "ownIdData": "<String>"
}

​

Endpoint 3 - Get Session

Handle a request to fetch a token for the current session by user’s email address.

Note that token is a unique session identifier that you generate. OwnID does not validate or use the token in any way, it merely passes the token back to you so you can identify the session it’s associated with.

Later, we’ll see how the OwnID login event returns this value in the frontend to establish a client session.

router.post('/getSessionByLoginId', async (req, res) => {
    const sign = require('jwt-encode');
    const email = req.body.loginId; //The unique id of a user in your database, usually email or phone
    const user = await User.findOne({ email: email }).exec();
    const jwt = sign({ email: user.email }, 'secret');
    return res.json({ token: jwt });
});

Response

Implement these responses for getSessionByLoginId:

Example:

{
  "token": "<String>"
}

​

Secure Your Endpoints

Requests from the OwnID server include two headers that can be used to ensure the request has not been tampered with. The first one, ownid-signature, is a hash value that the OwnID server generates from a timestamp and the body of the request. The second one, ownid-timestamp can be used by your backend to calculate the signature that is based on the timestamp and request body, and then compare the result to the value of ownid-signature. If both signatures do not match, the request has been altered.

Because the signatures are generated using an HMAC with the SHA256 hash function, the OwnID server and your backend must use the same cryptographic key when calculating the hash value. You can obtain this key from the OwnID Console, and then add the code generates a hash and compares it to the signature in your backend.

Obtaining the HMAC Key

Before the backend can generate the HMACSHA256 value, you must obtain the secret cryptographic key used in the calculation. Simply open your OwnID application in the OwnID Console and copy the value from MyApp > Shared Secret.

Request Verification

Now that you have the cryptographic key, the backend can verify requests by generating each request’s expected signature and compare it to the one generated by the OwnID server. The backend code must:

• Step 1: Extract the ownid-signature and ownid-timestamp headers from the request. These headers provide the HMAC code generated by the OwnID server and the timestamp it used to generate it.

• Step 2: Validate the ownid-timestamp for expiration. To prevent replay attacks, check whether the provided timestamp is within an acceptable time window. Define a preferred expiration time, such as 1 minute, and validate against the current time. Requests with a timestamp older than this period should be rejected.

• Step 3: Create the data string that will be used as an input to the hash function. To create it you need to concatenate:

  • The request body (in a JSON string format)
  • The character .
  • The timestamp (from the ownid-timestamp header)

• Step 4: Use HMAC with SHA256 to calculate a hashed value from the body-timestamp data string. The cryptographic key used in the calculation is the shared secret for your OwnID application.

• Step 5: Compare the hash value generated by your backend with the signature extracted from the ownid-signature header.

The following code snippets show how the backend might accomplish these steps:

const crypto = require('crypto');

// Step 1: Extract values from headers and request body
let key = "<your-shared-secret>"; // This is the shared secret from OwnID Console
let keyBuffer = Buffer.from(key, 'base64');
let body = JSON.stringify(req.body);
let ownIdSignature = req.headers['ownid-signature'];
let ownIdTimestamp = req.headers['ownid-timestamp'];
let dataToSign = `${body}.${ownIdTimestamp}`;

// Step 2: Validate the `ownid-timestamp` for expiration
const expirationTimeInMilliseconds = 60 * 1000; 
const currentTime = Date.now(); /
const ownIdTimestampMs = parseInt(ownIdTimestamp);

if (Math.abs(currentTime - ownIdTimestampMs) > expirationTimeInMilliseconds) {
    // The timestamp has expired
    throw new Error("Request rejected: Signature has expired.");
}

// Step 3: Generate HMAC signature
const hmac = crypto.createHmac('sha256', keyBuffer);
hmac.update(dataToSign);
let signature = hmac.digest('base64');

// Step 4: Compare the generated signature with the one from the header
if (signature !== ownIdSignature) {
    // The request has been tampered with
    throw new Error("Request rejected: Invalid signature.");
}

​

Next Steps

With the request handlers in place, you’re ready to build the frontend integrations for login, registration, account recovery, and more.