@loginid/web-sdk

Web SDK

Introduction

Introduction to FIDO2

• FIDO2 stands for Fast Identity Online 2, and it is an open authentication standard that provides strong authentication using public key cryptography. It aims to eliminate the use of passwords and offers a more secure and user-friendly way to authenticate users. FIDO2 is made up of two main components:

• WebAuthn: A web standard for authenticating users without passwords using public key cryptography. It allows users to register and authenticate with web services using a variety of authentication methods, including biometrics and security keys.

• CTAP (Client to Authenticator Protocol): A standard that allows external devices (such as security keys or biometric devices) to communicate securely with a client device (e.g., a web browser) during the authentication process.

Introduction to Passkeys

Passkeys are a new type of login credential that provides a convenient way for users to authenticate without the need for traditional passwords. Passkeys can be stored securely on a user's device, and they are used for both registration and authentication processes. They offer strong security, as the private key never leaves the user's device.

Installation

To get started with the LoginID Gen 2 Web SDK, you can install it using your preferred package manager. Here's an example using npm:

npm install --save @loginid/web-sdk

Usage and Configuration

The LoginID Web SDK provides a set of functions and components that can be integrated into your web application. To use it, you'll need to configure the SDK with your LoginID credentials and then call the appropriate methods for signup and signin functionalities.

import { LoginIdConfiguration, LoginIdPasskey } from '@loginid/web-sdk';

// Initialize the SDK with your configuration
const config = new LoginIdConfiguration('BASE_URL', 'YOUR_APP_ID');

// Use the SDK components for signup and signin
const lid = new LoginIdPasskey(config)

// Get a reference to the signup button element
var signupButton = document.getElementById("lid-signup");

// Add a click event listener
signupButton.addEventListener("click", () => lid.signupWithPasskey('username', 'cred_name'));

// Get a reference to the signin button element
var signinButton = document.getElementById("lid-signin");

// Add a click event listener
signinButton.addEventListener("click", () => lid.signinWithPasskey('username'));

API Reference

LoginIdConfiguration class

Constructor

constructor(baseUrl: string, appId: string) Creates a new instance of the LoginIdConfiguration class.

• baseUrl (string): The base URL for API requests.
• appId (string): The application ID.

Methods

• getBaseUrl(): string Get the base URL for API requests.

• getAppId(): string Get the application ID.

• getHttpClient(): IHttpClient Get the HTTP client instance used for making API requests.

LoginIdPasskey class

Constructor

constructor(config: ILoginIdConfiguration) Initializes a new instance of LoginIdPasskey with the provided configuration.

• config (ILoginIdConfiguration): The Login SDK configuration.

Methods

signupWithPasskey(username: string, options?: ISignupOptions): Promise<IPasskeyResult> Signs up with a passkey for the given username.

• username (string): The username for the sign-up.
• options (ISignupOptions, optional): Additional options for the sign-up.
• Returns a Promise that resolves to the result of the sign-up operation.

signinWithPasskey(username?: string): Promise<IPasskeyResult> Signs in with a passkey. If a username is provided, it signs in the user with that username; otherwise, it signs in the user anonymously.

• username (string, optional): The username for sign-in. If not provided, a user is signed in anonymously.
• Returns a Promise that resolves to the result of the sign-in operation.

sessionMfaBegin function

The sessionMfaBegin function is a critical step in initiating a multi-factor authentication session. It prepares the necessary data and sends a request to the server to create a session for multi-factor authentication.

Function

sessionMfaBegin(config: ILoginIdConfiguration): Promise<ISessionMfaBeginResponse> Begins a multi-factor authentication session.

• config (ILoginIdConfiguration): The Login SDK configuration.
• Returns a Promise that resolves to the session initiation response.

sessionMfaComplete function

The sessionMfaComplete function is used to complete a multi-factor authentication session that was previously initiated. It sends a request to the server to finalize the authentication session and returns the authentication token along with its expiration time.

Function

sessionMfaComplete(config: ILoginIdConfiguration, sessionId: string): Promise<ISessionMfaCompleteResponse> Completes a multi-factor authentication session.

• config (ILoginIdConfiguration): The Login SDK configuration.
• sessionId (string): The ID of the session to complete.
• Returns a Promise that resolves to the session completion response.

registerPasskeyInit function

The registerPasskeyInit function is used to initiate passkey registration for a user. It sends a request to the server to begin the registration process, and the server responds with registration details. These details are essential for proceeding with the registration process.

Request Structure

IRegisterPasskeyInitRequest Represents the request structure for initiating passkey registration.

• session_id (string): The session ID for the registration.
• username (string): The username for the registration.

Response Structure

IRegisterPasskeyInitResponse Represents the response structure for initiating passkey registration.

• session_id (string): The session ID for the registration.
• attestation (AttestationConveyancePreference): The attestation conveyance preference.
• authenticatorSelection (AuthenticatorSelectionCriteria): Authenticator selection criteria.
• challenge (string): A challenge for registration.
• excludeCredentials (optional): An optional list of credentials to exclude.
• extensions (optional): Additional extensions.
• pubKeyCredParams (PublicKeyCredentialParameters[]): Public key credential parameters.
• rp (object): Information about the Relying Party.
  • id (string): The ID of the Relying Party.
  • name (string): The name of the Relying Party.
• timeout (number): The registration timeout.
• user (object): User information.
  • id (string): The user's ID.
  • displayName (string): The user's display name.
  • name (string): The user's name.

Function

registerPasskeyInit(config: ILoginIdConfiguration, sessionId: string, username: string): Promise<IRegisterPasskeyInitResponse> Initiates passkey registration.

• config (ILoginIdConfiguration): The Login SDK configuration.
• sessionId (string): The session ID for the registration.
• username (string): The username for the registration.
• Returns a Promise that resolves to the registration response.

registerPasskeyComplete function

The registerPasskeyComplete function is used to complete the passkey registration process for a user. It sends a request to the server with the necessary data to finalize the registration. This function is typically called after initiating the registration with the registerPasskeyInit function. It returns the completion response, which contains important information about the registered user and their credentials.

Request Structure

IRegisterPasskeyCompleteRequest Represents the request structure for completing passkey registration.

• session_id (string): The session ID for the registration.
• username (string): The username for the registration.
• cred_name (string | undefined): The credential name (optional).
• attestation_response (object): Attestation response data.
  • id (string): The ID of the credential.
  • challenge (string): A challenge for registration.
  • type (string): The type of response.
  • response (object): Response data.
    • attestationObject (string): Attestation object.
    • clientDataJSON (string): Client data in JSON format.
    • transports (string[]): List of authenticator transports.

Response Structure

IRegisterPasskeyCompleteResponse Represents the response structure for completing passkey registration.

• user (object): User information.
  • user_uuid (string): The user's UUID.
  • username (string): The user's username.
  • created_at (Date): The user's creation date.
  • last_login (Date): The user's last login date (if available).
  • is_active (boolean): Indicates if the user is active.
• auth_cred (object): Authentication credential information.
  • cred_uuid (string): The credential's UUID.
  • user_uuid (string): The user's UUID.
  • tenant_id (string): The tenant's ID.
  • cred_name (string): The credential's name.
  • created_at (Date): The credential's creation date.
  • locked_as_of (Date): The date the credential was locked.
  • cred_type ('fido2'): The type of credential.
• is_authenticated (boolean): Indicates if the registration is authenticated.

Function

registerPasskeyComplete(config: ILoginIdConfiguration, sessionId: string, username: string, init: IRegisterPasskeyInitResponse, cred: PublicKeyCredential, credname?: string): Promise<IRegisterPasskeyCompleteResponse> Completes passkey registration.

• config (ILoginIdConfiguration): The Login SDK configuration.
• sessionId (string): The session ID for the registration.
• username (string): The username for the registration.
• init (IRegisterPasskeyInitResponse): The registration initiation response obtained from registerPasskeyInit.
• cred (PublicKeyCredential): The public key credential obtained fom the client's device.
• credname (string | undefined): The credential name (optional).
• Returns a Promise that resolves to the completion response.

authenticatePasskeyInit function

The authenticatePasskeyInit function is used to begin the passkey-based authentication process. It sends a request to the server to initiate authentication for a user. This function is typically called before continuing with the authentication process by using the response data.

Request Structure

IAuthenticatePasskeyInitRequest Represents the request structure for initiating passkey authentication.

• session_id (string): The session ID for authentication.
• username (string | null): The username associated with the authentication request (optional).

Response Structure

IAuthenticatePasskeyInitResponse Represents the response structure for initiating passkey authentication.

• session_id (string): The session ID for authentication.
• allowCredentials (array | undefined): Optional list of allowed credentials.
  • id (string): The ID of the credential.
  • transports (string[] | undefined): List of allowed authenticator transports.
  • type (string): The type of credential.
• challenge (string): A challenge for authentication.
• extensions (object): Additional client extensions.
• rpId (string): The Relying Party (RP) ID.
• timeout (number): The authentication timeout.
• userVerification (string): User verification requirements.

Function

authenticatePasskeyInit(config: ILoginIdConfiguration, sessionId: string, username: string|null): Promise<IAuthenticatePasskeyInitResponse> Initiates passkey authentication by making an API request.

• config (ILoginIdConfiguration): The configuration for the authentication process.
• sessionId (string): The session ID for authentication.
• username (string | null): The username associated with the authentication request (optional).
• Returns a Promise that resolves to the authentication initiation response.

authenticatePasskeyComplete function

The authenticatePasskeyComplete function is used to complete the passkey-based authentication process. It sends a request to the server to finalize the authentication for a user, and it returns the completion response containing relevant user and authentication information.

Request Structure

IAuthenticatePasskeyCompleteRequest Represents the request structure for completing passkey authentication.

• session_id (string): The session ID for authentication.
• username (string | null): The username associated with the * authentication request (optional).
• assertion_response (object): The assertion response from the authenticator.
  • id (string): The ID of the assertion response.
  • challenge (string): A challenge for authentication.
  • type (string): The type of authentication.
  • response (object): The response data from the authenticator.
    • authenticatorData (string): Authenticator data.
    • clientDataJSON (string): Client data in JSON format.
    • signature (string): The signature.
    • userHandle (string | undefined): User handle (optional).

Response Structure

IAuthenticatePasskeyCompleteResponse Represents the response structure for completing passkey authentication.

• user (object): User information.
  • user_uuid (string): The user's UUID.
  • username (string): The user's username.
  • created_at (Date): The user's creation date.
  • last_login (Date): The user's last login date (if available).
  • is_active (boolean): Indicates if the user is active.
• auth_cred (object): Authentication credential information.
  • cred_uuid (string): The credential's UUID.
  • user_uuid (string): The user's UUID.
  • tenant_id (string): The tenant ID.
  • cred_name (string): The credential name.
  • created_at (Date): The credential's creation date.
  • locked_as_of (Date | null): The date the credential was locked, or null if not locked.
  • cred_type (string): The type of credential ('fido2').
• is_authenticated (boolean): Indicates if the user is authenticated.

Function

authenticatePasskeyComplete(config: ILoginIdConfiguration, sessionId: string, username: string|null, init: IAuthenticatePasskeyInitResponse, cred: PublicKeyCredential): Promise<IAuthenticatePasskeyCompleteResponse> Completes passkey authentication by making an API request.

• config (ILoginIdConfiguration): The configuration for the authentication process.
• sessionId (string): The session ID for authentication.
• username (string | null): The username associated with the authentication request (optional).
• init (IAuthenticatePasskeyInitResponse): The initiation response for authentication.
• cred (PublicKeyCredential): The public key credential for authentication.
• Returns a Promise that resolves to the authentication completion response.

createPasskeyCredential function

The createPasskeyCredential function is used to create a passkey credential required for user registration. It takes the registration initiation response as an input and returns a promise that resolves to the passkey credential.

Input Parameters

• init: IRegisterPasskeyInitResponse Represents the registration initiation response. This response includes the information required to create a passkey credential.

Output

The function returns a promise that resolves to a PublicKeyCredential, which represents the created passkey credential.

getPasskeyCredential function

The getPasskeyCredential function is used to retrieve a passkey credential required for user authentication. It takes the authentication initiation response as an input and returns a promise that resolves to the passkey credential.

Input Parameters

• init: IAuthenticatePasskeyInitResponse Represents the authentication initiation response. This response includes the information required to retrieve a passkey credential.

Output

The function returns a promise that resolves to a PublicKeyCredential, representing the retrieved passkey credential.

License

This project is licensed under the ISC License.

ISC License (Internet Systems Consortium License)

The ISC License is a simple and permissive open-source software license. It is similar in spirit to the MIT and BSD licenses. Here are the key points to understand about the ISC License:

• Permission to Use: You are granted the permission to use, copy, modify, and distribute the software for any purpose, whether for personal, educational, or commercial use.
• No Warranty: The software is provided "as is," without any warranties. The author or maintainer of the software is not liable for any issues or damages arising from its use.
• Redistribution: You are free to redistribute the software in its original source code or compiled binary form, provided you include the original copyright notice and the ISC License text.
• Minimalistic: The ISC License is known for its minimalistic and concise text, making it easy to understand and comply with.

Summary

The ISC License is a straightforward and permissive license that encourages collaboration and the free use of software in your projects. It offers the freedom to modify, share, and build upon software while requiring minimal legal documentation. You can use software under the ISC License for personal, educational, or commercial purposes.

For more details, please refer to the full text of the ISC License.

Link to ISC License ISC License (Full Text)