Trusted Origins for iFrame embedding

Allow origins that you trust to embed Okta sign-in pages and Okta resources. This method is more secure than the current iFrame Embedding option in Customizations, which is based on x-frame-options. With the Customizations option, you can embed any resource into any site. However, with Trusted Origins, you can ensure that only the origins you trust can embed your resources.

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

For developer documentation, see Trusted Origins API.

Before you begin

Trusted origins for iFrame embedding work 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:

1. Embed an Okta sign-in page or resource in an iFrame

2. Embed Okta End-User Dashboard in an iFrame

3. Migrate from Customizations iFrame to Trusted Origins

1. Embed an Okta sign-in page or resource in an iFrame

These instructions are for embedding a new page or resource in an iFrame using Trusted Origins. If you're migrating an existing iFrame from Customizations to Trusted Origins, see 3. Migrate from Customizations iFrame to Trusted Origins.

In the Admin Console:

  1. Go to SecurityAPITrusted Origins tab.

  2. Click Add Origin.

  3. In the Add Origin dialog, enter Origin Name and Origin URL.

  4. Select the origin type as iFrame embed (origin).

    This keeps frame-ancestors in report-only if you have enabled iFrame embedding in Customizations.

  5. Disable iFrame embedding in Customizations:

    Click the iFrame embedding link displayed in the warning message in the Admin Console, or go to CustomizationsOtheriFrame Embedding, and clear Enable iFrame embedding.

  6. Back in the Add Origin dialog, click Save.

You've now enabled an Okta sign-in experience or an Okta-protected resource in an iFrame.

2. Embed Okta End-User Dashboard in an iFrame

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

  2. Back in the Add Origin dialog, check the Allows iFrame embedding of the Okta End-User Dashboard box.

  3. Click Save.

You've now enabled Okta End-User Dashboard in an iFrame. You can also customize the embedded dashboard.

3. Migrate from Customizations iFrame to Trusted Origins

  1. Identify all iFrames configured through CustomizationsOtherEnable iFrame Embedding.

  2. Configure these iFrames using Trusted Origins as explained in 1. Embed an 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 you might have missed. You need to manually check the resources you've embedded through Okta for CSP violations in the browser.

  4. Correct any CSP violations.

  5. Once you ensure that all trusted origins are working properly, clear iframe embedding in CustomizationsOtherEnable iFrame Embedding. This makes all Trusted Origins live.

Disable this feature

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


How are Trusted Origins different from iFrame embedding in Customizations?

The iFrame embedding in Customizations uses x-frame-options. Trusted Origins use the CSP frame-ancestors directive. This directive specifies which parent pages may embed a page using an iFrame.

  • Not enabled: Okta uses the SAMEORIGIN directive or CSP frame-ancestors and restricts iFrame embedding to the same origin as the Okta org.
  • Enabled: Okta doesn't send the SAMEORIGIN header, and any origin can embed Okta resources in an iFrame.

What if my org has both types of embedding enabled?

If your org has iFrame embedding enabled using both the Customizations option and the Trusted Origins method, Okta sends CSP frame-ancestors in the report-only header as a precaution. This means that the iFrames configured through Trusted Origins stays in monitoring mode unless you disable iFrame embedding under Customizations.

How do I prepare to switch iFrames from Customizations to Trusted Origins?

In a test org, configure all origins where you require iFrame embedding using Trusted Origins. Disable the Customizations option, and make sure that the newly configured iFrames are working properly. Then repeat the same procedure in your production org.

Known Issues

  • Third-party integrated URLs don't work with iFrame embedding if the third-party app doesn't allow it. For example, you've integrated a Salesforce instance in your Okta org. If the Salesforce app doesn't allow iFrame embedding, you can't embed the app in an iFrame using Trusted Origins.

  • The third-party app must also support iFrame embedding. If it relies on cookies for session management, the cookie must be Secure and have SameSite=None to work in Chrome.

  • Enrolling in or verifying with a WebAuthn factor doesn't work when this feature is enabled. Hosting the iFrame in a domain that's different from the org domain causes the WebAuthn authentication to fail. This is because WebAuthn is designed to block authentication across different domains. To allow the WebAuthn authentication to authenticate users, edit the HTML attribute of the iFrame code with this setting:

    <iframe src="..." allow="publickey-credentials-get *" />

    This displays the iFrame in a domain that's different from the org domain. The * represents your non-Okta web page domain.

  • End users enrolling in an authenticator from the embedded End-User DashboardSettings are exited out of the iFrame. The enrollment happens outside the iFrame.

  • If an embedding app has its own CSP, modify it appropriately to allow the Okta org in its frame-src directive.

  • If the browser doesn't support CSP, it defaults to x-frame-options. Check the browser documentation to find out whether it supports CSP.

  • If an embedded Okta Access Gateway (OAG) resource has x-frame-options set to SAMEORIGIN, the resource doesn’t appear in the iFrame. This fails even when the user successfully signed in.

  • The resource isn't displayed properly in an iFrame if the CSP header is missing.

  • Adding too many trusted origins can cause the HTTP header size to exceed the limit allowed by server software such as NGINX. In such cases, you may need to update the default server limits or reduce the number of trusted origins in Okta.