OIDC Endpoints

Ce contenu n’est pas encore disponible dans votre langue.

stubIdP exposes a standard OpenID Connect endpoint set. The base path depends on the runtime:

Runtime	Base URL
Node.js CLI	`http://localhost:8484`
Cloudflare Workers	`https://<worker>.workers.dev`

Discovery

GET {base}/.well-known/openid-configuration

Returns the standard OIDC Provider Metadata document, including all endpoint URLs, supported scopes, response types, and signing algorithms.

Authorization

GET {base}/auth

Initiates the authorization code flow. Standard OIDC query parameters:

Parameter	Required	Description
`client_id`	Yes	Must match the configured client ID
`redirect_uri`	Yes	Must match the configured redirect URI
`response_type`	Yes	`code`
`scope`	Yes	Space-separated scopes (e.g. `openid profile email`)
`state`	Recommended	Opaque value for CSRF protection
`nonce`	Recommended	Value for replay attack prevention

Token

POST {base}/token

Exchanges a grant for tokens. Supports the authorization_code, refresh_token, client_credentials, and urn:ietf:params:oauth:grant-type:device_code grant types.

Request body (form-encoded), for authorization_code:

Field	Description
`grant_type`	`authorization_code`
`code`	Authorization code received from the callback
`redirect_uri`	Must match the original authorization request
`client_id`	Client ID
`client_secret`	Client secret

The response includes access_token, id_token, and optionally refresh_token when offline_access is requested. access_token is opaque by default; set --access-token-format jwt to issue it as a signed JWT carrying identity claims. id_token only carries sub by default (spec-compliant); set --id-token-includes-userinfo-claims to include email/profile/etc. claims directly in it.

Any grant may include a resource parameter (a URI) to request a token audience. The value is echoed back as the aud claim of the issued access token (visible via Token Introspection or when decoding a JWT access token). Defaults to the issuer URL when omitted.

Client Credentials Grant

POST {base}/token

Machine-to-machine token issuance, no end-user interaction. Request body (form-encoded):

Field	Description
`grant_type`	`client_credentials`
`client_id`	Client ID
`client_secret`	Client secret
`resource`	Optional token audience

Returns an access_token scoped to the client (no id_token or refresh_token).

Device Authorization

POST {base}/device/auth

Starts the OAuth 2.0 Device Authorization Grant (RFC 8628) for input-constrained devices. Request body (form-encoded):

Field	Description
`client_id`	Client ID
`scope`	Space-separated scopes

Returns device_code, user_code, verification_uri, verification_uri_complete, and expires_in. The end user visits verification_uri (or verification_uri_complete) to approve the request using stubIdP’s login/consent screens, while the device polls POST {base}/token with grant_type=urn:ietf:params:oauth:grant-type:device_code and the device_code until it receives tokens.

Token Revocation

POST {base}/token/revocation

Revokes an access or refresh token (RFC 7009). Request body (form-encoded):

Field	Description
`token`	The token to revoke
`client_id`	Client ID
`client_secret`	Client secret

Always returns 200 OK, whether or not the token existed.

Token Introspection

POST {base}/token/introspection

Returns metadata about a token (RFC 7662). Request body (form-encoded):

Field	Description
`token`	The token to inspect
`client_id`	Client ID
`client_secret`	Client secret

Response includes active: true with claims such as client_id, exp, iat, aud, and scope when the token is valid, or { "active": false } otherwise.

UserInfo

GET {base}/me

Returns claims about the authenticated user. Requires a valid Bearer access token in the Authorization header.

JWKS

GET {base}/jwks

Returns the JSON Web Key Set used to verify token signatures. Use this endpoint in your application for automatic key discovery.

End session

GET {base}/session/end

Initiates RP-Initiated Logout (OpenID Connect RP-Initiated Logout 1.0).

Parameter	Description
`id_token_hint`	Previously issued ID token. Used to identify the session to end.
`post_logout_redirect_uri`	URI to redirect to after logout. Must match the value configured via `--post-logout-redirect-uri` / `STUBIDP_POST_LOGOUT_REDIRECT_URI`.
`state`	Opaque value passed back to the client in the post-logout redirect.

When --skip-prompt is enabled, stubIdP auto-approves logout without showing a confirmation page and immediately performs back-channel logout notifications before destroying the session.

Dynamic Client Registration

These endpoints are only available when stubIdP is started with --enable-registration.

Register a client (RFC 7591)

POST {base}/reg

Registers a new client. When --registration-initial-access-token is set, the request must include Authorization: Bearer <token>.

Request body (JSON):

Field	Required	Description
`redirect_uris`	Yes	Array of allowed redirect URIs
`client_name`	No	Human-readable client name
`grant_types`	No	Defaults to `["authorization_code"]`
`response_types`	No	Defaults to `["code"]`

The response includes client_id, client_secret, registration_client_uri, and registration_access_token.

Read client configuration (RFC 7592)

GET {base}/reg/{client_id}

Returns the current registration metadata for the client. Requires Authorization: Bearer <registration_access_token>.

Update client configuration (RFC 7592)

PUT {base}/reg/{client_id}

Replaces the client’s registration metadata. The full client object must be supplied (not a partial patch). Requires Authorization: Bearer <registration_access_token>.

Delete a client (RFC 7592)

DELETE {base}/reg/{client_id}

Removes the client registration. Requires Authorization: Bearer <registration_access_token>.

Health

These endpoints are not part of the OIDC spec and are served at the root path regardless of runtime.

Liveness

GET /healthz

Always returns 200 OK when the server process is running. Use this for liveness probes.

{ "status": "ok" }

Readiness

GET /readyz

Returns 200 OK when stubIdP is ready to serve traffic, or 503 Service Unavailable if any check fails. Use this for readiness probes.

Checks:

Check	Always present	Description
`oidc`	Yes	OIDC provider initialized and issuer set
`db`	When DB configured	Database reachable via `SELECT 1`

Example response (all healthy):

{
  "status": "ok",
  "checks": {
    "oidc": { "status": "ok" },
    "db": { "status": "ok" }
  }
}

Example response (DB unreachable):

{
  "status": "error",
  "checks": {
    "oidc": { "status": "ok" },
    "db": { "status": "error", "error": "Connection refused" }
  }
}