Configuring Advanced Settings

This article explains how to create and customize authentication error messages in the Beyond Identity Admin Console, allowing organizations to provide tailored notifications and guidance for users when authentication issues occur.

Under Advanced Settings in the Admin console, administrators can define custom error messages that provide end-users with additional information, an option to self-remediate, or a contact to reach out for help when they encounter authentication or registration failures.

Error notification types

There are 8 notification types that allow customization.

Notification type	Description	Shown on authentication failure?	Shown on registration failure?	Supports self remediation?
Policy Denied Notification	This is a notification that appears when any rule condition in a policy evaluates to "Deny" and does not allow authentication. If you want to set a custom notification for individual rule conditions in a policy (e.g. a custom notification that the user is on an unsupported OS version and needs to upgrade to authenticate), you can do so on the Policy page. For more information, see How to define policies. Custom notifications for individual rules take precedence over this “Policy Denied” notification configured in Advanced Settings.	Yes	Yes	No
User Suspended Notification	This notification appears when the user's account has been deactivated to prevent the user from authenticating. To reactivate an account, navigate to Users, click the deactivated user name, and click Reactivate User.	Yes	Yes	No
Deleted User Notification	This notification appears when the user cannot be authenticated because their account was deleted via the API (see https://docs.beyondidentity.com/api/v0#tag/Users/operation/DeleteUser). If this was an error, you can add a user back via the Admin console by navigating to Users and clicking Add User. You can also add the user via the API.	Yes	Yes	No
Passkey Deleted Notification	This notification appears when the user cannot authenticate due to a missing certificate or passkey on the user's device most likely due to: A password reset which changes the login password and rotates the Keychain and TPM or Secure Enclave. The wrong password was entered and the operating system reset the password. A backup was restored to a new or different device.The TPM or Secure Enclave is not be migrated because it is linked to the device's hardware. Users will need to add a new passkey to the device. If you change the message, make sure to point users to steps to add a new passkey -- instructions are on the Beyond Identity support site at: https://support.beyondidentity.com/docs/my-credential-isnt-working-when-i-try-to-login-due-to-a-missing-certificate	Yes	No	Yes
Passkey Not Found Notification	This notification appears when the user cannot authenticate because a passkey for the account was not found on their current device. If users have the passkey installed on a different device, such as their cell phone, they can migrate their existing passkey to the current device. For instructions, see: Windows: https://supportcases.beyondidentity.com/hc/en-us/articles/6763368950295/ macOS: https://supportcases.beyondidentity.com/hc/en-us/articles/6922972670615 iOS: https://supportcases.beyondidentity.com/hc/en-us/articles/6921300831383/ Android: https://supportcases.beyondidentity.com/hc/en-us/articles/6921633765655/ Linux: https://supportcases.beyondidentity.com/hc/en-us/articles/6922744089111	Yes	No	Yes
Passkey Not Found With Fallback Notification	This notification appears when the user cannot authenticate because a passkey for their account was not found on their current device, and roaming authentication is enabled for the tenant. If users have the passkey installed on a different device, such as their cell phone, they can migrate their existing passkey to the current device. For instructions, see: Windows: https://supportcases.beyondidentity.com/hc/en-us/articles/6763368950295/ macOS: https://supportcases.beyondidentity.com/hc/en-us/articles/6922972670615 iOS: https://supportcases.beyondidentity.com/hc/en-us/articles/6921300831383/ Android: https://supportcases.beyondidentity.com/hc/en-us/articles/6921633765655/ Linux: https://supportcases.beyondidentity.com/hc/en-us/articles/6922744089111	Yes	No	Yes
Authenticator Launch Error	This notification appears when communication cannot be established with the authenticator. Users should confirm that the authenticator is installed on the device, and if so, launch it to confirm that it's working.	Yes	Yes	No
Login Hint Mismatch	This notification appears when there is a login hint mismatch error for OIDC or WS-Fed requests. The login hint type is configured under Integrations > OIDC or Integrations > WS FED.	Yes	No	No

How to configure custom error messaging

Log into the Admin console.
Select Settings and scroll down to Advanced Settings.
Edit a notification by clicking the pencil icon to the right of it. Modify the following settings in the configuration dialog that has opened:
1. Error title
2. Error text (previously the error message)
  1. This field supports Markdown (for more information, see our Markdown Reference Guide).
3. Enable Self Remediation toggle
  1. This toggle enables the self remediation flow for end users to extend a passkey from another device to their current one (for more information, see our Self-Remediation via Credential Extension Guide).
  2. This option is only available on select notification types - see “Supports self-remediation?” column in the table above.
4. Action buttons (optional)
  1. Add up to 2 action buttons. These buttons are links that will open in the current browser window.
  2. Primary buttons are rendered with a black color background.
  3. Secondary buttons are rendered with a white color background.
Note: You can also click “Revert to default” to restore the default error configuration.
The following image shows an example of a configuration dialog for the “Passkey Not Found” notification:
Click Save Changes when finished.

Example notifications

Below, we’ve included images of example configurations and how they’re displayed in the browsers to end-users.

Admin Configuration	End-user view
“Passkey Not Found” notification with self-remediation enabled.	“Set up passkey with another device” button is displayed in the “Select another method” section.
“Passkey Not Found With Fallback” notification with custom message and action button.	Custom message is displayed, along with a “Log in another way” primary action button. “Log in with QR code“ button is displayed in the “Select another method” section.
“Policy Denied” notification with custom title, message, and 2 action buttons.	Custom title and message are displayed, along with a “Request Access” primary action button and “Report” secondary action button.

Admin Configuration

End-user view

“Passkey Not Found” notification with self-remediation enabled.

“Set up passkey with another device” button is displayed in the “Select another method” section.

“Passkey Not Found With Fallback” notification with custom message and action button.

Custom message is displayed, along with a “Log in another way” primary action button. “Log in with QR code“ button is displayed in the “Select another method” section.

“Policy Denied” notification with custom title, message, and 2 action buttons.

Custom title and message are displayed, along with a “Request Access” primary action button and “Report” secondary action button.