Attesto Phoenix

https://hexdocs.pm/attesto_phoenix/
Admin
Attesto Phoenix is an opinionated Phoenix and Ecto OAuth 2.0 and OIDC authorization server built on...
Tokens:27,417
Snippets:168
Trust Score:9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run the installer and generate migration

Source: https://hexdocs.pm/attesto_phoenix

Commands to install attesto_phoenix and generate the database migration.

```shell
mix deps.get
mix attesto_phoenix.install
mix attesto_phoenix.gen.migration --repo MyApp.Repo
mix ecto.migrate
```

--------------------------------

### Install with custom schema prefix and generate migration

Source: https://hexdocs.pm/attesto_phoenix

Installs attesto_phoenix and generates a migration with a custom PostgreSQL schema prefix.

```shell
mix attesto_phoenix.install --schema-prefix oauth
mix attesto_phoenix.gen.migration --repo MyApp.Repo --schema-prefix oauth
```

--------------------------------

### Install with custom OAuth path prefix

Source: https://hexdocs.pm/attesto_phoenix

Installs attesto_phoenix with a custom OAuth path prefix.

```shell
mix attesto_phoenix.install --oauth-path-prefix /mcp/oauth
```

--------------------------------

### Configure client_native? callback

Source: https://hexdocs.pm/attesto_phoenix

Sets the `:client_native?` callback in the `AttestoPhoenix.Config` configuration. The callback returns a boolean indicating whether a client is an installed app; default is `false`. When `true`, the client gets the RFC 8252 profile.

```elixir
config :my_app, AttestoPhoenix.Config,
  client_native?: {MyApp.OAuth, :client_native?}   # (client -> boolean), default false
```

--------------------------------

### Add attesto_phoenix with optional Igniter installer

Source: https://hexdocs.pm/attesto_phoenix

Adds attesto_phoenix and the optional Igniter installer as a dev-only dependency.

```elixir
def deps do
  [
    {:attesto_phoenix, "~> 3.4"},
    {:igniter, "~> 0.6", only: [:dev], runtime: false}
  ]
end
```

--------------------------------

### Generate 3.0, 3.1, and 3.4 upgrade migrations

Source: https://hexdocs.pm/attesto_phoenix

Use these commands in order to upgrade an existing 2.x database to 3.x. Do not use the fresh migration command for existing databases. Follow the stopped-cutover guide before running these.

```shell
mix attesto_phoenix.gen.migration --upgrade 3.0 --repo MyApp.Repo
mix attesto_phoenix.gen.migration --upgrade 3.1 --repo MyApp.Repo
mix attesto_phoenix.gen.migration --upgrade 3.4 --repo MyApp.Repo

```

--------------------------------

### Configure authorization_code_private_context and completion callback

Source: https://hexdocs.pm/attesto_phoenix

Configuration example for attaching a private context function and a completion callback in the AttestoPhoenix.Config. The private context is set at the authorization endpoint and read back at completion. The completion callback must return an error if the host transaction rolls back.

```elixir
config :my_app, AttestoPhoenix.Config,
  authorization_code_private_context: &MyApp.Policy.private_context/1,
  authorization_code_completion: &MyApp.Policy.complete/2
```

--------------------------------

### GET /.well-known/openid-federation

Source: https://hexdocs.pm/attesto_phoenix

Serves the signed OpenID Federation Entity Configuration (application/entity-statement+jwt) built from :federation_authority_hints and :federation_entity_metadata.

```APIDOC
## GET /.well-known/openid-federation

### Description
Serves the signed OpenID Federation Entity Configuration (application/entity-statement+jwt) built from :federation_authority_hints and :federation_entity_metadata.

### Method
GET

### Endpoint
/.well-known/openid-federation

### Response
#### Success Response (200)
- **body** (string) - The signed entity configuration JWT.

#### Response Example
{
  "entity_configuration": "eyJhbGciOiJFUzI1NiJ9..."
}
```

--------------------------------

### GET /oauth/credential_offer/:id

Source: https://hexdocs.pm/attesto_phoenix

Retrieves a credential offer by reference (the credential_offer_uri that a wallet dereferences).

```APIDOC
## GET /oauth/credential_offer/:id

### Description
Retrieves a credential offer by reference (the credential_offer_uri that a wallet dereferences).

### Method
GET

### Endpoint
/oauth/credential_offer/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the credential offer.

### Response
#### Success Response (200)
- **body** (object) - The credential offer object.

#### Response Example
{
  "credential_issuer": "https://example.com",
  "credential_configurations": ["example_credential"],
  "grants": {
    "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
      "pre-authorized_code": "abc123"
    }
  }
}
```

--------------------------------

### GET /oauth/device_verification

Source: https://hexdocs.pm/attesto_phoenix

Serves the verification page where the user enters the user code from the device authorization step.

```APIDOC
## GET /oauth/device_verification

### Description
Serves the verification page where the user enters the user code from the device authorization step.

### Method
GET

### Endpoint
/oauth/device_verification

### Parameters
#### Query Parameters
- **user_code** (string) - Optional - The user code to pre-fill.

### Response
#### Success Response (200)
- **HTML page** - The verification page.

#### Response Example
(HTML content)
```

--------------------------------

### Development commands: mix deps.get, mix precommit, mix test

Source: https://hexdocs.pm/attesto_phoenix

Run these commands in order to set up and test the project. The test command requires Postgres.

```shell
mix deps.get
mix precommit
mix test --include ecto   # requires Postgres

```

--------------------------------

### Configure native_apps options

Source: https://hexdocs.pm/attesto_phoenix

Sets the server-wide `native_apps` options in the `AttestoPhoenix.Config` configuration. `loopback_include_localhost: true` accepts a varying port for `http://localhost/...` redirects; `reject_embedded_user_agents: true` refuses authorization requests from in-app webviews. Both are opt-in and default to `false`.

```elixir
config :my_app, AttestoPhoenix.Config,
  native_apps: [
    loopback_include_localhost: true,
    reject_embedded_user_agents: true
  ]
```

--------------------------------

### Configure AttestoPhoenix in config/config.exs

Source: https://hexdocs.pm/attesto_phoenix

Sets required and optional configuration for AttestoPhoenix in the host application's config.exs. Required keys include issuer, audience, keystore, repo, and principal_kinds. Optional keys cover policy modules, token TTLs, DPoP, mTLS, and resource indicators. The otp_app and repo keys at the top point controllers and Ecto-backed stores at the host application.

```elixir
# config/config.exs
# Points controllers and Ecto-backed stores at the host application.
config :attesto_phoenix,
  otp_app: :my_app,
  repo: MyApp.Repo

config :my_app, AttestoPhoenix.Config,
  # --- required ---
  issuer: "https://auth.example.com",
  audience: "https://api.example.com",
  keystore: MyApp.Keystore,            # implements Attesto.Keystore
  repo: MyApp.Repo,                    # Ecto.Repo for the token stores
  principal_kinds: {MyApp.OAuth.PrincipalStore, :principal_kinds},

  # host policy modules (preferred install surface)
  client_store: MyApp.OAuth.ClientStore,
  principal_store: MyApp.OAuth.PrincipalStore,
  scope_policy: MyApp.OAuth.ScopePolicy,
  consent_policy: MyApp.OAuth.ConsentPolicy,
  claims_provider: MyApp.OIDC.ClaimsProvider,
  event_sink: MyApp.OAuth.Events,

  # --- optional policy ---
  openid_provider: true,
  scopes_supported: ["profile", "email", "read:*", "write:*"],
  protected_resource_scopes_supported: ["read:*", "write:*"],
  send_error: &MyApp.OAuthErrors.render/3,
  #   (conn, status, body_map -> conn), optional custom OAuth error envelope
  client_auth_signing_algs: Attesto.SigningAlg.fapi_algs(),
  client_auth_enforce_fapi_alg_policy: true,
  request_object_policy: Attesto.RequestObject.Policy.generic(),

  # --- optional deployment + features ---
  # Incoming request transport gate only; issuer and advertised endpoint URLs
  # remain HTTPS-only regardless of this value.
  require_https: true,
  trusted_proxies: ["10.0.0.0/8"],     # honor X-Forwarded-* only from these
  access_token_ttl: 900,
  refresh_token_ttl: 1_209_600,
  refresh_token_max_lifetime: nil,      # optional fixed family limit, seconds
  refresh_token_expiration_metadata: false, # experimental refresh-expiration draft03
  refresh_token_rotation_grace_seconds: 60,
  schema_prefix: nil,                   # Ecto/repo connection default/search_path (often `public`)
  sweep_interval_ms: 60_000,
  authorization_code_ttl: 60,
  authorization_grant_id_claim: "https://api.example.com/claims/oauth_grant_id",
  dpop_enabled: true,
  dpop_nonce_required: false,
  mtls_enabled: false,                 # RFC 8705 certificate-bound tokens
  # The terminator must overwrite, never append/forward, the client-cert header.
  # This callback is invoked only from trusted_proxies:
  forwarded_cert_der: &MyApp.TLS.forwarded_client_cert_der/1,
  client_certificate_chain_validated?: &MyApp.TLS.chain_validated?/2,
  token_endpoint_auth_methods_supported: ["private_key_jwt", "tls_client_auth"],
  client_mtls_metadata: &MyApp.OAuth.Clients.mtls_metadata/1,
  mtls_endpoint_aliases: %{
    "token_endpoint" => "https://mtls.auth.example.com/oauth/token"
  },
  registration_enabled: false,         # if true, also set registration callbacks

  # RFC 8707 resource indicators (optional; see below)
  resource_indicators: [
    allowed_resources: ["https://api.example.com/a", "https://api.example.com/b"],
    allowed_resources_for: {MyApp.OAuth, :resources_for}  # optional per-client (client -> [uri])
  ]
```

--------------------------------

### GET /oauth/presentation_request/:id

Source: https://hexdocs.pm/attesto_phoenix

Serves the signed request object for OID4VP presentation. The response is of content type application/oauth-authz-req+jwt.

```APIDOC
## GET /oauth/presentation_request/:id

### Description
Serves the signed request object for OID4VP presentation. The response is of content type application/oauth-authz-req+jwt.

### Method
GET

### Endpoint
/oauth/presentation_request/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the presentation request.

### Response
#### Success Response (200)
- **body** (string) - The signed request object as a JWT.

#### Response Example
{
  "request": "eyJhbGciOiJFUzI1NiJ9..."
}
```

--------------------------------

### Generate complete migration for fresh database

Source: https://hexdocs.pm/attesto_phoenix

Use this command to generate the complete schema migration for a fresh database. It creates the operational tables backing the attesto store behaviours. The command uses the --repo flag to specify the Ecto repository.

```shell
mix attesto_phoenix.gen.migration --repo MyApp.Repo

```

--------------------------------

### GET /oauth/statuslist/:id

Source: https://hexdocs.pm/attesto_phoenix

Serves a signed statuslist+jwt built from the :status_list_store. This is the revocation target referenced by issued credentials.

```APIDOC
## GET /oauth/statuslist/:id

### Description
Serves a signed statuslist+jwt built from the :status_list_store. This is the revocation target referenced by issued credentials.

### Method
GET

### Endpoint
/oauth/statuslist/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the status list.

### Response
#### Success Response (200)
- **body** (string) - The signed status list JWT.

#### Response Example
{
  "status_list": "eyJhbGciOiJFUzI1NiJ9..."
}
```

--------------------------------

### Generate upgrade migrations for 3.0 and 3.1

Source: https://hexdocs.pm/attesto_phoenix

Run these Mix commands to generate the upgrade migrations. The first pair uses the configured schema prefix (or the Ecto default, normally public). The second pair uses a dedicated PostgreSQL schema via --schema-prefix oauth. Remove any legacy :table_prefix setting before running; the generator refuses that key.

```shell
# Use the configured schema_prefix; without one, the migration defers to the
# Ecto migrator/repo default (normally public). Keep that aligned with the
# runtime connection search path:
mix attesto_phoenix.gen.migration --upgrade 3.0 --repo MyApp.Repo
mix attesto_phoenix.gen.migration --upgrade 3.1 --repo MyApp.Repo

# Dedicated PostgreSQL schema:
mix attesto_phoenix.gen.migration --upgrade 3.0 --repo MyApp.Repo --schema-prefix oauth
mix attesto_phoenix.gen.migration --upgrade 3.1 --repo MyApp.Repo --schema-prefix oauth

```

--------------------------------

### GET /.well-known/openid-credential-issuer

Source: https://hexdocs.pm/attesto_phoenix

Returns the Credential Issuer Metadata for the OID4VCI issuer role. This endpoint is mounted when the credential_issuance feature flag is enabled.

```APIDOC
## GET /.well-known/openid-credential-issuer

### Description
Returns the Credential Issuer Metadata for the OID4VCI issuer role.

### Method
GET

### Endpoint
/.well-known/openid-credential-issuer

### Response
#### Success Response (200)
- **body** (object) - Credential Issuer Metadata as defined by OID4VCI.

#### Response Example
{
  "credential_issuer": "https://example.com",
  "credential_endpoint": "https://example.com/oauth/credential",
  "credential_configurations_supported": {}
}
```

--------------------------------

### Implement authorization_code_completion callback

Source: https://hexdocs.pm/attesto_phoenix

Defines the MyApp.Policy module with private_context/1 and complete/2. The complete/2 callback wraps the continuation in a database transaction, revalidates authorization, and rolls back on failure. It must return the continuation's result unchanged.

```elixir
defmodule MyApp.Policy do
  def private_context(context) do
    %{"security_epoch" => epoch_for(context.subject)}
  end

  def complete(context, continuation) do
    MyApp.Repo.transaction(fn ->
      # Lock and revalidate the subject's authorization under the same
      # transaction the token issuance will commit in.
      case still_authorized?(context.subject, context.private_context) do
        true ->
          case continuation.() do
            {:ok, _response, _events} = ok -> ok
            {:error, _oauth_error} = error -> MyApp.Repo.rollback(error)
          end

        false ->
          error =
            AttestoPhoenix.OAuthError.new(
              :invalid_grant,
              "subject authorization is no longer valid"
            )

          MyApp.Repo.rollback({:error, error})
      end
    end)
    |> case do
      {:ok, result} -> result
      {:error, {:error, _} = failure} -> failure
      {:error, reason} -> {:error, reason}
    end
  end
end
```

--------------------------------

### GET /oauth/check_session

Source: https://hexdocs.pm/attesto_phoenix

Serves the check_session_iframe for OpenID Connect Session Management, allowing RPs to detect changes to the OP login session.

```APIDOC
## GET /oauth/check_session

### Description
Serves the check_session_iframe for OpenID Connect Session Management, allowing RPs to detect changes to the OP login session.

### Method
GET

### Endpoint
/oauth/check_session

### Parameters
None

### Response
#### Success Response (200)
- **HTML page** - The check_session_iframe content.

#### Response Example
(HTML content)
```

--------------------------------

### POST /oauth/bc-authorize

Source: https://hexdocs.pm/attesto_phoenix

Starts a CIBA (Client-Initiated Backchannel Authentication) flow for decoupled authentication. The user approves the request out of band, and the client collects tokens at the token endpoint.

```APIDOC
## POST /oauth/bc-authorize

### Description
Starts a CIBA (Client-Initiated Backchannel Authentication) flow for decoupled authentication. The user approves the request out of band, and the client collects tokens at the token endpoint.

### Method
POST

### Endpoint
/oauth/bc-authorize

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be `urn:openid:params:grant-type:ciba`.
- **client_id** (string) - Required - The client identifier.
- **client_secret** (string) - Required - The client secret.
- **login_hint** (string) - Required - Identifier for the user to authenticate.
- **scope** (string) - Optional - Space-delimited list of requested scopes.
- **request** (string) - Optional - Signed authentication request (JWT) following the FAPI-CIBA profile.

### Response
#### Success Response (200)
- **auth_req_id** (string) - The authentication request identifier.
- **expires_in** (integer) - Lifetime of the auth_req_id in seconds.
- **interval** (integer) - Minimum polling interval in seconds.

#### Response Example
{
  "auth_req_id": "...",
  "expires_in": 120,
  "interval": 5
}
```

--------------------------------

### Configure dev endpoint with AttestoPhoenix.DevTLS.https_opts

Source: https://hexdocs.pm/attesto_phoenix

Add this line to config/dev.exs to serve the endpoint over HTTPS using the generated certificate. The function raises if the certificate is missing and never falls back to http.

```elixir
config :my_app, MyAppWeb.Endpoint,
  https: AttestoPhoenix.DevTLS.https_opts(port: 4443)

```

--------------------------------

### Run Ecto migrations

Source: https://hexdocs.pm/attesto_phoenix

Run this command to apply the generated migrations to the database. It is used after generating the migration files.

```shell
mix ecto.migrate

```

--------------------------------

### Configure static resource metadata and resolver

Source: https://hexdocs.pm/attesto_phoenix

Shows configuration for static `resource_metadata` and a resolver function. The resolver is authoritative when present and does not fall back to the static URL when it returns `nil`. The resolver runs once per protected-resource request and must be fast and total.

```elixir
resource_metadata: "https://api.example/.well-known/oauth-protected-resource",
resource_metadata_resolver: {MyAppWeb.ResourceMetadata, :for_request}
```

```elixir
def for_request(%Plug.Conn{request_path: "/alpha"}) do
  "https://api.example/.well-known/oauth-protected-resource/alpha"
end

def for_request(%Plug.Conn{request_path: "/beta"}) do
  "https://api.example/.well-known/oauth-protected-resource/beta"
end

def for_request(_conn), do: nil
```

--------------------------------

### Generate local HTTPS certificate with mix attesto_phoenix.gen.dev_https

Source: https://hexdocs.pm/attesto_phoenix

Run this mix task once to generate a locally-trusted mkcert certificate for development. Required because attestto requires an https issuer and there is no disable-https switch.

```shell
mix attesto_phoenix.gen.dev_https

```

--------------------------------

### Configure build_refresh_principal callback

Source: https://hexdocs.pm/attesto_phoenix

Set the :build_refresh_principal option in the AttestoPhoenix.Config to a callback that checks the principal and session state during refresh. The callback receives the client and a map with refresh context fields; return the principal map to allow refresh or {:error, :invalid_grant} to deny and revoke the family.

```elixir
config :my_app, AttestoPhoenix.Config,
  build_refresh_principal: &MyApp.OAuth.PrincipalStore.build_refresh_principal/2

```

--------------------------------

### Mount Attesto routes with router macro

Source: https://hexdocs.pm/attesto_phoenix

Defines a router module that uses AttestoPhoenix.Router and mounts routes under a scope with a custom pipeline that sets the OTP app.

```elixir
defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  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)
  end
end
```

--------------------------------

### Configure protected pipelines and scopes

Source: https://hexdocs.pm/attesto_phoenix

Defines pipelines for authentication and scope authorization, then applies them to a scope. `AttestoPhoenix.Plug.Authenticate` verifies the Bearer JWT, enforces DPoP and mTLS binding when enabled, and resolves the subject via `:load_principal`. `AttestoPhoenix.Plug.RequireScopes` enforces route-level scope authorization using `Attesto.Scope` grant-form algebra.

```elixir
pipeline :api_protected do
  plug AttestoPhoenix.Plug.Authenticate
end

pipeline :reports_read do
  plug AttestoPhoenix.Plug.RequireScopes, "read:reports"
end

scope "/api", MyAppWeb do
  pipe_through [:api, :api_protected]

  scope "/reports" do
    pipe_through :reports_read
    get "/", ReportController, :index
  end
end
```

--------------------------------

### Enable CIMD for native clients in config

Source: https://hexdocs.pm/attesto_phoenix

Configuration to enable Client ID Metadata (CIMD) for native clients, with allowed hosts and loopback include localhost option. The default CIMD fetcher requires the optional Req dependency. Keep allowed_hosts narrow when clients are known in advance. The localhost option only affects redirect matching, not outbound fetch guard.

```elixir
config :my_app, AttestoPhoenix.Config,
  client_id_metadata: [
    enabled: true,
    allowed_hosts: ["client.example"]
  ],
  native_apps: [loopback_include_localhost: true]
```

--------------------------------

### Configure Plug.Parsers with Attesto body reader

Source: https://hexdocs.pm/attesto_phoenix

Configures the endpoint's Plug.Parsers to use AttestoPhoenix.DuplicateParameterGuard as the body reader to detect repeated parameters before dispatch.

```elixir
plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json],
  pass: ["*/*"],
  json_decoder: Phoenix.json_library(),
  body_reader: {AttestoPhoenix.DuplicateParameterGuard, :read_body, []}
```
Tokens:
Raw