Skip to main content
Version: v1

authenticate

Last updated on

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

Note: The example app for the Javascript SDK uses NextAuth.js to initiate the OIDC flow and to consume the resulting code and token.

Dependencies​

The authenticate function requires the Beyond Identity Javascript SDK.

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';
  1. Initialize the SDK
const embedded = await Embedded.initialize();

  1. Identify the passkey you wish to authenticate with and obtain its passkey id.

    How you achieve this depends upon your app, but a list of passkeys available on the device can be obtained 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

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

await embedded.isAuthenticateUrl(url)

Parameters​

ParameterTypeDescription
urlstringRequired. Beyond Identity authentication url. This 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.
passkeyIdstringThe ID of the passkey that you wish to use for the authentication. This should match the id property of a Passkey that is available on the device.

Returns​

On success, the authenticate function returns a Promise that resolves to an AuthenticateResponse, which itself is a JSON object that contains the following keys:

  • redirectURL: string containing the complete url to which your app should redirect the user in order to complete the OIDC flow. In keeping with the OIDC specifications this includes the code and state parameters as query parameters to the redirect_url that was specified in the original OIDC request to the /authorize endpoint for the an authentication url.
  • message: string containing a message your app may optionally consume or display.

Notes​

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

The example app for the Javascript SDK uses NextAuth.js to initiate the OIDC flow and to consume the resulting code and token. For step by step instructions to configure NextAuth.js and OIDC using our sample application, and to create the associated Beyond Identity tenant configuration, see the Getting Started guide. For complete guidance on authentication, see Workflow: Authentication with Passkey

Examples​

Example: Call authenticate after validating URL​

if (embedded.isAuthenticateUrl(url)) {
    authenticateResponse = await embedded.authenticate(url, passkeyId);
}

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

let passkeys = await embedded.getPasskeys();
let promptText = passkeys.map((passkey, index) => {
    return `${index}: ${passkey.identity.username}`;
}).join("\n");
let selectedIndex = parseInt(prompt(promptText, "index")!!);
if (selectedIndex >= 0 && selectedIndex < passkeys.length) {
    let selectedId = passkeys[selectedIndex].id;
    let result = await embedded.authenticate(url, selectedId);
}

Example: Retrieve Beyond Identity authentication url via OIDC call​

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

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:

  • TENANT_ID: the Tenant ID of the tenant in which the app is configured
  • REALM_ID: the Realm Id of the realm in which the app is configured
  • APPLICATION_ID: The Application ID from the header of the app's configuration page
  • CLIENT_ID: The Client ID from the External Protocol tab of the app's configuration page
  • REDIRECT_URI: Matches 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, 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, 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