Trusted Origins for iFrame embedding

This is an Early Access feature. To enable it, contact Okta Support.

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 Customization that uses x-frame-options (XFO). The XFO method does not let you distinguish between secure and non-secure origins. Trusted Origins allow you to selectively configure the origins you trust.

How it works

Trusted Origins use Content Security Policy’s (CSP) frame-ancestors directive. CSP protects your data from web attacks such as cross-site scripting and data injection. 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 CSP is enforced or not depends on the browser the user is using. Browsers that support CSP enforce it, those that don’t ignore it and default to the sameorigin policy. For developer documentation, see Trusted Origins API.

Before you begin

This feature works only when the XFO iFrame embedding is not in use (Customizations > Other > Enable iFrame Embedding). Okta recommends that you first embed all Trusted Origins you need and then turn off the XFO option. This ensures that your existing iFrames are not unintentionally broken.

Start this procedure

You can perform the following tasks:

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

2. Embed Okta End-User Dashboard in an iFrame

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

In the Admin Console,

  1. Go to Security > APITrusted 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).

    You also must disable XFO iFrame embedding in Customizations for this setting to work.

  5. To disable XFO iFrame embedding,

    Click the iFrame embedding link displayed in the warning message in the Admin Console.

    OR

    Go to Customizations > Other > iFrame Embedding, and uncheck Allow 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 Procedure 1.

  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. See Embed an end-user home page into an existing portal.

Disable this feature

Disabling this feature may break existing iFrames. You can verify whether 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 the XFO iFrame embedding?

The XFO iFrame embedding uses x-frame-options. When this setting is not enabled, Okta uses the SAMEORIGIN directive and restricts iFrame embedding. When this setting is enabled, Okta does not send the SAMEORIGIN header, thus any origin can embed Okta resources in an iFrame.

The Trusted Origins feature uses CSP frame-ancestors directive. This directive specifies parent pages that 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 XFO method and the Trusted Origins method, Okta does not send CSP frame-ancestors as a precaution. In other words, you must disable the XFO embedding for Trusted Origins to work.

What should I need to know before switching from XFO to Trusted Origins?

In a test org, configure all origins where you require iFrame embedding using Trusted Origins. Disable the XFO embedding 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 Dashboard > Settings are exited out of the iFrame. The enrollment happens outside the iFrame.

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

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