Full Stack Integration

With a full stack integration it is possible to gain all of the benefits of OwnID even if your website uses an identity platform that does not have a pre-built OwnID integration. In a full stack integration, the OwnID server communicates with your website's server by sending requests to a set of API endpoints that have been added by your team. This article provides the specification for these APIs, allowing you to build the endpoints that are accessed by the OwnID server.

In a full stack integration, you will:

• Build API endpoints into your backend
• Create an OwnID application
• Integrate the OwnID widget into your frontend

Step 1: Create Database Field

The OwnID server uses an ownIdData object to store OwnID authentication information in a website's database. The structure of this String is unimportant to the website's backend --- the backend just needs to include a database field that stores the JSON blob when it is received from the OwnID server and be able to retrieve it when the OwnID server requires it.

If your database requires you to create a field before storing the ownIdData object that is received from the OwnID server, do it now. For a relational database (RDBMS), be sure the field meets the following requirements:

• A character datatype e.g., VARCHAR
• A minimum length of 5000 chars

Step 2: Build Endpoints

OwnID requires your endpoints to conform to the following specifications. These endpoints must share a common base URL that is unique.

POST /setOwnIDDataByLoginId

As a user interacts with OwnID, the OwnID server sends a POST /setOwnIDDataByLoginId request to store authentication data in the website's backend. When the backend receives this request, it must associate the specified user with the authentication data (ownIdData) and a lookup field for that data (loginId) so the OwnID server can retrieve the data with future API calls. As an example, when a website's backend receives the following request it must associate the user identified by sol@testmail.com with the provided OwnID authentication data.

curl --location --request POST 'https://bazco.company/setOwnIDDataByLoginId/' \

--header 'Content-Type: application/json' \

--data-raw '{

"loginId": "sol@testmail.com",

"ownIdData":"<String>"

}'

Request Parameters

When the OwnID server sends a POST /setOwnIDDataByLoginId request, it encodes parameters as JSON with a Content-Type of application/json. The following parameters must be supported:

Parameter	Type	Is required?	Description
loginId	string	True	The unique identifier of a user in the database, usually email or phone.
ownIdData	string	True	The OwnID authentication data object.

Expected Response

If the website's backend successfully receives and processes the POST /setOwnIDDataByLoginId request, it should return a 204 HTTP status code with an empty response body.

{ }

Code Example

NodeJS

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);

});

Python

@app.route('/ownid/setOwnIDDataByLoginId', methods=['POST'])

def set_ownid_data_by_login_id():

data = request.get_json()

login_id = data['loginId']

ownid_data = data['ownIdData']

user = db.session.query(Users).filter(Users.email == login_id).first()

user.ownid_data = ownid_data

user.save()

return ('', 204)

Java

@PostMapping("/setOwnIDDataByLoginId")

public ResponseEntity <Object> setOwnIdDataByLoginId(@RequestBody OwnIDData req) {

User user = userRepository.findByLoginId(req.getLoginId());

user.setOwnIdData(data);

userRepository.save(user);

return ResponseEntity.status(HttpStatus.NO_CONTENT).body(null);

}

C#

[HttpPost("setOwnIDDataByLoginId")]

public async Task<ActionResult<Object>> SetOwnIdDataByLoginId(string loginId, string ownIdData)

{

var user = _userRepository.Instance.Get(loginId);

user.ownIdData = ownIdData;

_userRepository.Instance.Update(user);

return NoContent();

}

POST /getOwnIDDataByLoginId

OwnID sends a POST /getOwnIDDataByLoginId request to retrieve OwnID authentication data about a user. The request finds the user within the identify platform based on the user's loginId, which is usually the user's email or phone number. This loginId uniquely identifies the user within the database. For example, the following request should retrieve the OwnID authentication data about a user whose unique identifier is an email address:

curl --location --request POST 'https://bazco.company/getOwnIDDataByLoginId' \

--header 'Content-Type: application/json' \

--data-raw '{

"loginId":"sol@testmail.com"

}'

Request Parameters

When the OwnID server sends a POST /getOwnIDDataByLoginId request, it encodes parameters as JSON with a Content-Type of application/json. The following parameter must be supported:

Parameter	Type	Is required?	Description
loginId	string	True	The unique identifier of a user in the database, usually email or phone.

Expected Response

When the OwnID server makes a POST /getOwnIDDataByLoginId request, it expects to receive back the ownIdData object that was stored in the website's database the last time the OwnID server made a POST /setOwnIdDataByLoginId request. This response has the following structure:

{

"ownIdData": "<String>"

}

If the user exists but doesn't have the ownIdData object (this is the use case of an existing user going passwordless for the first time), we expect a response with an empty ownIdData:

{

"ownIdData": ""

}

Error handling when user doesn't exist

When the user (loginID) doesn't exist in your database, you must return a standard HTTP code with the following response body:

{

"errorCode": 404,

"errorMessage": "User not found"

}

Code Example

NodeJS

router.post('/getOwnIDDataByLoginId', async (req, res) => {

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();

if (!user) { return res.json({ errorCode: 404 }) } //Error code when user doesn't exist

res.json({ ownIdData: user.ownIdData }) //OwnID authentication information as string

});

Python

@app.route('/ownid/getOwnIDDataByLoginId', methods=['POST'])

def get_ownid_data_by_login_id():

data = request.get_json()

login_id = data['loginId']

user = db.session.query(Users).filter(Users.email == login_id).first()

if not user:

return jsonify({'errorCode': 404})

return jsonify({'ownidData': user.ownid_data})

Java

@PostMapping("/getOwnIDDataByLoginId")

public ResponseEntity<Object> getOwnIdDataByLoginId(@RequestBody OwnIDSearchRequest req) {

User user = userRepository.findByLoginId(req.getLoginId());

if (user == null) {

return ResponseEntity.status(HttpStatus.OK).

body(new OwnIdErrorResponse(HttpStatus.NOT_FOUND, "User not found"));

}

return ResponseEntity.status(HttpStatus.OK).body(new OwnIDDataResponse(user.getOwnIdData()));

}

C#

[HttpPost("getOwnIDDataByLoginId")]

public async Task<ActionResult<Object>> GetOwnIDDataByLoginId(string loginId)

{

var user = _userRepository.Instance.Get(loginId);

if (user == null)

return Ok(new { ErrorCode = HttpStatusCode.NotFound, ErrorMessage = "User not found" });

return Ok(new { OwnIdData = user.OwnIdData });

}

POST /getSessionByLoginId

The OwnID servers sends a POST /getSessionByLoginId request after the user has successfully logged in with OwnID. The backend receiving the request is expected to return a JSON object that will be used to authenticate the user on the client side. Often times, the backend returns a JWT for this purpose, but it can also be an arbitrary JSON string. Once it receives the JSON object, the OwnID server passes it to the client-side app using a JavaScript event.

curl --location --request POST 'https://bazco.company/getSessionByLoginId' \

--header 'Content-Type: application/json' \

--data-raw '{

"loginId":"sol@testmail.com",

}'

Request Parameters

When the OwnID server sends a POST /getSessionByLoginId request, it encodes parameters as JSON with a Content-Type of application/json. The following parameters must be supported:

Parameter	Type	Is required?	Description
loginId	string	True	The unique identifier of a user in the database, usually email or phone.

Expected Response

When the OwnID makes a POST /getSessionByLoginId request, it expects to receive back a response with the following structure, where token is a JSON object, often a JWT:

{

"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

}

Code Example

NodeJS

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 });

});

Python

@app.route('/ownid/getSessionByLoginId', methods=['POST'])

def get_session_by_login_id():

data = request.get_json()

login_id = data['loginId']

user = db.session.query(Users).filter(Users.email == login_id).first()

token = jwt.encode({

'userId': str(user.email), 'exp': datetime.datetime.utcnow() + datetime.timedelta(hours=3)},

app.config['SECRET_KEY'],

"HS256")

return jsonify({'token': token})

Java

@PostMapping("/getSessionByLoginId")

public ResponseEntity<OwnIDSessionResponse> getSessionByLoginId(@RequestBody OwnIDSearchRequest req) {

User user = userRepository.findByLoginId(req.getLoginId());

Algorithm alg = Algorithm.HMAC256("secret");

String token = JWT.create().

withClaim("loginId", req.getLoginId()).

sign(alg);

return ResponseEntity.status(HttpStatus.OK).body(new OwnIDSessionResponse(token));

}

C#

[HttpPost("getSessionByLoginId")]

public async Task<ActionResult<OwnIDSessionResponse>> GetSessionByLoginId(string loginId)

{

var user = _userRepository.Instance.Get(loginId);

var hashObject = new HMACSHA256(Encoding.UTF8.GetBytes("secret"));

var signature = hashObject.ComputeHash(Encoding.UTF8.GetBytes(user.LoginId));

var encodedSignature = Convert.ToBase64String(signature);

return Ok(new OwnIDSessionResponse() { Token = encodedSignature });

}

Step 3: Create OwnID Application

Each website integrating with OwnID must have an OwnID application. To create an OwnID application:

1. Open the OwnID Console and create an account or log in to an existing account.
2. Select Create Application.
3. Select the language you are using to build the endpoints required by the OwnID server.
4. Confirm that you have built the API endpoints by selecting Next.
5. Enter the base URL that is shared by the API endpoints.
6. Select your frontend framework and complete the integration steps. These steps are discussed below in more detail.

Step 4: Add OwnID to Your Frontend

Installing the OwnID SDK

If a website uses a framework like Angular or ReactJS, it must install the OwnID SDK before adding the OwnID widget to its registration and login flows. To install the OwnID SDK for a framework, use the CLI to run:

ReactJS

npm install @ownid/react

or

yarn add @ownid/react

Angular

npm install @ownid/angular

or

yarn add @ownid/angular

Initializing the OwnID SDK

Regardless of whether a website is using a framework or javascript, the OwnID SDK needs to be included and initialized with the appId of the website's OwnID application. This unique appId can be obtained by opening the application in the OwnID Console.

ReactJS

Import the OwnIDInit component to your App component and configure it with your appId:

import { OwnIDInit } from '@ownid/react';

...

<OwnIDInit config={{appId:'9s8d7f9s87g98s7dgMyAppID'}}/>

Angular

Import the OwnIDInit component to your App component and configure it with your appId:

...

import { OwnidAngularModule } from '@ownid/angular';

...

@NgModule({

...

imports: [

...

OwnidAngularModule.forRoot({appId:'s9d8f7s98f79s87dfMyAppID'}),

...

]})

JavaScript

Place the following code in the head of the registration or login page to include and initialize the SDK.

<script>

((o,w,n,i,d)=>{o[i]=o[i]||(async(...a)=>((o[i].q=o[i].q||[]).push(a),{error:null,data:null})),

(d=w.createElement("script")).src='https://cdn.ownid.com/sdk/'+n,d.async=1,w.head.appendChild(d)})

(window,document,'<appID>','ownid');

</script>

Tip: You can customize the appearance of the OwnID widget using advanced initialization parameters. For details, see Customizing the UI.

Registration Page

Allowing users to register with OwnID involves frontend integration along with a modification to how your backend handles the user's information when they submit their registration details.

Frontend Modifications: As you modify your website's frontend to integrate OwnID into the registration page, you will:

• Render the OwnID widget by adding it to your form.
• Define a variable to store the OwnID authentication payload returned by the onRegister function. This payload is an ownIdData object.
• Modify the function that is executed when the registration form is submitted (for example, onSubmit) so it adds the ownIdData object to the user's registration data.

ReactJS

Add references to required elements, define onRegister function, and modify the function that is called when the form is submitted:

function RegisterComponent() {

const emailField = useRef(null);

const passwordField = useRef(null);

const [ownIdDataString, setOwnIDData] = useState(null);

// Stores ownIdData

function onRegister(ownIdData) {

setOwnIDData(ownIdDataString);

}

function onSubmit(userData) {

// Call your existing registration logic in the backend

return register({ …userData, ownIdData: ownIdDataString});

}

return (

<form onSubmit={onSubmit}>

<input ref={emailField} type="email" name="email" />

<input ref={passwordField} type="password" name="password" />

<button type="submit">Register</button>

<OwnID type={'register'}

loginIdField={email.current}

passwordField={password.current}

options={{variant: 'button-fingerprint', infoTooltip:true}}

onError={(error) => console.error(error)}

onRegister={onRegister} />

</form>

);

}

Angular

First, add the ownid component to the HTML template of the registration page:

<form #myForm="ngForm" (ngSubmit)="onSubmit()">

<input #emailField type="email">

<input #passwordField type="password">

<ownid type="register"

(onRegister)="onRegister($event)"

[loginIdField]="emailField"

[passwordField]="passwordField"

[options]="{variant: 'button-fingerprint', infoTooltip:true}">

</ownid>

<button type="submit">Register</button>

</form>

Next, add a onRegister callback to the js file of the registration page, storing ownIdDate in your app storage (e.g., a variable at component scope):

onRegister(ownIdData) {

this.ownIdDataString = ownIdData;

}

Finally, modify the function that is executed when the registration form is submitted (for example, onSubmit) so it adds the OwnID payload to the user's registration data.

onSubmit(userData) {

//Call your existing registration logic in the backend

return register({ …userData, ownIdData: ownIdDataString});

}

JavaScript

Once the registration page loads and initializes the OwnID SDK, it uses the following code to render the OwnID widget and register the user:

<body>

<form name="myForm" onsubmit="return onSubmit()">

<input id="email" type="text" name="email">

<input id="password" type="text" name="password">

<input type="submit" value="Submit">

</form>

<script>

var ownIdDataString;

function onSubmit(userData) {

//Call your existing registration logic in the backend

return register({ …userData, ownIdData: ownIdDataString});

}

ownid("register", {

passwordField: document.getElementById("password"),

loginIdField: document.getElementById("email"),

variant: "button-fingerprint",

infoTooltip:true,

onError: (error) => console.log(error),

onRegister: (ownIdData) => ownIdDataString = ownIdData,

});

</script>

</body>

Backend Modifications: When the user submits their registration details, your onSubmit function eventually calls a method in the backend that completes the registration. You must modify this backend registration logic so it stores the ownIdData field of the userData object into the database field designed for this purpose. This is the same database field used to store ownIdData objects sent from the OwnID server to the backend's /setOwnIDDataByLoginId endpoint.

Login Page

Adding the OwnID widget to a login page allows users who have registered with OwnID to log into the website. The widget's onLogin function, which is triggered when the user logs in with OwnID, returns an object that is used to set the session in the frontend. It is the same object that was sent from your backend to the OwnID server in response to a /getSessionByLoginId request. Since your backend determines what object was sent to the OwnID server, your frontend code knows what object it is receiving from the onLogin function. This object can be a JWT, but can also be an arbitrary string generated by your backend. In addition to setting the session, the onLogin function should redirect the user to an authorized page (e.g., a profile page).

Add the following code to render the login widget:

ReactJS

Add references to elements and define the widget's onLogin function:

function LoginComponent() {

const emailField = useRef(null);

const passwordField = useRef(null);

function onLogin(data) {

//setting user session

localStorage.setItem('data', JSON.stringify({ token: data.token }));

//redirecting user to the account page

window.location.href = '/account';

}

return (

<form>

<input ref={emailField} type="email" name="email" />

<input ref={passwordField} type="password" name="password" />

<button type="submit">Log In</button>

<OwnID type='login'

passwordField={passwordField}

loginIdField={emailField}

options={{variant: 'button-fingerprint', infoTooltip:true}}

onError={(error) => console.error(error)}

onLogin={onLogin} />

</form>

);

}

Angular

First, add the ownid component to the HTML template of the login page:

<form #myForm="ngForm" (ngSubmit)="onSubmit()">

<input #emailField type="email">

<input #passwordField type="password">

<ownid type="login"

[loginIdField]="emailField"

[passwordField]="passwordField"

[options]="{variant: 'button-fingerprint', infoTooltip:true}"

(onLogin)="onLogin($event)">

</ownid>

<button type="submit">Log In</button>

</form>

Next, define the onLogin function:

onLogin(data) {

//Set user session with data object, which was sent to OwnID server from your backend

this.authService.setAuth({ token: data.token });

//redirect user to the account page

this.router.navigateByUrl('/account');

}

JavaScript

Once the login page loads and initializes the OwnID SDK, it uses the following code to render the OwnID widget and log in the user:

<body>

<form name="myForm">

<input id="email" type="text" name="email">

<input id="password" type="text" name="password">

<input type="submit" value="Submit">

</form>

<script>

ownid("login", {

loginIdField: document.getElementById("email"),

passwordField: document.getElementById("password"),

variant: "button-fingerprint",

infoTooltip: true,

onError: (error) => console.log(error),

onLogin: function (data) {

//Set user session with data object, which was sent to OwnID server from your backend

localStorage.setItem('data', JSON.stringify({ token: data.token }));

//redirect user to the account page

window.location.href = '/account';

}

});

</script>

</body>

Customizing the UI

The default code added to initialize the OwnID SDK has a single parameter: appId. In addition to this required parameter, there are optional parameters that can be added to the initialization code to modify the look of the OwnID button. Each parameter is added to the ownid function of the initialization code as a key/value pair of the JSON object. See how to customize the OwnID widget in this page.

Security

OwnID enforces IP allowlisting to make server-to-server calls to your servers.

In addition, 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: 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 3: 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 4: 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:

NodeJS

const crypto = require('crypto');

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}`;

const hmac = crypto.createHmac('sha256', keyBuffer);

hmac.update(dataToSign);

let signature = hmac.digest('base64');

if (signature !== ownIdSignature) {

// The request has been tampered with

}

Python

import hmac

import hashlib

import base64

import json

key = "<your-shared-secret>" # This is the shared secret from OwnID Console

key_buffer = base64.b64decode(key)

data = json.dumps(request.get_json(), separators=(',', ':'))

own_id_signature = request.headers.get('ownid-signature')

own_id_timestamp = request.headers.get('ownid-timestamp')

data_to_sign = f'{data}.{own_id_timestamp}'.encode(encoding='utf-8')

signature = hmac.new(key_buffer, data_to_sign, hashlib.sha256).digest()

signature = base64.b64encode(signature)

signature = signature.decode(encoding='utf-8')

if not signature == own_id_signature:

# The request body or timestamp have been tampered with

C#

using System.Security.Cryptography;

string key = "<your-shared-secret>"; // This is the shared secret from OwnID Console

Byte[] keyBuffer = Convert.FromBase64String(key);

string body = JsonSerializer.Serialize(ownIdRequest.Content);

string ownIdSignature = ownIdRequest.Headers.GetValues("OwnID-Signature").FirstOrDefault();

string ownIdTimestamp = ownIdRequest.Headers.GetValues("OwnID-Timestamp").FirstOrDefault();

string dataToSign = $"{body}.{ownIdTimestamp}";

Byte[] dataToSignBytes = Encoding.Default.GetBytes(dataToSign);

string signature;

using (HMACSHA256 hmac = new HMACSHA256(keyBuffer))

{

signature = Convert.ToBase64String(

hmac.ComputeHash(dataToSignBytes));

}

if (signature != ownIdSignature)

{

// The request has been tampered with

}

Java

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

import javax.persistence.EntityNotFoundException;

import javax.persistence.NoResultException;

import java.nio.charset.StandardCharsets;

import java.security.Key;

import java.util.Base64;

import java.util.Map;

String key = "<your-shared-secret>"; // This is the shared secret from OwnID Console

byte[] keyBuffer = Base64.getDecoder().decode(key);

Key hashKey = new SecretKeySpec(keyBuffer, "HmacSHA256");

String ownIdSignature = headers.get("ownid-signature");

String ownIdTimestamp = headers.get("ownid-timestamp");

String dataToSign = String.format("%s.%s", bodyJson, ownIdTimestamp);

byte[] dataToSignBytes = dataToSign.getBytes(StandardCharsets.UTF_8);

Mac mac = Mac.getInstance("HmacSHA256");

mac.init(hashKey);

byte[] signatureBytes = mac.doFinal(dataToSignBytes);

String signature = Base64.getEncoder().encodeToString(signatureBytes);

if (!signature.contentEquals(ownIdSignature)) {

// The request has been tampered with

}