Dynamic Client Registration

Authagonal implements OAuth 2.0 Dynamic Client Registration (RFC 7591), allowing client applications to register themselves at runtime without administrator involvement.

Enabling the Endpoint

Dynamic registration is disabled by default. Opt in via configuration:

{
  "Auth": {
    "DynamicClientRegistrationEnabled": true
  }
}

Or set Auth__DynamicClientRegistrationEnabled=true as an environment variable. A multi-tenant host can override the setting per tenant through ITenantContext.DynamicClientRegistrationEnabled: a tenant’s own answer wins, and null falls back to the host-wide option.

When enabled, the discovery document advertises the endpoint:

GET /.well-known/openid-configuration

{
  "registration_endpoint": "https://auth.example.com/connect/register"
}

Registering a Client

POST /connect/register
Content-Type: application/json

{
  "client_name": "My App",
  "redirect_uris": ["https://myapp.example.com/callback"],
  "post_logout_redirect_uris": ["https://myapp.example.com/"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "openid profile email offline_access",
  "audiences": ["https://api.myapp.example.com"],
  "allowed_cors_origins": ["https://myapp.example.com"],
  "backchannel_logout_uri": "https://myapp.example.com/oidc/backchannel",
  "frontchannel_logout_uri": "https://myapp.example.com/oidc/frontchannel",
  "frontchannel_logout_session_required": true
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "client_id": "a1b2c3d4e5f6...",
  "client_secret": "xkCd2_base64url...",
  "client_id_issued_at": 1745000000,
  "client_secret_expires_at": 0,
  "client_name": "My App",
  "redirect_uris": ["https://myapp.example.com/callback"],
  "post_logout_redirect_uris": ["https://myapp.example.com/"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "openid profile email offline_access",
  "token_endpoint_auth_method": "client_secret_basic"
}

The client_secret is returned once and cannot be retrieved later. Store it securely. The response is sent with Cache-Control: no-store. client_id is 32 lowercase hex characters, and client_secret_expires_at is always 0 (secrets do not expire). Public clients (none) and private_key_jwt clients get no client_secret in the response. The response echoes only the fields shown: audiences, jwks, jwks_uri, allowed_cors_origins and the logout fields are stored but not returned.

Request Parameters

Defaults & Invariants

• PKCE required: RequirePkce is always true for dynamically registered clients.
• Consent required: RequireConsent is always true, so a user sees the consent screen for a self-registered client even where a statically seeded client would skip it.
• Public clients: token_endpoint_auth_method: "none" produces a client without a secret. PKCE is still required.
• Offline access: requesting scope offline_access implicitly adds refresh_token to grant_types.

Error Responses

Security Considerations

The registration endpoint is unauthenticated, but constrained by design:

• Rate limited: 10 registrations per source address per rolling hour (429 rate_limited), so the client store can’t be flooded. The address is the one the caller cannot choose (the forwarded value is not trusted blindly).
• Grant types restricted: only authorization_code + refresh_token; a registered client always requires a user-mediated flow and can never act as a machine-to-machine client.
• Scopes allowlisted, not inherited: a registrant may declare the five OIDC built-ins and nothing else unless an operator lists a scope in Auth:DynamicClientRegistrationScopes. Existence in the scope store is not permission: a scope exists because some client needs it, not because every anonymous registrant may claim it.
• Admin scope reserved: the authagonal-admin scope (or whatever AdminApi:Scope is set to) is refused, so registration can never produce a client that reaches the admin API.
• Logout URIs validated: backchannel_logout_uri and frontchannel_logout_uri are dereferenced by the server, so they must be external http(s) endpoints: loopback, RFC1918, link-local (including the cloud metadata address) and .internal/.local hosts are refused.
• Bounded records: at most 20 redirect URIs of at most 2048 characters each, so one registration cannot be used to inflate the client store.
• CORS origins derived, not trusted: the stored origins come from the client’s own https redirect URIs, never from the request body.
• PKCE always required, and consent always required, on registered clients.

What it does not constrain, unless the registrant opts in, is the audience. RFC 7591 has no field for one, so a stock registration omits audiences (an Authagonal extension) entirely: the client was never asked, its list is “unset”, and it may name any absolute URI as its resource at the authorization endpoint and receive a token carrying that value as aud. That is deliberate (the MCP authorization spec requires clients to name the MCP server as the resource, and an MCP client is a DCR client), and it makes the resource server responsible for authorizing on scope rather than on iss + aud + sub. Sending audiences, even as an empty list, is an answer and pins the client to it: a non-empty list is the allowlist for resource, and an explicit [] means the client may not name a resource at all. Token exchange is the exception: there an unset Audiences denies outright, so a registered client cannot aim an exchanged token anywhere. See Audiences and resource indicators.

For stronger gating (initial access tokens, mTLS, software statements), front the endpoint with your own middleware or an IAuthHook. Consider disabling dynamic registration entirely and managing clients via the admin API in environments where self-service registration is not a requirement.