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:
| Type | When to use |
|---|---|
| Hosted Web | In 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 SDK | With 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. |
| None | If 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.
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>
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:
| Value | When to use |
|---|---|
| Automatic | You 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. |
| Manual | You want or require a lot more control and flexibity when redirecting to your native/web app. For example:
|
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.
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:
| Scenario | How Invoke URL is used |
|---|---|
| Binding a passkey | You 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. |
| Authentication | When 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.
- EMAIL delivery_method
- RETURN delivery_method
Credential binding flows that use RETURN delivery_method do not make use of the Invoke URL.
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).
HTTP/1.1 302 Found
Location: $invoke_url/bi-authenticate?request=<request>
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.