Deploy a widget

You can deploy a widget either by self hosting or by using CyberArk hosting.

Difference between an embedded widget and the CyberArk Identity hosted pages

Features of embedded widgets and CyberArk Identity hosted pages

Feature

Embedded widget

CyberArk Identity hosted pages

Single sign-on

  • Single sign-on works for the embedded widget only when the widget cookie is set.

  • The sameSite value for this cookie is None, and thus it enables cross-origin communications.

  • The widget collects and shares the user credentials in an application from one origin and then sends them to another origin, which can present specific security vulnerabilities, including the possibility of a phishing attack. To avoid this, allowlist the third-party domain and enable cross-origin authentication in the browser.

  • To mitigate replay attacks, CyberArk Identity sends Cross-Site Request Forgery (CSRF) tokens for every API call.

  • The single sign-on works out-of-the-box for hosted pages.

  • There is no possibility of phishing attacks because the authentication pages are hosted on CyberArk Identity. Therefore, there is no transfer of credentials from one origin to another.

MFA

The supported MFA mechanisms are email OTP, SMS, phone call, password, security questions, OATH OTP, mobile push, QR code, and FIDO2

Supports all the MFA mechanisms.

Login protocols

Supports external IdP authentication using OIDC. Doesn't support the following login methods:

  • Integrated Windows Authentication/Client-Based Authentication (IWA/CBA)

  • External IdP authentication using SAML

  • Social login

Supports external IdP authentication using OIDC/SAML and social login.

Doesn't support the IWA/CBA login method.

Mobile apps

Embedded widgets are deemed unsafe for third parties and should not be implemented.

It is more secure to use the native app authorization requests. This ensures the users that they are entering credentials in the right domain.

It also enables using the user's current authentication state, thus enabling SSO.

Customizations

The CSS of the widget can be overridden to provide extensive customization.

Customization is limited.

Passkeys

Not supported as an authentication factor.

Supported as an authentication factor.

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

Link the CyberArk Identity hosted widget

  1. Go to Apps & Widgets > Widgets, then select a configured widget or create one with your own customizations.

  2. In the Get Started tab of the widget configuration, select the specific web app to redirect the user to the application configured in the tenant. For more details, see Integrate a widget with the OIDC app.

  3. In the widget configuration, if you did not select an application from the drop-down list in the Get started tab, you can go to the Deploy tab and edit the success handler function to provide the path for the application. The success handler determines the destination page for the user after a successful authentication.

  4. Save the widget and copy the login page URL in the widget configuration. The URL redirects the user to the widget.

    For the MFA widget, the login page URL includes the username as well.

Advantages of linking a CyberArk Identity authentication page

  • No code approach - The customer doesn't require to write code, integrate or deploy.

  • Unique user login experience for all the applications

  • End-to-end security is maintained by CyberArk Identity.

  • No Cross-Origin Resource Sharing (CORS) or third-party cookie-blocking issues.

  • Low-level security for embedded login option at the browser level.

  • SSO is an out-of-the-box feature.

  • No maintenance or upgrade issues.

  • According to the Internet Engineering Task Force (IETF), authorization requests from native apps, such as mobile applications, should only be made through external user agents, primarily the user's browser. Using the browser to make native app authorization requests results in better security.

Embed the widget into your web app

You can download a full screen authentication widget HTML using the Download HTML button from the Deploy tab in the widget configuration section.

  1. Go to Apps & Widgets > Widgets and select a configured widget or create one with your own customizations.

  2. In the Get Started tab, select the web app where you want to embed the widget. For more details, see Integrate a widget with the OIDC app.

  3. In the configuration editor, enter widgetHandler.onLoginSuccess as shown in the following screen.

    You can use either the web app or the success handler. If the web app and success handler are provided at the same time, the success handler takes preference over the web app.

  4. Copy the downloaded HTML content either to a Python IDE or to Notepad++.

    The following is a sample of the HTML content. Enter the widget_id and the tenant_id in the sample HTML code. Add the <link> tag to link the CSS files to the HTML code and the <script> tag to import the javascript of the widget.

    <html>

    <head>

    <meta http-equiv="X-UA-Compatible" content="IE=edge" />

    <meta charset="utf-8">

    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />

    <!-- Below Line imports the required css for the widget -->

    <link rel="stylesheet" type="text/css" href="https://<tenant_id>.id.integration-cyberark.cloud/vfslow/lib/uibuild/standalonelogin/css/login.css">

    <!-- Below Line imports the required javascript for the widget -->

    <script src="https://<tenant_id>.id.integration-cyberark.cloud/vfslow/lib/uibuild/standalonelogin/login.js"></script>

    <script type="text/javascript">

    /*

    LaunchLoginView method is used to render the widget with the provided configuration.

    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.

    The widgetId should be sent to "widgetId" configuration so that widget renders with configuration saved in the admin portal.

    =>(Optional) Make your login page to always launch one app

    If your custom login HTML is only being used for one application, you can configure that application key directly in the page.

    In the CyberArk Identity Admin Portal, go to the app's Settings tab and find the App Key field. Include that value as the "appKey" config option when calling the LaunchLoginView method. Now users can visit your login page directly with no query string and it will direct it to your application after authentication is complete.

    Please refer the below link for more information.

    https://docs.cyberark.com/Idaptive/Latest/en/Content/Widgets/Manage-widgets.htm

    */

    var widgetHandler = {};

    document.addEventListener('DOMContentLoaded', function () {

    LaunchLoginView({"containerSelector":".cyberark-login",

    "apiFqdn":"<tenant_id>.id.integration-cyberark.cloud",

    "widgetId":"<widget_id>",

    "success":function(loginResponse) { widgetHandler.onLoginSuccess(loginResponse) }});

    });

     

    widgetHandler.onLoginSuccess = function (loginResponse) {

    <!-- Navigate to the localhost and display the login response -->

    window.location.href = 'http://localhost:8000';

    document.write(loginResponse);

    };

    </script>

    </head>

    <body class="cyberark-login" style="">

    </body>

    </html>

    In the above code snippet, the LaunchLoginView method contains the following parameters:

    LaunchLoginView parameters

    Parameter Name

    Description

    containerSelector

    The class in which the widget has to load. Example, cyberark-login.

    apiFqdn

    Fully qualified domain name of your tenant.

    widgetId

    Unique ID for the widget. You can copy the valid of the Widget ID in the Get started section.

    success

    Once the user is authenticated, the success parameter indicates where the user is redirected to.

    username (for MFA widget only)

    Unique identifier or login credential that a user provides to authenticate themselves.

  5. Host the authentication widget on your local host by creating a simple Python server as shown below. Enter the name of the authentication widget HTML file in self.path variable.

    import http.server
    import socketserver
    
    class MyRequestHandler(http.server.SimpleHTTPRequestHandler):
    	def do_GET(self):
    		if self.path == '/':
    			#Enter the name of the authentication widget HTML file
    			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()

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

  6. Navigate to the folder location where your HTML file and the .py file are stored and run the command python SERVER_FILE_NAME.py.

    This command starts the server and renders your authentication widget at http://localhost:8000/.

  7. Log in as a user.

    Once you are logged in successfully, you are redirected to the http://localhost:8000 URL and the loginResponse data is displayed accordingly.

    Make changes to the configurations on the Admin Portal to see them dynamically rendered on the widget.

    The widget loads in the container that is assigned to it. Any CSS added to the container in which the widget is loaded also affects the widget display.