Integrate a widget with web apps

You can connect your widget with specific apps based on the type of authorization and authentication requirements your application has.

You need to deploy theses specific applications for them to appear in the widget configuration page for you to select.

Integrate a widget with the User-Password app

If your web application requires a username and password without the need to pass cookies or header information in the signin pages, use the User-Password template to connect your application with CyberArk Identity.

  1. The user enters the username on the authentication widget that is embedded into the website.

  2. The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.

    The user is authenticated against any directory that CyberArk supports.

  3. After the user is successfully authenticated, the widget makes a call to the corresponding User-Password app (based on the app key) and the user’s authentication token is passed to the server.

  4. The user is re-directed to the URL specified in the app.

Integrate a widget with the OIDC app to provide SSO

If your web application uses OIDC for authentication, you can use the OIDC template to connect your app, to provide SSO using the Authentication widget.

The following are the two types of login flows currently supported with the OIDC app:

  • OP-initiated Login

  • RP-initiated Login

Integrate widget with OIDC for an OP-initiated Login

In the OP-initiated login flow, you can link the widget with Open ID app to perform authorization calls using CyberArk Identity or a custom app to the Identity authorization server and then redirect the user to the specified URL.

  1. The user enters the username on the authentication widget that is embedded into the website.

  2. The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.

  3. The user is authenticated against the CyberArk Identity cloud directory user.

  4. After the user is successfully authenticated, the widget makes a call to the corresponding OIDC app (based on the app key) and the user’s authentication token is passed to the Identity authorization server.

  5. When the user tries to access a functionality on the third-party app (for example, a payment gateway), the OIDC app re-directs the user to the resource URL provided in the OIDC app configurations.

  6. The third-party app sends an API call to the authorize endpoint and passes the required information.

  7. The authorization server redirects to the URL with the authorization code.

  8. The third-party app sends an API call to the token endpoint and passes the required information.

  9. The authorization server redirects to the redirect URI with the ID token of the user. This ID token can be utilized by the client app to provide SSO to the user.

  10. The user is redirected to the URL specified in the app.

Integrate widget with OIDC for an RP-initiated Login

In the RP-initiated login flow, you can utilize the widget and link it with the Open ID app to perform authorization calls using the widget to the Open ID authorization server.

  1. The user enters the username on the authentication widget that is embedded into the website.

  2. The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.

  3. The user is authenticated against the CyberArk Identity cloud directory user.

  4. After the user is successfully authenticated, the widget sends an authorization request to the authorization server with the required details.

  5. As the user is already authenticated with the server, the server redirects the user with an authorization code.

  6. The OIDC client on the customer's server uses this authorization code to send a request for access tokens.

  7. The authorization server validates the authorization code and returns the ID and access tokens to the customer's server.

  8. The ID and access tokens are utilized to redirect the user to the URL specified in the app.

Deploy a widget integrated with an OIDC app

After the widget is integrated with the OIDC app, while deploying the widget, provide the required parameter values in the downloaded HTML file.

For RP-initiated flow, provide values for the following:

  • redirect_uri: The landing page URL to redirect the user to, after the authorization is complete

  • scope: A scope is a named entity which defines the endpoint(s) that a client may access such as name, email, etc. Scopes are used in the flow where the user is prompted to grant scope authorization. For more details, see the following HTML code.

<html>
    <head>
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <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://techpubs.my.idaptive.qa/vfslow/lib/uibuild/standalonelogin/css/login.css">
        <!-- Below Line imports the required javascript for the widget -->
        <script src="https://techpubs.my.idaptive.qa/vfslow/lib/uibuild/standalonelogin/login.js"></script>
        <script type="text/javascript">
           /* 
               LaunchLoginView method is used to render the widget with 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 send to "widgetId" configuration so that widget renders with configuration saved in the admin portal.

               =>(Optional) Make your login page 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 LaunchLoginView. Now users can visit your login page directly with no query string and it will direct to your application
                   after authentication is complete.
                Please refer the below link for more information.
                https://identity-developer.cyberark.com/docs/authentication-widgets
           */
		   var widgetHandler = {};
            document.addEventListener('DOMContentLoaded', function () {
                LaunchLoginView({"containerSelector":".cyberark-login","apiFqdn":"techpubs.my.idaptive.qa","widgetId":"dea85524-30b5-48d2-8be8-f966b5feed42","redirect_uri":"http://www.google.com","scope":"email","code_challenge":"","code_challenge_method":""});
            });
			
           
        </script>
    </head>
    <body class="cyberark-login" style="">
    </body>
</html>

For PKCE grant , the widget supports Authorization code grant and Authorization code flow. These changes are applicable for both the embedded and the CyberArk Identity hosted Authentication widget and MFA widget.

Integrate a widget with the OAuth2 app to make REST API Calls

If your web application needs to make REST API calls, you can use Custom OAuth2 Client to connect your app using the Authentication widget.

  1. The user enters the username on the authentication widget that is embedded into the website.

  2. The corresponding MFA is fetched for the user and displayed, and the user enters the required MFA challenges.

  3. The user is authenticated against the CyberArk Identity cloud directory user.

  4. After the user is successfully authenticated, the widget executes the success handler function.

    Write the success handler function to capture the authentication token.

  5. The widgetHandler.onLoginSuccess function is invoked to pass the authentication token to the “/auth” endpoint.

  6. The “/auth” endpoint sends the authentication token as bearer token in the headers of the request, to make an HTTPS request to the “/authorize” endpoint.

  7. The authorization server redirects to the redirect URL with the Authorization code. The OAuth client makes an API call to the token endpoint passing the required information.

  8. The authorization server redirects to the redirect URL with the access token of the user.

  9. Use this access token to make Rest API calls to the CyberArk Identity platform. The screenshot below shows the user experience when widget is integrated with an app that has OAuth flow.

    In the above example, you can leverage the CyberArk Identity API to update user information, TOTP registration, and change language settings as needed.

    You can leverage the OAuth2 Sever app using a widget in similar ways. In addition, you can limit the end user’s access to your application using the access tokens returned by the OAuth2 server app .