Shopifex.Plug.ManagedInstall (Shopifex v3.0.0)

Copy Markdown View Source

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:

  1. Verifies the id_token with Shopifex.SessionToken (strict HS256).
  2. If the shop doesn't exist, exchanges the id_token for an expiring offline access token (RFC 8693) and persists the full token lifecycle (access_token, token_expires_at, refresh_token, refresh_token_expires_at).
  3. 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 in config :shopifex, :scopes (a merchant approved a scope update) — it re-exchanges, which also persists Shopify's current grant.
  4. 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_token redirect bridge. App Bridge supplies a fresh id_token on every embedded load, so there is no need to bridge auth across a cookieless redirect — this plug deliberately ships no Phoenix.Token redirect 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
end

Configuration

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.

Summary

Functions

call(conn, opts)

init(opts)