Configure custom end-user portals to use the Okta Browser Plugin

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.

Before you begin

The plugin does the following once configured:

  • 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 also 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.

    • /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.

Start this procedure

This procedure contains two parts: configuring your portal as a CORS-trusted origin, and modifying your custom portal HTML.

Use the following steps to 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
    • 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. Once you have finished saving, you must now configure your portal as a CORS-trusted origin. To start, 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:

  6. <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')"/>

  7. Write code similar to the following on https://www.example.com to handle the postMessage response from the iframe. For example:

  8. 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>