OAuth Provider

Expose this app as an OAuth 2.0 authorization server.

Configure

require "better_auth"
require "better_auth/oauth_provider"

auth = BetterAuth.auth(
  secret: ENV.fetch("BETTER_AUTH_SECRET"),
  base_url: ENV.fetch("BETTER_AUTH_URL", "https://auth.example.com/api/auth"),
  plugins: [
    BetterAuth::Plugins.oauth_provider(
      scopes: ["openid", "profile", "email", "offline_access"],
      consent_page: "/oauth2/consent",
      allow_dynamic_client_registration: true,
      valid_audiences: ["https://api.example.com"]
    )
  ]
)

Register A Client

Dynamic client registration is disabled by default. Enable allow_dynamic_client_registration and call registration with a session cookie unless allow_unauthenticated_client_registration is enabled.

client = auth.api.register_o_auth_client(
  headers: {"cookie" => session_cookie},
  body: {
    client_name: "Example Client",
    redirect_uris: ["https://client.example.com/callback"],
    token_endpoint_auth_method: "client_secret_post",
    grant_types: ["authorization_code", "refresh_token"],
    response_types: ["code"],
    scope: "openid profile offline_access"
  }
)

Public clients use token_endpoint_auth_method: "none" and must use S256 PKCE.

Authorization Code Flow

Call /oauth2/authorize with response_type=code, a registered redirect_uri, and S256 PKCE parameters. If consent is needed, the endpoint redirects to consent_page with a consent_code.

consent = auth.api.o_auth2_consent(
  headers: {"cookie" => session_cookie},
  body: {
    accept: true,
    consent_code: params[:consent_code],
    scope: "openid profile"
  }
)

The consent scope may be narrower than the requested scope.

tokens = auth.api.o_auth2_token(
  body: {
    grant_type: "authorization_code",
    code: params[:code],
    redirect_uri: "https://client.example.com/callback",
    client_id: client[:client_id],
    client_secret: client[:client_secret],
    code_verifier: verifier
  }
)

Opaque access tokens are returned by default. If a valid resource is supplied, the access token is a JWT and the resource becomes the JWT aud. The default valid audience is the provider issuer URL; when openid is granted, the UserInfo endpoint is also allowed.

Routes

Deprecated aliases remain for one minor release: GET /oauth2/client/:id, GET /oauth2/client, GET /oauth2/clients, PATCH /oauth2/client, DELETE /oauth2/client, GET /oauth2/consents, and GET/PATCH/DELETE /oauth2/consent.

Options

When the JWT plugin is registered, JWT access tokens and ID tokens use its configured signing algorithm. Without the JWT plugin, Ruby falls back to HS256 for compatibility.

Metadata

OpenID metadata is available only when openid is in configured scopes. jwks_uri is advertised only when explicitly configured through advertised_metadata[:jwks_uri], jwks_uri, or jwks[:remote_url].

Organization Integration

OAuth clients can be tied to an active organization or team through the Ruby organization plugin by providing client_reference and, when consent should be scoped to the selected organization, post_login[:consent_reference_id].

auth = BetterAuth.auth(
  secret: ENV.fetch("BETTER_AUTH_SECRET"),
  base_url: ENV.fetch("BETTER_AUTH_URL"),
  plugins: [
    BetterAuth::Plugins.organization(teams: {enabled: true}),
    BetterAuth::Plugins.oauth_provider(
      scopes: ["openid", "read:posts"],
      allow_dynamic_client_registration: true,
      client_reference: ->(info) { info[:session]["activeOrganizationId"] },
      post_login: {
        page: "/select-organization",
        should_redirect: ->(info) { info[:session]["activeOrganizationId"].to_s.empty? },
        consent_reference_id: ->(info) { info[:session]["activeOrganizationId"] }
      }
    )
  ]
)

When client_reference returns an organization id, dynamically registered clients store it as reference_id and do not store user_id. Client list/get/update/delete operations are then scoped through the current client_reference.

When post_login[:consent_reference_id] returns an organization id, consent records and authorization codes carry that reference. A user who already consented for one organization must consent again after selecting a different organization.

Support Boundary

This gem implements the OAuth 2.0/OIDC authorization server behavior from upstream @better-auth/oauth-provider: metadata, registration, authorization, consent, token, introspection, revocation, userinfo, logout, pairwise subjects, PKCE, organization references, and rate limits.

It does not currently expose an equivalent to upstream oauthProviderResourceClient. That upstream client is for protected resource servers: verifying bearer access tokens, generating OAuth protected resource metadata, and returning WWW-Authenticate challenges with resource_metadata.

MCP support in Ruby currently lives in the core MCP plugin (BetterAuth::Plugins.mcp), not in this OAuth provider gem. The upstream OAuth provider MCP tests combine the resource client, MCP SDK transports, and protected-resource metadata helpers. Porting those tests to this gem would require a new public Ruby resource-client API or a dedicated package for protected resource helpers.