Create an Authentication widget

This topic describes how to create an Authentication widget in CyberArk Identity from the Admin Portal and embed the widget in your web app or link the CyberArk Identity hosted page to your web app.

Overview

The CyberArk Identity Authentication widget provides authorization, multi-factor authentication (MFA), and single-sign-on (SSO) to your websites and mobile applications, while implementing standards like OIDC and SAML.

The following diagram illustrates an example of how a user can sign in to a website called Acme Inc. using the Authentication widget.

The following functions are supported by the Authentication widget when it's integrated with a web app:

Quick Response (QR) Code user identification
Self-service password reset (SSPR) configuration
Self-service account unlock (SSAU)
Social media sign-in (applicable only for CyberArk-hosted widgets)
Forgot username self-service at sign in
Adaptive MFA
Multifactor authentication - The Authentication widget supports all the out-of-band (OOB) factors in CyberArk Identity. You can configure any authentication profile for conditional access to secure their applications using Authentication widgets.
External IdP authentication (applicable only for CyberArk-hosted authentication pages) - In addition to supporting LDAP and AD authentication, the Authentication widget supports Azure AD Domain Services (DS) and Google Directory Service (GDS) authentication, and external IdP authentication using standard protocols such as SAML and OIDC.
Anti-phishing security image
Remember last signed in username (Remember me)
Custom links

Keep me signed in and smart card authentication are not supported in widgets.

Before you begin

To embed a widget to your web app, specify trusted domains for API calls to prevent cross-origin resource sharing attacks before creating and deploying widgets.

In the Admin portal, go to Settings > Authentication > Security Settings.
In the API Security section, click Add under Specify Trusted DNS Domains for API Calls and select the domain that serves the widget page to the trusted domains of your tenant. For example, localhost.

Create an Authentication widget

The following procedure describes how to create and customize an Authentication Widget.

Step 1: Add the Authentication widget

Go to Apps & Widgets > Widgets, then on the top right corner, click Add widget.
Select Authentication Widget from the drop-down list.

The Get started page of the selected widget displays and you can customize the widget for your needs.

Step 2: Get started with the configuration

Update the following fields in the Get started tab:

Name	Description
Widget name	Enter a unique name for your widget. This is a required field.
Select the application that the user will be redirected to after authentication	Select a web app from the list of deployed applications to link to the widget. After a successful sign in, you are redirected to the selected application. See Integrate a widget with the OIDC app for more information.

Name

Description

Widget name

Enter a unique name for your widget. This is a required field.

Select the application that the user will be redirected to after authentication

Select a web app from the list of deployed applications to link to the widget. After a successful sign in, you are redirected to the selected application.

See Integrate a widget with the OIDC app for more information.

Step 3: Customize the Login form

In the Login form tab, you can customize the fields and corresponding labels that are displayed in the login form of an end user's application as follows:

In the Configuration section, perform the following actions:
- Select Enable social login to enable the user to log in to the app using their social media credentials.
- Select Enable forgot username link to add a link for the forgot password use case in the Login form.
Select a preferred language from the Language drop-down list and see the content in the label editor change to the selected language. The Login form label editor is a JavaScript-based editor where you can customize the Login form labels.

You can expand the Script Help menu to get more details on the objects defined in the Login form.
Select Update Preview to preview the form as you edit the fields.

The language that appears on the Login screen of the user's application depends on the browser language selected by the end user.
Select Reset to revert the edited labels to their default descriptions.

Label Name	Description	Default text
UsernameHeader	Enter a name for the form.	Sign In
SocialLoginLabel	Enter the text that appears on the form when you select the Enable social login field.	Or sign in with social media
StartOverLink	Enter the text that appears for the signin page with MFA challenges after selecting next to restart the login form.	Start Over
ForgotUsernameLabel	Enter the text that appears when you select Enable forgot username link, to preview the link in the form.	Don't know username?
LoginNameLabel	Specify a hint for the Login name field header, for the end user to enter the username in the correct pattern.	Enter your username {login_name_hint}. The {login_name_hint} is a variable obtained from Login Customization section of the Account customization page and is displayed in English only.
LoginNamePlaceholder	Specify a hint for the Login name field, for the end user to enter the username in the correct pattern.	Your username {login_name_hint}
NextButtonText	Enter text on the button that takes the end user to the MFA challenge page upon selection.	Next
Authentication Header	Enter the header text that appears for the Signin page with MFA challenges after selecting Next.	Authenticate to {company_name}. The {company_name} is a variable obtained from the General options section of the Account Customization page and is displayed in English only.
ChooseMFAPrompt	Specify the hint text for the user to select the required MFA prompt for the first challenge.	Choose authentication method
ChooseSecondFactorPrompt	Specify the hint text for the user to select the required MFA prompt for the second challenge.	Choose second authentication method
PasswordPrompt	Specify the hint text for the user to enter their password.	Enter the password associated with your username
ForgotPasswordLink	Enter the text that appears when the user has configured only password authentication. The link does not appear if other authentication challenges are configured.	Forgot your password?
PasswordLabel	Enter the label text for password field.	Password
PasswordMismatchPrompt	Specify an error message that appears when the user's new password does not match with the one entered in the confirm password field.	Passwords do not match.
ResetPasswordPrompt	Enter the header text for the page where the user can reset the password.	Reset Your Password
NewPasswordPrompt	Specify the hint text for the New Password field.	New Password
ConfirmPasswordPrompt	Specify the hint text for the Confirm Password field.	Confirm Password
PasswordResetLabel	Enter the label text for Password reset button.	Password reset
MandatoryFieldPrompt	Specify the error message for the password field when left blank.	This field is mandatory
EnterCodePrompt	Specify the hint text to enter the code received for MFA challenge.	Enter code
AuthenticateButtonText	Enter the label text for the authentication button.	Authenticate
EmailLabel	Enter the label text for the email MFA challenge that was configured.	Email - {email_address}. The {email_address} is a variable obtained from the registration details the user provides when he signs up and is displayed in English only.
SendEmailButtonText	Enter the label text for the send email button.	Send me an email
EmailSentLabel	Specify the label text for the email sent status.	Email sent!
EmailPrompt	Enter the prompt message to the user that the email is sent to the registered email address.	Email sent to {email_address}. Click the link or manually enter the code to authenticate. \n\nReturn to this app to continue.
TextMessageLabel	Enter the label text for the MFA challenge configured to share the text message.	Text Message - * * {mobile_number}. The {mobile_number} is a variable obtained from the registration details the user provides when they sign up and is displayed in English only.
SendTextMessageButtonText	Enter the label text for the Send me a message button.	Send me a message
SMSSentLabel	Specify the label text for the message sent status.	Message Sent!
SMSPrompt	Enter the prompt message to the user that the message is sent to the registered mobile number.	Message sent to number * * {mobile_number}. Approve the notification or manually enter the code to authenticate\n\n
PhoneCallLabel	Enter the label text for the MFA challenge configured to make a phone call.	Phone - * * {mobile_number}
SendPhoneCallButtonText	Enter the label text for the Call me button.	Call me
CallingLabel	Enter the label text for showing the call status.	Calling you...
PhoneCallPrompt	Enter the prompt message to the user that the message is sent to the registered mobile number.	Attempting to call * * {mobile_number}.\n\nFollow the instructions to authenticate.
ProvideCodeLabel	Enter the label asking the user to provide the MFA code.	Provide a code
VerificationCodePrompt	Enter a value to customize the prompt displayed on the form to provide the MFA code.	Enter the verification code
ScanQRwithIdentityApp	Enter the text to scan the QR code with the CyberArk Identity app.	Scan QR code with the CyberArk Identity app.
NotificationMessagePrompt	Enter the prompt message that is displayed when a push notification is sent to the user's mobile device.	Push notification sent!
RequestSentPrompt	Enter the prompt message for the QR code MFA challenge.	Request sent to your device. Approve the notification or manually enter the code to authenticate.
AnswerQuestionsButton	Enter the text for the Answer these questions button to answer the security questions.	Answer these questions
QRCodeLabel	Enter the label text for displaying the QR code.	QR code
GenerateCodeButton	Enter the text for the Generate a code button.	Generate a code
QRDisplayPrompt	Enter the message to the user for the QR code.	Here's your QR code
ScanQRwithIdaptiveAppPrompt	Enter the prompt message to scan the QR code with the CyberArk app on an enrolled device.	Scan QR code with the CyberArk app on an enrolled device.
MobileAuthenticatorLabel	Enter the label text for mobile authenticator.	Mobile Authenticator
MobileAuthenticatorButton	Enter the text for the Send me a push button.	Send me a push
OnDeviceAuthenticatorLabel	Enter the label text displayed for the on-device authentication.	On-device authentication
OnDeviceAuthenticatorButton	Enter the text for the Continue with device button.	Continue with device
OnDeviceAuthenticatorDispayLabel	Enter the label text displayed to indicate the user to use on-device authentication.	Use your device
OnDeviceAuthenticatorPrompt	Enter the prompt message to the user for on-device authentication.	Interact with your On-device Authenticator
OnDeviceAuthenticatorError	Enter the error message text that is displayed when the on-device authenticator fails.	There was an error interacting with your authenticator, please try again.

Step 4: Customize the Sign-up form

In the Sign-up form tab:

Create a form for the user to complete a one-time registration to an application. You much have CAPTCHA configured to enable the sign-up form. See Enable CAPTCHA for more details.
Select the Enable sign-up form checkbox to enable a sign up form, then configure the fields.
Select the primary identifier from the drop-down list.
Select the sign-up fields. The Username, Password, Confirm Password, and Email fields are selected by default.

The sign-up form only displays the fields shown in the Admin Portal. You cannot add more fields to the Sign-up form. In addition, social login is not displayed in the sign-up form.

Step 5: Customize the widget to match your branding

Use the Styling tab to customize the look and feel of the widget to match your branding. This customization is reflected in the Login and Sign-up forms. For more details, see Customize portal and login windows.

Step 6: Embed or host the widget in your web app

To embed the widget into your web app:

Go to the Deploy tab, then click Download Html to download the HTML of the Authentication page.
Embed the widget into your web app.

For more details, see Embed the widget into your web app.

To link the CyberArk Identity hosted widget:

Go to the Deploy tab, then click Copy URL to copy the URL of the Authentication page.
Create a customized Authentication page, hosted by CyberArk using the widget customization javascript editor.

For details, see Link the CyberArk Identity hosted widget.

Hosted pages and embedded widgets support the OIDC-based external IdP authentication. SAML is supported only by hosted pages.

Implement app-level MFA for the widget

By implementing app-level MFA, you can enhance the security of your application. To do this, you have to link the MFA widget to your web app. This feature offers an extra layer of protection by prompting users to adhere to the app-level policy instead of relying on the user policy.

Configure app-level MFA

Go to Apps & Widgets > Web Apps, then click on your web app.
In the Policy tab:
1. Select the profile from the Default Profile (used if no conditions matched) drop-down.
2. Select Bypass Login MFA when launching this app, then click Save. This checkbox ensures that the policy set at the application level takes precedence over the policy set at the user level.

When the user signs in to the authentication widget, the user is prompted with the authentication profile set up for the app, rather than the authentication profile set at the user level.