Configure custom end-user portals with 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.

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

    Retrieves information about the list of sites on your custom end-user portal. This is useful for SSO scenarios.

  • /api/v1/users/me/home/tabs

    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

    Retrieves information about the currently signed-in user, such as what plugin settings are enabled.

  • /api/plugin/2/hashed-self-service-sites

    Retrieves information useful for adding apps on-the-fly.

Procedure

Configure your portal as a CORS-trusted origin

  1. In the 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: Enter the URL for the origin you want to trust. For example, https://example.okta.com.

    • Type

      • CORS: Select this option to permit the JavaScript hosted on your websites to make an XMLHttpRequest to the Okta API using an Okta session cookie.

  4. Click Save.

Modify your custom portal

Next, configure your portal as a CORS-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 condition exist:

  • The admin hasn't defined any trusted origin.
  • The request referrer (such as the parent frame) isn’t in the list of CORS-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.

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