Hosted portal
The hosted setup portal lets your customer's IT admin verify a domain, connect an IdP, pass a test sign-in and set up directory sync without help from your team.
The setup portal is an organization-scoped workflow for a customer’s IT administrator. Its backend supports domain verification, configuring and testing connections, activation and directory setup. This guide describes those implemented interfaces, not a claim that a hosted deployment is available.
Your server creates a short-lived portal link with only the intents needed for that customer. The IT admin configures the IdP; your application consumes profiles and provisioning events.
A connection must pass its test before activation.
Activation needs a verified domain
Section titled “Activation needs a verified domain”The setup portal turns single sign-on on only for a tested connection of an organization with at least one verified domain. An untested connection answers test_sign_in_pending first; with no verified domain, the portal’s activate call answers HTTP 409 with the portal state domain_unverified. Include the domain_verification intent in the portal link, or verify the domain first, so the IT admin can finish.
Activation through the management API (POST /) does not require a verified domain. Sign-ins with an email outside the organization’s verified domains are refused on every path (email_outside_verified_domain).
Boundaries
Section titled “Boundaries”Portal sessions cannot read another organization’s resources. Link redemption and state-changing requests have their own security requirements; a management API key is never a portal browser credential.
Use test sign-ins and Connection Doctor to inspect checks and supported fixes through either the portal or management API. The portal can send fix instructions to a scoped IT contact. A migration-scoped portal session can supply IdP metadata for an imported draft SAML connection that has no metadata yet; submit either its metadata URL or document. Portal links and invites use your verified custom portal hostname when you have one.
Business and Enterprise environments can attach portal profiles to constrain provider choices and required configured attributes. Setup completion is explicit; these backend interfaces do not imply that every control is shipped in a portal frontend.
Use signing-key rotation for acknowledgement, testing and confirmation, and customer IT email for the environment-scoped messages eligible for customization. Platform authentication and security mail remain platform-controlled.
Embed the portal in your app
Section titled “Embed the portal in your app”To show the setup portal inside your own app in an iframe, list your app’s origins in portal_embed_origins with PATCH /v1/environment (set per environment with that environment’s key; at most 20 bare https origins, normalised to lower case without a default port; [] turns embedding off). Then show a portal link with the JavaScript SDK or the React SDK’s AdminPortal component.
- While origins are set, the portal session cookie is issued with
SameSite=None; Secure; Partitioned, so it works in a third-party frame and stays partitioned to your site. Otherwise it staysSameSite=Strict. State-changing requests still need the CSRF header. - The portal reports the allowed origins to its frontend as
embed_origins. - OhAuthCat publishes the origins to the edge for the environment and its active custom portal domains: a change reaches the edge within about 30 seconds, and a removed custom domain is cleared within 15 minutes. With no valid origins the edge sends
frame-ancestors 'none'. - Browsers enforce framing through the
Content-Security-Policy: frame-ancestorsheader on the portal page, which the edge sends (by default'none'). Check that the portal loads in your frame before you rely on it.