Gated Marketplace: SSO & Setup

A gated marketplace is a full-page App Marketplace at its own domain, reachable only by your signed-in users. An anonymous visitor is sent to your identity provider first, authenticated, and returned to the exact page they asked for — now signed in and personalized to their account. Gated marketplaces authenticate with SAML single sign-on. This article explains how the sign-in gate works and, in detail, what Partner Fleet handles versus what your team builds.

How the gate works

Every request to a gated marketplace passes through a sign-in gate:

1. A user opens any gated URL — the home page, or a deep link straight to a listing.
2. If they don't have a session, Partner Fleet doesn't render the page. It redirects them to your identity provider (IdP), carrying the page they were trying to reach.
3. Your IdP authenticates the user and returns a signed SAML assertion to Partner Fleet.
4. Partner Fleet validates the assertion against your IdP's certificate, opens a session, and redirects to the original page — now signed in.
5. The session rides subsequent requests, so the user isn't bounced through SSO again until it expires.

Sign-in flow — SAML SSO

A gated marketplace authenticates through your existing Identity Provider (Okta, Entra ID, etc.).

1. A logged-out visitor hits a gated URL → Partner Fleet redirects to your IdP's SSO URL (IdP-initiated), carrying the intended path as RelayState.
2. Your IdP authenticates the user and POSTs a signed SAML assertion to Partner Fleet's Assertion Consumer Service (ACS), echoing the RelayState.
3. Partner Fleet validates the assertion against your IdP's certificate, creates or updates the account and user from the assertion's attributes, opens a session, and redirects to the path carried in RelayState.

What Partner Fleet does vs. what you do

The trust boundary sits between your IdP and Partner Fleet's ACS.

In one sentence: Partner Fleet provides the gated store, the sign-in gate, the ACS that validates your signed SAML assertion, and the session/redirect security around it; you point a domain at it and prove who the user is by configuring your SAML IdP.

Deep links

Because the gate preserves the requested path through the whole round-trip (as RelayState, echoed back by your IdP), you can link straight to a listing from an email or from inside your app. A logged-out user who clicks it signs in once and lands on that listing, not the home page.

SAML configuration

• Partner Fleet exposes an ACS (Assertion Consumer Service) for your standalone SAML provider.
• You configure a standalone Identity Provider in the admin with your IdP SSO target URL and signing certificate. The store won't accept sign-ins until both are present (the gate fails closed otherwise).
• The flow is IdP-initiated: the gate sends the user straight to your IdP; the deep link rides as RelayState and is echoed back to the ACS.

Integration status and account data

A gated marketplace has no embed script and no postMessage — those are embedded features. So integration (install) status and account data get in through server-to-server paths:

• SAML attributes set or refresh the account (and its fields) on each sign-in.
• The Core API (Admin API v2) manages any account and its integration status from your backend, with no user present — the right tool for syncing install state after a user installs or removes an integration. See Core API — Overview.

There's no client-side integrations array here (that's an embed-script feature). For a gated marketplace, drive integration status from your backend via the Core API.

Setup checklist

Admin (your admin team):

1. Open your App Marketplace Developer Settings and set the Delivery mode to Standalone Delivery (non-iframe) — this is the gated delivery.

   Revealing the delivery picker. Changing delivery mode is a significant change, so the picker is hidden by default. To show it, add ?edit_delivery=true to your Developer Settings URL — for example: …/admin/onboarding/stores/in_app_developer_settings?edit_delivery=true&store_id=<your store id>. (A direct navigation path is planned for a future release.)

2. Set the SSO type to SAML, and configure the standalone IdP: IdP SSO target URL + signing certificate.
3. Brand it on Appearance; add Listings; set Buttons & Actions, Permissions, and Audience Filtering (the same configuration as the embedded delivery).

Engineering (your team):

4. Point your domain at the gated store (DNS/CNAME — see Dynamic Domains Configuration).
5. Configure IdP-initiated SAML SSO to the ACS — pass the required identity and account attributes, and echo RelayState so deep links resolve.
6. Test the round-trip: open a gated URL logged-out → confirm you're redirected to your IdP and land back signed in on the requested page.
7. (Optional) Wire install-state sync from your backend via the Core API.

Related

• App Marketplace: Overview — deliveries and the "how data gets in" matrix.
• Dynamic Domains Configuration — pointing a domain/CNAME at the store.
• Core API — Overview — syncing accounts and integration status server-to-server.
• Appearance / Listings / Buttons & Actions / Permissions / Audience Filtering — the shared configuration tabs.