Configure your custom end-user portals to leverage the Okta browser plugin Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005ujxsaq&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fconfigure-your-custom-end-user-portals-to-leverage-the-okta-browser-plugin-2006956534
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Configure your custom end-user portals to leverage the Okta browser plugin
Published: Jan 31, 2018   -   Updated: May 15, 2018

okta-doc-source

Configure your custom end user portals to leverage the Okta browser plugin


Security > API > Trusted Origins

You can configure the Okta browser plugin to behave on your custom end user portal exactly as it behaves in the Okta end user dashboard. When configured, the plugin does the following:

  • The plugin informs the custom portal that it (the plugin) is present. You can configure your custom portal to detect when the plugin is not installed, and then display a banner prompting end users to install the plugin.
  • The plugin makes the following API calls to the Okta server to update its state:
    • /api/plugin/2/sites
    • Retrieves information about the list of sites on your custom end user portal (useful for SSO scenarios).


    • /api/v1/users/me/home/tabs
    • Retrieves information about the location of tabs and apps on the portal in order to construct the Your Apps menu that displays when end users click the blue plugin icon. Screenshot

      MyApps-pluginIcon


    • /api/internal/enduser/home
    • Retrieves information about the currently logged-in user such as the plugin settings that are enabled.


    • /api/plugin/2/hashed-self-service-sites
    • Retrieves information useful for adding apps on-the-fly.


Procedure

This procedure has two parts:

Part Ⓐ – Configure your portal as a CORS-trusted origin
  1. From the Okta Admin console, go to Security > API.
  2. Click the Trusted Origins tab.
  3. Click Add Origin and configure settings: Screenshot

    CustPortal_CORS

    • Name – Enter your organization's Origin name.
    • Origin URL – For example, https://www.example.com.
    • Type
      • CORS – Select this option to allow JavaScript hosted on your websites to make an XMLHttpRequest to the Okta API using the Okta session cookie.
      • Redirect – Ignore this option. It has no effect on this feature.
  4. Click Save.
  5. Proceed to Part Ⓑ.

Part Ⓑ – Modify your custom portal HTML
  1. Modify your custom portal HTML by adding the following hidden frame. This effectively sends a 'pluginVersion'postMessage request to the iframe when the iframe loads:
  2. <iframe id="okta-frame"
    	style="display:none"
    	src="https://example.okta.com/app/UserHome/plugin-info"
    	onload="this.contentWindow.postMessage('pluginVersion', 'https://example.okta.com/app/UserHome/plugin-info')"/>
  3. You then write write code similar to the following on https://www.example.com to handle the postMessage response from the iframe. For example:

  4. window.addEventListener('message', function (event) {
      if (event.origin === 'https://example.okta.com' &&
          event.data && 
          event.data.detected) {
        doSomething(event.data.pluginVersion);
    }});

How it works
  1. The Okta browser plugin examines all frames on the page, detects that there is one frame of the form https://*.okta.com/app/UserHome*, and then informs that frame that it is installed.
  2. The Okta web server receives the web request and validates that the iframe owner origin is trusted (that is, it is https://www.example.com). If trust is validated, the Okta web server responds with a JSP page containing Javascript code that responds to trusted origin postMessage requests with the following JSON:

    {
      detected: true/false
      pluginVersion: x.y.z // if plugin is present
    }
  3. The plugin detects that it is on an /app/UserHome/plugin-info endpoint that loaded successfully, and then updates its state accordingly by making the four API calls described above.
  4. You then write code similar to the following on https://www.example.com to handle the postMessage response from the iframe:

    window.addEventListener('message', function (event) {
      if (event.origin === 'https://example.okta.com' &&
          event.data && 
          event.data.detected) {
        doSomething(event.data.pluginVersion);
      }
    });

Security considerations

Okta requires an authenticated session for this functionality.

The /plugin-info endpoint is denied access if:

  • No trusted origin has been defined by the admin.
  • The request referrer (such as the parent frame) is not in the list of CORS-trusted origins defined by the admin.

Configure a fully working example

To configure a working example of this feature, create a local web server (for example, Node.js server) to host the simple HTML page below. The following example hosts the page on https://example.com HTML.

<html>
<head>
     <script>
       window.addEventListener('message', function (event) {
        if (event.origin === 'https://example.okta.com' &&
              event.data &&
              event.data.detected) {
            document.getElementById('pluginVersion').innerHTML = event.data.pluginVersion;
        }
      });
    </script>
</head>
<body>
  Plugin Detected: <b><span id="pluginVersion"></span></b>
  <iframe id="okta-frame"
          style="display:none"
          src="https://example.okta.com/app/UserHome/plugin-info"
          onload="this.contentWindow.postMessage('pluginVersion', 'https://example.okta.com/app/UserHome/plugin-info')"/>
</body>
<html>

The output from running the above code should be similar to this:

ConfigCustPortal_Output


Post a Comment