Configure custom portals with the Okta Browser Plugin

You can configure the Okta Browser Plugin to behave on your custom portal exactly as it behaves in the Okta End-User Dashboard.

After you configure the plugin, it informs your custom portal that about its presence. You can configure your custom portal to detect when the plugin isn't installed and prompt end users to install the plugin.

The plugin also makes the following API calls to Okta to update its state:

• /api/plugin/2/sites: This call retrieves information about the list of sites on your custom portal. This is useful for SSO scenarios.
• /api/v1/users/me/home/tabs: This call retrieves information about the location of tabs and apps on the portal. The plugin uses this to construct the Your Apps menu that is displayed when end users click the blue plugin icon.
• /api/internal/enduser/home: This call retrieves information about the currently signed-in user, such as what plugin settings are enabled.
• /api/plugin/2/hashed-self-service-sites: This call retrieves information useful for adding apps as they're needed.

Configure your portal as a trusted origin

You can configure your portal as a trusted origin for requests that go to your Okta Browser Plugin.

Use a specific parent domain

Use a specific parent domain for more secure iFrame embedding.

1. In the Admin Console, go to SecurityAPI.

2. Click the Trusted Origins tab.

3. Click Add Origin and configure settings.

   • Origin name: Enter your organization's origin name.
   • Origin URL: Enter the URL for the origin that you want to trust. For example, https://example.okta.com.
   • Choose Type: Select these iFrame embedding options:
     • iFrame embed: Select this option to allow iFrame embedding of Okta sign-in pages and single-sourcing URLs.
     • Allows iFrame embedding of Okta End User Dashboard: Select this option to allow iframe embedding of the End-User Dashboard
4. Click Save.

Use any parent domain

Use any parent domain for iframe embedding.

1. In the Admin Console, go to CustomizationsOther.

2. In the IFrame Embedding section, select Allow IFrame embedding.

Modify your custom portal

Next, configure your portal as a trusted origin.

1. Modify your custom portal HTML by adding the following hidden iFrame. This sends a pluginVersion postMessage request to the iFrame when the iFrame loads:

   Copy

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

2. Add some JavaScript code to your site to handle the postMessage response from the iFrame. For example:

   Copy

   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 to detect if there's one frame of the form https://*.okta.com/app/UserHome*. The plugin then informs that frame that the plugin is installed.

2. The Okta server receives the request and validates that it trusts the iFrame owner origin. After validating the trust relationship, the Okta server responds with a JSP page containing Javascript code. This code responds to postMessage requests from a trusted origin with the following JSON:

   Copy

   {
     detected: true/false
     pluginVersion: x.y.z // if plugin is present
   }

3. The plugin detects that it's on an /app/UserHome/plugin-info endpoint that loaded successfully. It then updates its state accordingly by making the four API calls to Okta as described earlier.

4. Code similar to the following handles the postMessage response from the iFrame:

   Copy

   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 the following conditions exist:

• The admin hasn't defined any trusted origin.
• The request referrer (such as the parent frame) isn't in the list of trusted origins defined by the admin.

Configure a fully working example

To see a working example of this feature, create a local web server (for example, a node.js server) to host a simple HTML page.

The following example hosts the page on https://example.okta.com.

<leve>
<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>