Authentication Widget

This guide provides instructions for hosting the CyberArk Identity authentication widget to provide authentication and authorisation for your application.

Introduction to Authentication Widget

The CyberArk Identity authentication widget is JS based application that enables users to register and authenticate to any third-party apps using the login mechanism provided by CyberArk Identity.

The CyberArk Identity authentication widget provides:

  • Authentication to your websites and mobile applications without using a password.
  • Strong multi-factor authentication layer to have a secure access to your websites and mobile applications through the trusted CyberArk Identity platform.
  • Single Sign On functionality while implementing standards like OIDC and SAML.
  • Seamless login experience without losing your branding, through several customisation options.
  • Registration user into the CyberArk Identity.

The following diagram shows how a user can login to an external website using the authentication widget. The end user would have to provide the required information for login using the widget Once the information is provided, the user will be authenticated against the CyberArk Identity cloud directory and if the authentication is successful the user would be able to login to the website.

Authentication widget uses the start authentication and advance authentication APIs to authenticate the user while using the CyberArk Identity.

Functionalities supported by the Login Widget

  • Multi-factor authentication lets you to secure the access to your application with the adaptive MFA
  • Single sign on enables users to securely authenticate with multiple applications and websites by using just one set of credentials.
  • QR-code based user identification enables users to log in to your application by scanning a Quick Response (QR) Code with an enrolled mobile device.
  • Configure self-service password reset (SSPR) so your users can reset their forgotten passwords without the need to contact your help desk.
  • Enable users to unlock their accounts using self-service account unlock (SSAU)
  • Enable your users to use their existing social media credentials to access your application using social login
  • Allow users to retrieve their forgotten username with the forgot username self-service at login

Prerequisites

Enabling cross-origin

Add the domain which serves this page to your tenant's trusted domains at the following location in the admin portal:
Settings > Authentication > Security Settings > Specify Trusted DNS Domains for API Calls

For example:
If your widget is hosted on the localhost:

Configure the login widget in admin portal

Configure your login widget at the following location in the admin portal
Settings > Customization > Authentication Widgets.

Once you add the login widget, you will be redirected to widget configuration page where you can customize the widget and add the success handler function to dictate how the end user should be re-directed post authentication.

Embed the login widget into your web app

A full screen login widget HTML template can be copied using the Copy HTML button from the widget configuration page

or you can embed in existing HTML with the following steps:

Embed the widget HTML in your web app:

To use the CDN, include this in your HTML:

Customize the success handler

  • Inject the login widget by providing a containerSelector (a querySelector path) for the container on your page where you'd like it to display. This can be any empty div on the page, or the body itself.
document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({
                  "containerSelector": ".cyberark-login",
                  "apiFqdn": "ENTER YOUR API FQDN",
                  "widgetId": "AUTO GENERATED WIDGET ID",
                  "appKey": "PROVIDE YOUR APPKEY HERE",
                  "success": function (AuthData) { loginSuccessHandler(AuthData) }
                });
            });
  • Provide your API FQDN (full qualified domain name of your tenant). Ex: If your tenant URL is https://acmeinc.my.idaptive.app your API FQDN would be acmeinc.my.idaptive.app
  • The widget ID gets generated for the widget when it is added on the admin portal. Every widget has a unique Id. The customizations and the policies can be updated dynamically for the widgets using this Id.
  • The appKey is used to link the login widget with an app. For more details refer to “Connect login widget with apps” section.
  • Provide success handler function to dictate what will happen once the user is authenticated successfully. For more details refer to “Connect login widget with apps” section.

Note: Either appKey or success handler can be used. If appKey and success handler are provided, success handler is given preference over appKey

Try it out yourself

Prerequisites: Python should be installed.

To try out the widget yourself follow the below steps:

  • Navigate to the admin portal and navigate to settings -> customization -> authentication widgets.
  • Add your own login widget with all the customizations required.
  • Copy the HTML to either to a python IDE or to Notepad++.
  • Edit the success handler as below an save the HTML file.
document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({
                  "containerSelector": ".cyberark-login",
                  "apiFqdn": "ENTER YOUR API FQDN",
                  "widgetId": "AUTO GENERATED WIDGET ID",
                  "success": function (AuthData) { loginSuccessHandler(AuthData) }
                });
            });
           function loginSuccessHandler(AuthData){
             window.location.href = 'http://localhost:8000/';
             document.write('<html><body><h2>Authentication Token:</h2> '+AuthData.Auth+'</body></html>');
           }

Host the login widget on your local host by creating a simple python server as below:

import http.server
import socketserver

class MyRequestHandler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/':
            self.path = 'LoginWidget.html'
        return http.server.SimpleHTTPRequestHandler.do_GET(self)

Handler = MyRequestHandler
server = socketserver.TCPServer(('127.0.0.1', 8000), Handler)

server.serve_forever()

The above code hosts the login widget on local host at port 8000.

Make sure the login widget HTML and the .py file that contains code to host the widget and present under the same folder structure.

  • Add localhost as the trusted domain on the admin portal at in the admin portal:
    Settings > Authentication > Security Settings > Specify Trusted DNS Domains for API Calls
  • Navigate to the folder where your HTML file and the .py file are present and run the command “python SERVER_FILE_NAME.py”. This command will start the server and renders your login widget at http://localhost:8000/
  • Try to login with a user. Once the user is logged in successfully, you would be navigated to the http://localhost:8000 URL with the authentication token of the user.

Play around with the widget configurations on the admin portal. Make changes to the configurations on the admin portal to see them dynamically getting rendered on the widget.

Connect login widget with specific apps

Widget integration with User-password app to authenticate with username and password

If your web application requires a username and password where the login pages do not require cookies or header information to be passed, use the user-password template to connect your application with CyberArk Identity.

To connect your application with the login widget, the app key of your application should be provided in the login widget JS.

Note: The app key is provided in the Description tab of your app if your app is using a User-Password web app template.

Example:

document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({
                  "containerSelector": ".cyberark-login",
                  "apiFqdn": "acmeinc.my.idaptive.qa",
                  "widgetId": "8fb33728-5e69-47d7-8d87-320e3ae43fa1",
                  "appKey": "aeb0c2ab-9d0c-4c02-a7b7-6b1927e73338"
                });
            });

How it works?

Example:

  • The user enters the username on the login widget that is embedded into website.
  • The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.
  • The user is authenticated against the CyberArk Identity cloud directory user.
  • Once the user gets successfully authenticated, the widget makes a call to the corresponding user-password app (based on app key) and the user’s authentication token is passed to the server.
  • The user then gets re-directed to the URL specified in the app

The URL can be configured in the user-password application as below:

End user experience:

Widget integration with OIDC app to provide SSO:

If your web application uses OIDC for authentication, use the OIDC template to connect your app to provide SSO using the login widget

To connect your application with the login widget, the app key of your application should be provided in the login widget JS.

Note: The app key is provided in the Settings tab of your app if your app is using a User-Password web app template.

Example:

document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({
                  "containerSelector": ".cyberark-login",
                  "apiFqdn": "acmeinc.my.idaptive.qa",
                  "widgetId": "8fb33728-5e69-47d7-8d87-320e3ae43fa1",
                  "appKey": "2827886e-f4e6-4324-a865-730bfab2a06a"
                });
            });

How it works?

**Example:**

Note: This example assumes the customer has configured the authorization code grant in OIDC web app

  • The user enters the username on the login widget that is embedded into website.
  • The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.
  • The user is authenticated against the CyberArk Identity cloud directory user.
  • Once the user gets successfully authenticated, the widget makes a call to the corresponding OIDC app (based on app key) and the user’s authentication token is passed to the server.
  • The OIDC app then re-directs to the resource URL give in the OIDC app configurations.
  • The OIDC client will now make an API call to the authorize endpoint passing the required information
  • The authorization server will redirect to the redirect URL with the authorization code.
  • The OIDC client will now make an API call to the token endpoint passing the required information
  • The authorization server will redirect to the redirect URL with the ID token of the user.

This ID token can be utilized by the client app to provide SSO to the user.

The resource URL and the redirect URL can be configured in the OIDC application as below:

End user experience:

Note: In this example, we are considering Acme Inc to be a banking app.

The above example shows the once end user logs into the Acme Inc web app, the user can do the following:

  • Navigate to the self-service user profile page and view the user details and update them accordingly. The ID token is decoded to get the user details.
  • Navigate to the account summary page to view his transaction details.
  • Navigate to the funds transfer page to perform the transactions.

The ID token generated for the user specifies that the user has authenticated successfully, and he can perform the operations.

Widget integration with OAuth2 client to make Rest API calls to CyberArk Identity platform

Use the OAuth2 client web app template to create an application that allows you to make Rest API calls to CyberArk Identity platform.

Use the success handler function to pass the authentication token to the OAuth server, once the user has authenticated successfully.

Example:

document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({
                  "containerSelector": ".cyberark-login",
                  "apiFqdn": "acmeinc.my.idaptive.qa",
                  "widgetId": "8fb33728-5e69-47d7-8d87-320e3ae43fa1",
                  "success": function (AuthData) { loginSuccessHandler(AuthData) }
                });
            });
           function loginSuccessHandler(AuthData){
             window.location.href = 'http://127.0.0.1:5000/auth?Auth='+data.Auth
           }

Note: The http://127.0.0.1:5000/auth’ is used as an example to demonstrate the usecase.

In the above example, the loginSuccessHandler function is invoked to pass the authentication token to the “/auth” endpoint once the user authentication is successful.

The “/auth” endpoint should now make a HTTPS request to the “/authorize” endpoint by sending the authentication token as bearer token in the headers of the request.

Please refer to the implementation of login widget in the Java-angular web sample app for further information.

How it works?

Note: This example assumes the customer has configured the authorization code grant in OAuth 2 client web app

  • The user enters the username on the login widget that is embedded into website.
  • The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.
  • The user is authenticated against the CyberArk Identity cloud directory user.
  • Once the user gets successfully authenticated, the widget executes the success handler function. The success handler function should be written such that the authentication token is captured. For Example: The success handler function will call the “/auth” endpoint and append the authentication token to the URL.
  • Once the authentication token is capture, use this authentication token to send a request to the “/authorize” endpoint with the authentication token as the bearer token.
  • The authorization server will redirect to the redirect URL with the authorization code.
  • The OAuth client will now make an API call to the token endpoint passing the required information
  • The authorization server will redirect to the redirect URL with the access token of the user.

The access token can now be used to make Rest API calls to the CyberArk Identity platform.
The redirect URL can be configured in the OAuth2 client application as below:

End user experience:

The above example shows the once end user logs into the Acme Inc web app, the user can do the following:

  • Leverage the CyberArk Identity API to update the user information
  • Leverage the CyberArk Identity API for TOTP registration. Later the user can use the TOTP to perform his authentication.
  • Leverage the CyberArk Identity API to change the language settings accordingly.

Note: The OAuth2 Sever app can also be leveraged using the login widget. The functionality would be exactly same except that the access tokens returned by the OAuth2 server app can be leveraged to provide limit the end user’s access to your application.

Widget integration with SAML to make Rest API calls to CyberArk Identity platform

If you web application uses SAML for authentication, use the SAML template to provide SSO using the login widget

To connect your application with the login widget, the app key of your application should be provided in the login widget JS.

Note: The app key is provided in the Settings tab of your app if your app is using a User-Password web app template.

Example:

document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({
                  "containerSelector": ".cyberark-login",
                  "apiFqdn": "acmeinc.my.idaptive.qa",
                  "widgetId": "86115382-9219-4542-a411-fcf8ab0d5a63"
                });
            });