Migrating to Attesto from an existing OAuth provider

A checklist for replacing an existing OAuth/OIDC provider (a hand-rolled provider or an ex_oauth2_provider-style library) with the attesto / attesto_phoenix stack.

1. Mount the routes

Add the router macro and mount the endpoints. The well-known documents are always at the host root (RFC 8615); the OAuth endpoints live under your chosen prefix:

use AttestoPhoenix.Router

pipeline :attesto_phoenix_config do
  plug AttestoPhoenix.Plug.PutConfig, otp_app: :my_app
end

scope "/" do
  attesto_routes(pipeline: :attesto_phoenix_config, registration: true)
end

2. Configure the host callbacks

Build an AttestoPhoenix.Config. The recommended production shape is the named behaviours - AttestoPhoenix.ClientStore, AttestoPhoenix.PrincipalStore, AttestoPhoenix.ScopePolicy, AttestoPhoenix.ConsentPolicy, AttestoPhoenix.RegistrationStore, AttestoPhoenix.EventSink - wired into the matching Config keys. See guides/examples.md for minimal configs.

Point the library's global resolver and Ecto-backed stores at the same host:

config :attesto_phoenix, otp_app: :my_app, repo: MyApp.Repo

3. Map your existing client store

Your old provider already has a client table. Point :load_client, :verify_client_secret, :client_id, :client_redirect_uris, and :client_public? at it. You do not need to migrate the rows into a new schema; you need callbacks that read your existing rows.

4. Remove the runtime provider, keep historical migrations

This is the step that trips people up. When you delete the old provider dependency:

• Remove the runtime code - the old provider's plugs, routes, and any use OldProvider.X lines.

• Keep the historical migrations working. Your repo's migration history still references the old provider's tables and, sometimes, helper modules the old provider exposed at migration time. If you delete the dependency outright, mix ecto.migrate on a fresh database fails when it reaches those old migrations.

  Options that keep history runnable:

  • Leave the old migrations as-is and keep a thin compatibility shim for any module they reference, OR
  • Squash the historical migrations into a single baseline that no longer references the removed dependency (only safe once every environment is past those migrations), OR
  • Replace the dependency-specific calls inside the old migration files with the raw SQL they generated, so the migration no longer needs the dependency at all.

  Pick one before removing the dep from mix.exs. Do not remove the dep and discover the break on the next clean deploy.

5. Scope and token claims

Move scope policy into :authorize_scope (or AttestoPhoenix.ScopePolicy) and the principal/claim shaping into :build_principal / :build_userinfo_claims. Attesto owns the JWT/JWKS/DPoP mechanics; your host owns who the subject is and which scopes a client may hold.

6. Verify discovery

Fetch /.well-known/oauth-authorization-server and /.well-known/openid-configuration and confirm every advertised endpoint URL points at a route you actually mounted.

Note for a /mcp/oauth (or any non-/oauth) consumer

If you mount the OAuth endpoints somewhere other than /oauth - for example under /mcp/oauth to avoid colliding with a legacy provider at /oauth - set the mount once:

oauth_path_prefix: "/mcp/oauth"

With that set, the discovery documents and the RFC 7591 registration_client_uri advertise the /mcp/oauth/* paths automatically, and AttestoPhoenix.Config.to_attesto_config/2 passes the resolved token path into the core config for you. A consumer that previously hand-passed token_endpoint_path: "/mcp/oauth/token" into to_attesto_config/2 can drop that argument once :oauth_path_prefix is set, since the resolver now derives it. (Explicit per-endpoint overrides such as :token_path still win if you need a path that does not follow the prefix.)

The bundled attesto_routes/1 macro mounts fixed /oauth/* tails. For this prefix, mount it with prefix: "/mcp" (or put it in a surrounding /mcp scope), so the physical routes and advertised URLs agree. An explicit override such as token_path: "/mcp/oauth/token2" changes metadata only; add a matching host route when using one. The installer accepts only /oauth or a prefix that ends in /oauth, using literal slash-separated segments with letters, digits, _, or -; it rejects other values before changing files.