Trusted Origins for iFrame embedding

Trusted Origins lets you embed sites, like the Okta sign-in page or Okta-protected resources, in origins that you trust. This prevents your site from being embedded in an untrusted site. It's more secure than the iFrame Embedding option in Customizations, which lets you embed resources into any site.

See Frequently Asked Questions and Known Issues with Trusted Origins for iFrame Embedding.

How it works

Trusted Origins use the Content Security Policy's (CSP) frame-ancestors directive. Its frame-ancestors directive specifies parent pages that may embed a page using an iFrame. Trusted Origins lets you configure an origin that Okta returns in the frame-ancestors directive of the CSP header.

The user's browser determines whether the CSP frame-ancestors directive is enforced. iFrame Embedding is based on x-frame-options. Browsers that support the CSP frame-ancestors directive enforce it and give it precedence over x-frame-options. In the absence of CSP and x-frame-options, anyone can embed the resource into any site. When x-frame-options is set to SAMEORIGIN, the resource can only be displayed in a frame on the same origin as the page itself.

Disabling this feature may break existing iFrames. Verify that your iFrames are working properly by visiting the page that embeds Okta sign-in pages or Okta-resources in an iFrame.

For developer documentation, see Trusted Origins API.

Before you begin

Trusted Origins for iFrame embedding works only when the iFrame embedding under CustomizationsOtherEnable iFrame Embedding isn't in use. Okta recommends that you first embed all Trusted Origins you need and then turn off the Customizations option, if you have enabled it. This ensures that your existing iFrames aren't unintentionally broken.

Start this procedure

You can either create a new Trusted Origin or migrate an existing iFrame to Trusted Origins:

Embed the Okta sign-in page or resource in an iFrame

Embed the Okta End-User Dashboard in an iFrame

Migrate from Customizations iFrame to Trusted Origins

Embed the Okta sign-in page or resource in an iFrame

These instructions are for embedding the Okta sign-in page or Okta-protected resources in an iFrame using Trusted Origins. If you're migrating an existing iFrame from Customizations to Trusted Origins, see Migrate from Customizations iFrame to Trusted Origins.

  1. In the Admin Console, go to SecurityAPITrusted Origins.

  2. Click Add Origin.

  3. Enter the Origin Name and Origin URL in the respective fields.

  4. Select the origin type as iFrame embed (origin). This keeps frame-ancestors in report-only if you enabled iFrame embedding in Customizations.

  5. Disable iFrame embedding in Customizations using either of these methods:
    • Click the iFrame embedding link that appears in the warning message in the Admin Console.
    • Go to CustomizationsOtheriFrame Embedding, and then clear Enable iFrame embedding.

  6. In the Add Origin dialog, click Save.

Embed the Okta End-User Dashboard in an iFrame

  1. Follow steps 1 to 5 in Embed the Okta sign-in page or resource in an iFrame.

  2. In the Add Origin dialog, select the Allows iFrame embedding of the Okta End-User Dashboard option.

  3. Click Save.

Migrate from Customizations iFrame to Trusted Origins

  1. Go to CustomizationsOtherEnable iFrame Embedding and identify all iFrames.
  2. Configure these iFrames using Trusted Origins as described in Embed the Okta sign-in page or resource in an iFrame.

    Don't disable iFrame embedding in Customizations yet. This keeps frame-ancestors in report-only so you can confirm that the new iFrame is working as expected before making it live.

  3. Check for any origins that you might have missed. Manually check the resources that you've embedded through Okta for CSP violations in the browser.
  4. Correct any CSP violations and ensure that all Trusted Origins are working correctly.
  5. Go to CustomizationsOtherEnable iFrame Embedding and clear iFrame embedding. Trusted Origins are now live.