Handles Shopify's managed app installation flow via token exchange, and keeps the embedded session's offline access token fresh.
With managed installation (the default for new Shopify apps), Shopify sends an
id_token JWT on every page load instead of going through the traditional
OAuth authorization code exchange. This plug:
- Verifies the
id_tokenwithShopifex.SessionToken(strict HS256). - If the shop doesn't exist, exchanges the
id_tokenfor an expiring offline access token (RFC 8693) and persists the full token lifecycle (access_token,token_expires_at,refresh_token,refresh_token_expires_at). - If the shop exists but its stored access token is within ~10 minutes of
expiry (
token_expires_at) or already expired — or its stored scopes lack any scope inconfig :shopifex, :scopes(a merchant approved a scope update) — it re-exchanges, which also persists Shopify's current grant. - Otherwise it builds the session from the stored shop directly.
New installs are persisted through the configurable
Shopifex.ManagedInstall.Callbacks hooks (insert_shop/1, after_install/1,
after_exchange/2), so apps can customise shop creation and side effects
without re-implementing token exchange.
Concurrency
Concurrent embedded loads of the same shop (two tabs, a reload during a slow
exchange, several app-load requests fanned out by the admin) are serialized
per shop through Shopifex.TokenRefreshLease — the same lease
Shopifex.Auth.refresh/1 takes — so exactly one of them exchanges the
id_token. The others poll the shop row and build their session from the
pair the exchange persisted, without contacting Shopify; a first install
inserts the row once. The shopifex_token_refresh_leases table is therefore
required by this plug, not only by background refresh (see
docs/upgrading.md). A load that cannot obtain or observe the lease within
config :shopifex, :token_refresh_wait_timeout_ms (15s by default) logs a
warning and exchanges without it. A re-exchange of an existing shop is
written with the same locked compare Shopifex.Auth.refresh/1 uses, so a
pair that a refresh or another exchange persisted meanwhile is kept rather
than overwritten. The lease is held until the exchange, its persistence, the
webhook reconcile and the Shopifex.ManagedInstall.Callbacks hooks have
run, so a hook that calls Shopifex.Auth.refresh/1 for the same shop
synchronously waits out the lease deadline and gets
{:error, :refresh_in_progress}; run such work asynchronously.
Webhooks are reconciled via Shopifex.Shops.configure_webhooks/1 on first
install and on every re-exchange (idempotent self-heal — see that function).
Reconciliation issues one webhookSubscriptions query (plus a create per missing
topic) per re-exchange, i.e. at most once per shop per ~50 min of activity; it
does not run on the hot per-load path that builds the session from a fresh
shop directly.
If no recognised id_token is present, this plug is a no-op — the request
falls through to the legacy OAuth flow (Shopifex.Plug.ShopifySession).
No cookieless
auth_tokenredirect bridge. App Bridge supplies a freshid_tokenon every embedded load, so there is no need to bridge auth across a cookieless redirect — this plug deliberately ships noPhoenix.Tokenredirect branch. If your app issues its own signed-token redirect, keep that as a custom plug clause; the library will not handle it.
Usage
Add this plug to your router pipeline before Shopifex.Plug.ShopifySession:
pipeline :managed_install do
plug Shopifex.Plug.ManagedInstall
end
scope "/auth" do
pipe_through [:shopifex_browser, :managed_install, :shopify_session]
get "/", MyAppWeb.AuthController, :auth
endConfiguration
config :shopifex,
api_key: "your_api_key",
secret: "your_api_secret"Install-time side effects (profile fetch, analytics, snapshots) are
app-specific and belong in your AuthController / shop-creation path, not in
this plug.