Skip to main content
Version: v2

authenticate

The authenticate function enables an app using the Beyond Identity SDK to perform passkey-based authentication within a standard OpenID Connect authorization flow.

Dependencies

The authenticate function requires the Beyond Identity SDK.

yarn add @beyondidentity/bi-sdk-js

or

npm install @beyondidentity/bi-sdk-js

Prerequisites

Before making a call to authenticate, you must complete the following prerequisite calls:

  1. Import the required types and functions from the SDK.

    import { Embedded } from '@beyondidentity/bi-sdk-js';
  2. Initialize the SDK.

    // --- Initialize with required arguments
    try {
    const embedded = await Embedded.initialize();
    console.log("Initialization successful", embedded);
    } catch (error) {
    console.error("Initialization failed:", error);
    }

    // --- Initialize with required and optional arguments
    const config = {
    allowedDomains: ["example.com", "another-example.com"],
    logger: function (logType, message) {
    console.log(`[${logType}] ${message}`);
    },
    };

    try {
    const embedded = await Embedded.initialize(config);
    console.log("Initialization successful", embedded);
    } catch (error) {
    console.error("Initialization failed:", error);
    }
  3. Identify the passkey you wish to authenticate with and obtain its passkey ID.

    How you achieve this depends upon your app, but you can obtain a list of passkeys available on the device via the getPasskeys function. This returns an array of passkeys that you can use, for example, to prompt the user interactively to select one. The id property of the selected Passkey is the passkey id this function expects

  4. Use isAuthenticateUrl to verify the url parameter you intend to send to the function

    if (embedded.isAuthenticateUrl(url)) {
    // authenticate against a passkey bound to the device
    }

Parameters

ParameterTypeDescription
urlstringRequired. A Beyond Identity authentication URL is generated by the Beyond Identity API's /authorize endpoint in response to a standard OpenID Connect request from your app (see example below). The generated URL is unique for each authentication request. It contains an encoded JWT token containing the challenge for the passkey to sign.
passkeyIdstringRequired. The ID of the passkey that you wish to use for the authentication. This should match the id property of a Passkey available on the device.

Returns

On success, the authenticate function returns the following response:

{
redirectUrl: string;
message?: string;
}
  • redirectURL: string containing the complete URL to which your app should redirect the user to complete the OIDC flow.

    Keeping with the OIDC specifications, this includes the code and state parameters as query parameters to the redirect_url specified in the original OIDC request to the /authorize endpoint for the authentication URL.

  • message: string containing a message your app may optionally consume or display.

Notes

Using the authenticate function requires your app to generate a standard OpenID Connect (OIDC) request to Beyond Identity's API and consume the resulting codes and tokens.

For step-by-step instructions to on how to configure authentication using the embedded SDK, see this guide.

Examples

Example: Call authenticate with selected ID after prompting the user with a list of passkeys

const url = "authenticate-url";

try {
// Fetch all passkeys for this browser
const passkeys = await embedded.getPasskeys();

// Check if there are any passkeys available
if (passkeys.length > 0) {
// TODO: Instead of automatically selecting the first passkey,
// present a UI to the user to let them select the desired passkey.
// For the purpose of this example, we're using the first passkey.
const passkeyId = passkeys[0].passkeyId;

if (embedded.isAuthenticateUrl(url)) {
// The URL is valid for authenticating against a passkey
const response = await embedded.authenticate(url, passkeyId);
console.log(`Successfully authenticated against passkey bound to this browser. Response: ${JSON.stringify(response)}`);
} else {
console.log("The URL is not a valid Authenticate Passkey URL");
}
} else {
console.log("No passkeys available for this browser");
}
} catch (error) {
console.error(`Error: ${error}`);
}

Example: Retrieve Beyond Identity authentication url via OIDC call

The app sends an OIDC call to the Beyond Identity API's /authorize endpoint:

Call /authorize Endpoint to Initiate OIDC Call
1
curl -X GET "https://auth-us.beyondidentity.com/v1/tenants/${TENANT_ID}/realms/${REALM_ID}/applications/${APPLICATION_ID}/authorize?client_id=${CLIENT_ID}&scope=openid&response_type=code&redirect_uri=${REDIRECT_URI}&state=8LIY29kN8Oz7zrAhb8xb0yvem-gvnRy1HTn03MAuL_E"

where the following elements match the corresponding properties of the app as configured in your Beyond Identity tenant:

PropertyDescription
TENANT_IDThe Tenant ID of the tenant in which the app is configured.
REALM_IDThe Realm ID of the realm in which the app is configured.
APPLICATION_IDThe Application ID from the header of the app's configuration page.
CLIENT_IDThe Client ID from the External Protocol tab of the app's configuration page.
REDIRECT_URIMatches one of the Redirect URIs configured on the External Protocol tab of the app's configuration page, URL encoded.

When the Invocation Type configured on the Authenticator Config tab of the app's configuration page is set to Manual, it returns a JSON object:

{ "authenticate_url": "http://localhost:8083/bi-authenticate?request={BI_JWT}" }

where BI_JWT is a base64url encoded JWT token containing the challenge and other data to kick off the passkey authentication.

When the Invocation Type on the app is set to Automatic, it returns an HTTP 302 to the authentication URL:

http/1.1 302 Found
...
location: http://localhost:8083/bi-authenticate?request={BI_JWT}

where BI_JWT is a base64url encoded JWT token containing the challenge and other data to kick off the passkey authentication.