DirectWeb Integration

DirectWeb Integration (COMING SOON)

This DirectWeb Developer’s Quickstart Guide serves as an integration guide for our trusted partners so that you will be able to evaluate, test, and launch LoginID’s authentication service using our DirectWeb API.

At the present time, the DirectWeb API is still under development. This document serves as an initial draft of the API documentation.

About Direct Web API

login

The DirectWeb API is made available to your web application via the LoginID Javascript SDK. In contrast to the OpenID Connect flow, the DirectWeb API allows you to leverage LoginID’s authentication capabilities while allowing the user experience to remain completely within your domain.

When the user desires to register or login, your web application should call LoginID’s Javascript SDK as described below in the document. This allows the SDK to take over the flow from the client-side, without forcing you to manage the nuances of security when interacting with LoginID’s backend.

Depending on the type of authentication requested (e.g. FIDO2, OTP, Password), you maybe able to specify callback functions to manage very specific aspects of the flow via the options field. However, this capability is not available for all authentication types as the flow may not be conducive to such customized experiences. For example, if the authentication type is FIDO2, the native browser experience as defined by the browser vendor, will drive the experience regarding how the biometrics are requested. On the other hand, if the required authentication is OTP based, you may have an option to specify the UX widget that will receive the OTP from the user.

Step 1 - Obtain your client keys

In order for the LoginID Javascript SDK to manage the DirectWeb functionality on your behalf, it needs to be configured with your credentials, which you can obtain from LoginID’s dashboard.

To obtain the API key you will need to perform the following steps:

Create a new admin account

  • Navigate to https://qa1.awstest.loginid.io/ and select the “Register a new account” option and follow the instructions to create a new account on LoginID’s dashboard.

  • Use the navigation bar to select “Integration” or Press the “Get Integrated” button

Create Credentials

In the resulting form, you must enter the following information:

Application Name

Registered URL

Your application name

https://your.url

Please note that unlike in the OpenID Connect flow, the Registered URL is not a callback URL, but the top-level domain that is integrating the DirectWeb API functionality. LoginID’s backend will essentially whitelist this domain against your client profile as an allowable domain to issue cross-origin requests via the DirectWeb API.

Moreover, a callback URL is not needed as with the OpenID Connect integration, since the user experience never leaves your domain when using the DirectWeb API. Therefore, returning back to your domain via a callback URL is not required.

If the Registered URL is not specified correctly, the DirectWeb API functionality will fail.

Once the request is submitted, you will receive an API key and a JWS verification public key. The API key is used to configure LoginID’s Javascript SDK from your web application and the JWS verification public key can be used to verify the JWS object that is returned by the DirectWeb API once the user registration/login is complete.

API Key

JWS verification public key

Your API key

Public key to verify JWS returned by DirectWeb API

While you should generally store the API Key securely (i.e. don’t post it on the internet!), it is not strictly treated as confidential information since any motivated attacker can inspect your web application in their own browser and ascertain the API Key that is used to configure LoginID’s Javascript SDK. However, this API Key is not very useful for such an attacker since the API key is tightly coupled to the Registered URL that you defined previously, such that it is not practical for the attacker to use the API key on their own web application hosted under a different domain.

Moreover, using the API Key on the attacker’s own customized browser to spoof the origin URL can be mitigated and can be further discussed as necessary.

For the first iteration of the DirectWeb API, the result of the authentication will be returned to the frontend web application directly, where the returned JWS may be verified using the JWS verification public key on your backend for additional assurance. Therefore, a shared secret to facilitate direct backend-to-backend communication (or asymmetric equivalent) is not necessary, but for additional security enhancements in the future, maybe provided with a subsequent version of the DirectWeb API.

Step 2 - Getting LoginID Javascript SDK

The next step is to integrate the LoginID Javascript SDK to the web application and this can be achieved by the code snippet below:

<script src="https://loginid.io/apis/js/loginid-1.0.0.min.js"></script>

For all subsequent calls to DirectWeb API, the LoginID Javascript SDK uses this API Key when communicating with LoginID’s backend.

Step 3 - Configuring the SDK

Next the SDK must be initialized with the API Key that was obtained from LoginID’s dashboard in Step 1.

var loginid = require('loginid-directweb');
loginid.initialize('API-KEY');

For all subsequent calls to DirectWeb API, the LoginID Javascript SDK uses this API Key when communicating with LoginID’s backend.

Step 4 - Configuring the SDK

The code snippet for requesting registration of a new credential for the given username is shown below.

options = {
credential_type: 'FIDO2',
nonce: 'NONCE-GENERATED-ON-YOUR-SERVER'
};
let ret = await loginid.register(username, options);
// will return ret.success, ret.username, and ret.jws

The username is a mandatory field that must be passed into the register function. The options field specifies optional fields, where if not specified, LoginID will use default values. For example, if a nonce is not specified, the LoginID Javascript SDK will generate a nonce on the client-side prior to calling the LoginID backend. Irrespective of the origin of the nonce, the SDK will verify the nonce present in the response from the server against the expected nonce. If credential_type is not specified and the user’s browser/platform supports FIDO2, the LoginID Javascript SDK will default to FIDO2.

If you desire to specify the nonce, it is recommended that the nonce is generated on your backend and verified with the nonce in the returned JWS. The following code may be used to generate the nonce on the backend:

const crypto = require('crypto');
let nonce = crypto.randomBytes(16).toString('base64');

The returned object from the function will have three elements: success, username, and JWS, where you can obtain your desired level of assurance from these values. If you want to determine if the registration was successful on the front-end web application, it can simply check the success field. If you want to know the registered username (which will match the input username if this field is populated), the username field in the returned object can be used. If backend assurance is required regarding the operation, you can verify the JWS value with the JWS verification public key that was obtained in Step 1. The JWS includes the status of the operation (success), username, credential type, nonce, timestamp, etc. signed by the LoginID private key that will correspond to the JWS verification public key.

Step 5 - Login with an existing user credential

The code snippet to requesting login with an existing credential is shown below.

options = {
credential_type: 'FIDO2',
nonce: 'NONCE-GENERATED-ON-SERVER'
};
let ret = await loginid.login(username, options);
// will return ret.success, ret.username, and ret.jws

The discussion above in Step 4 regarding the parameters to and return object from the register function is equally applicable to the login function here.

Getting help

We’re happy to assist, if you have any questions please don’t hesitate to contact dev@loginid.io

Do you have any specific requests for examples using other frameworks or programming languages? Contact us and let’s talk about bringing secure, private authentication to your application, we have engineers on standby to discuss.