Skip to main content
Version: v2

Authentication

Beyond Identity console settings allow you to configure the authentication experience your users see.

The settings described here are configured via the Configuration Type on the Authenticator Config tab when you add an application.

The Beyond Identity platform offers three authenticator configuration types:

TypeWhen to use
Hosted WebIn this model, Beyond Identity's hosted web app handles passkey registration and authentication for you, including generating new passkeys, presenting users with authenticator choice options as needed, and validating passkey assertions. With this model, your app simply needs to redirect to Beyond Identity's hosted web authenticator, and we do the rest.
Embedded SDKWith this model you have more control over the authentication user experience, but your app must do the work of registering and enumerating passkeys for the user, presenting a passkey selection page if required, initiating authentication and verifying passkey assertions.
NoneIf the authenticator configuration type is set to "none", it means that the application uses the client credentials grant type and does not use an authenticator. This configuration is designed to be used for machine to machine authentication

Currently, the following authentication factors are supported and more are coming soon:

  • Universal Passkey

  • Email OTP

  • FIDO2 Multi-Device Passkey - Coming soon!

  • Federated IDP - Coming soon!

Hosted Web

The Hosted Web Authenticator is a constrained version of the Embedded SDK authenticator type. It requires less configuration and code, but it does require redirecting your users to a web-based authenticator hosted by Beyond Identity. The web-based authenticator, however, can be configured with your own logo and brand colors. The Hosted Web Authenticator handles passkey registration and authentication for you, including generating new passkeys, presenting users with authenticator choice options as needed, and validating passkey assertions. Your app simply needs to redirect to Beyond Identity's hosted web authenticator, and we do the rest. Beyond Identity can be set up as an OAuth or OpenID Connect provider using the Hosted Web Authenticator. If you wish to find an OpenID Connect client, we recommend looking for one on the list of certified OpenID Connect clients. To get started, create an application. All the values you need to configure the provider can be found in your Beyond Identity console application’s External Protocol tab.

Authentication Profile

The Authentication Profile allows you to customize the authentication flow for new or returning users.

Email verification for sign-up and new browser login

This configuration allows you to customize the authentication flow for user registration. This includes users who are registering for the first time or for the first time on a new browser, which includes browsers on the same device or a different device.

Currently the following authentication factors are supported and more are coming soon:

  • One-time password

    Verify email with OTP when an end user signs up or logs in on a new browser.

Authentication method for returning login

This configuration allows you to customize the authentication flow for user login.

Currently, the following authentication factors are supported and more are coming soon:

  • Hardware-bound passkey (Recommended)

    This option generates a hardware key within your device's trusted execution environment (TEE).

    Hardware-bound passkeys support biometric step-up during authentication. Available on Chrome and Edge.

    Select fallback method for when a browser isn’t supported:

    • Software-bound passkey (Recommended)

      Use software-bound passkey when a browser doesn’t support hardware-bound passkey.

    • One-time password

      Use OTP when a browser doesn’t support hardware-bound passkey.

  • Software-bound passkey

    This option generates a passkey securely created within the browser's context.

    Software-bound passkeys do not support biometric step-up during authentication.

  • One-time password

    Authenticate with OTP when an end user returns to log in on a browser previously used.

danger

Switching an authentication passkey method such as from "Hardware-bound" to "Software-bound" passkeys may require your customers to re-enroll a new passkey to match the method you have chosen. Your users will be prompted with the new browser login option (OTP) to create a new passkey.


In other words, if your user already has a "Hardware-bound" passkey but you have configured "Software-bound", then the user will no longer see their "Hardware-bound" passkey as an option to authenticate.

Embedded SDK

Embedded SDK requires more configuration and code. Still, it has more flexibility, like silent authentication and keeping the whole experience inside your application. The embedded SDK authenticator is embedded directly in your application when you install one of our SDKs.

The embedded SDKs handle all cryptographic operations on the user's device, such as creating passkeys and logging in with a passkey. We redirect to your native or web app to authenticate against those passkeys. Passkeys are stored on the same device as your native application or on a specific browser and origin for your web application.

This option enables three additional fields to configure:

  • Invocation Type

  • Invoke URL

  • Trusted Origins

Invocation Type

The Invocation Type specifies how the Beyond Identity authentication URL is delivered to your application. The authentication URL is your app's Invoke URL appended with /bi-authenticate? and the query string parameter request, containing the authentication challenge your app will need to sign:

$invoke_url/bi-authenticate?request=<request>
IMPORTANT

The Invocation Type only impacts the authentication flow. It has no effect on the passkey creation/binding flow.

Invocation Type can have one of two values:

ValueWhen to use
AutomaticYou want Beyond Identity to do the heavy lifting for you. If you initiate an OAuth2.0 request and specify the "Invoke URL" correctly, we'll get the Beyond Identity authentication URL to where it needs to be, whether this is inside of a native app or a web application. A 302 redirect is returned in response to your app's OIDC request, causing the user agent to automatically redirect to the authentication url.
ManualYou want or require a lot more control and flexibity when redirecting to your native/web app. For example:
  • write your own intelligent routing layer using the Beyond Identity authentication URL
  • authenticate against passkeys in your browser on desktop, but use passkeys on your native app on mobile
The authentication URL is returned to you as part of a JSON response, but it's up to you to get it to your native/web app any way you see fit.
{
  "authenticate_url": "$invoke_url/bi-authenticate?request=<request>"
}
Since the challenge is packaged as part of the URL, it behaves the same as the Automatic Invocation Type.

Invoke URL

The invoke URL is a single URL that points to where your application is. In the case of a native application (iOS, Android, Flutter, React Native), this is either an App Scheme or a Universal URL / App Link. In the case of a web application, this is just a URL to your web application or a specific page of your web application.

caution

While app schemes are generally easier to set up, Universal URLs and App Links are recommended as they provide protection against App Scheme hijacking.

There are two scenarios in which the Invoke URL is used:

ScenarioHow Invoke URL is used
Binding a passkeyYou can send a passkey enrollment (binding) link to your users (such as via email). When your user clicks the link, Beyond Identity redirects to the Invoke URL of your app. Note that the path /bind is appended to the Invoke URL and must be implemented as a route in your application.
AuthenticationWhen a user authenticates with a passkey, your app's Invoke URL is appended with /bi-authenticate? and the query string parameter request that contains the authentication challenge. For automatic invocation type, a 302 redirect is used, causing the user agent to automatically redirect to the authentication url. For invocation type manual, the authentication url is returned to your app as part of a JSON response. Note that the path /bi-authenticate is appended to the Invoke URL and must be implemented as a route in your application.

Invoke URL as used for binding a passkey

The redirect URL to your app will be in the following form:

$invoke_url/bind?api_base_url=<api_base_url>&tenant_id=<tenant_id>&realm_id=<realm_id>&identity_id=<identity_id>&job_id=<job_id>&token=<token>

The path /bind is appended to the invoke_url and must be implemented as a route in your application.

Invoke URL as used for Authentication

The path /bi-authenticate is appended to the invoke_url and must be implemented as a route in your application.

The authentication flow responses differs based on the Invocation Type specified (Automatic or Manual).

Invocation Type Automatic
HTTP/1.1 302 Found
Location: $invoke_url/bi-authenticate?request=<request>
Invocation Type Manual
HTTP/1.1 200 OK
Content-Type: application/json

{
"authenticate_url": "$invoke_url/bi-authenticate?request=<request>"
}

Trusted Origins

Trusted Origins are a list of URLs from which the embedded SDK is allowed to make requests to our backend. By default, cross origin requests are blocked by our server. Specifying your website's URL here adds it to a whitelist and enables your website to make requests to our server.