Trusted Origins for iFrame embedding

Using Trusted Origins for iFrame embedding, you can 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 that is based on x-frame-options. With the Customizations option, any resource can be embedded 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 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 which is returned by Okta in the frame-ancestors directive of the CSP header.

Whether or not the CSP frame-ancestors directive is enforced depends on the user's browser. Browsers that support CSP frame-ancestors directive enforce it and give it precedence over x-frame-options. In the absence of CSP and x-frame-options, the resource can be embedded by anyone 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 is not in use. We recommend 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 are not 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 Okta 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 Okta resource in an iFrame

These instructions are for embedding a new page or resource in an iFrame using Trusted Origins. If you are 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 uncheck 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 the instructions 1-5 in 1. Embed an Okta sign-in page or Okta 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 Okta resource in an iFrame.

    Don't disable iFrame embedding in Customizations yet. This will keep 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 will need to manually check different 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, uncheck iframe embedding in CustomizationsOtherEnable iFrame Embedding. This will make 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.

FAQs

How are Trusted Origins different from iFrame embedding in Customizations?

The iFrame embedding in Customizations uses x-frame-options. When this option is not enabled, Okta uses the SAMEORIGIN directive and restricts iFrame embedding to the same origin as the Okta org. When this option is enabled, Okta does not send the SAMEORIGIN header, thus any origin can embed Okta resources in an iFrame. Trusted Origins use CSP frame-ancestors directive. This directive specifies which parent pages may embed a page using 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 report-only header as a precaution. This means that the iFrames configured through Trusted Origins will stay in monitoring mode unless you disable iFrame embedding under Customizations.

What should I know before switching 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 cannot 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 display the iFrame in a domain that's different from the org domain and allow the WebAuthn authentication to authenticate users, edit the HTML attribute of the iFrame code with this setting:

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

    Where * is your non-Okta webpage 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 is not displayed in the iFrame even though 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.