Developer reference

my.netquirk.com is the OpenID Connect provider for the Netquirk service network. A service registered as a client sends the user to the authorization endpoint, receives a code at its own redirect URI, and exchanges that code for tokens. The user signs in once, and the service reads the claims it asked for.

Discovery

The issuer publishes its configuration as the OpenID Connect discovery document. A client reads it once and learns the issuer, the endpoints, the scopes the issuer grants, the grants it accepts and the algorithm its ID tokens are signed with.

The discovery document is served at /.well-known/openid-configuration. A client that speaks OAuth 2.0 without OpenID Connect reads the same configuration from /.well-known/oauth-authorization-server. Every path on this page is relative to the issuer host, my.netquirk.com.

Endpoints

/oauth2/authorize

Sends the user here to sign in and approve the request, then redirects back to the registered redirect URI with a code.

/oauth2/token

Exchanges a code, a refresh token or a client credential for an access token, an ID token and a refresh token.

/oauth2/userinfo

Returns the claims for the scopes the user granted.

/oauth2/keys

Publishes the public keys that sign ID tokens and access tokens.

/oauth2/revoke

Revokes a refresh token or an access token the client no longer needs.

/oauth2/par

Accepts a pushed authorization request and answers with a single-use request URI the browser can carry to the authorization endpoint.

/oauth2/device_authorization

Starts the device flow for a client with no browser to redirect, and returns the device code and the code the user types.

/oauth2/logout

Ends the session of the user who is signed in and returns the user to the service.

Signing in

The authorization code flow is the only response type the issuer accepts. The client sends the user to the authorization endpoint with response_type=code, and the issuer redirects back to the registered redirect URI with a code. The client exchanges that code at the token endpoint.

PKCE (RFC 7636) is supported for every client, and S256 is the only challenge method the issuer accepts. An operator can require PKCE for a client that has not asked for it.

The issuer accepts the authorization code, refresh token and client credential grants, the device code grant (RFC 8628) for a client with no browser to redirect, and the token exchange grant.

Scopes

Three scopes are available. openid returns the subject identifier of the user. profile returns the name, the picture and the role claims. email returns the email address and whether it is verified.

The consent screen lists what a client asked for, and the user can withdraw a grant under their own account.

Client authentication

A confidential client authenticates at the token endpoint with HTTP Basic credentials, with a client secret in the form body, with a private key JWT, or with a client certificate. A public client authenticates with no credential at all.

Tokens

ID tokens are signed with EdDSA, which is Ed25519. The public keys are published at /oauth2/keys, and a client picks the key by the key id in the token header. Access tokens are JSON Web Tokens as well.

A client that binds an access token to a key it holds, with DPoP (RFC 9449), gets a thumbprint claim on the token, and every later call with that token has to carry the matching proof.

Refresh tokens are opaque. A client exchanges one at the token endpoint and revokes it at the revocation endpoint when the grant is withdrawn.

The account

A signed-in user manages the account under /account: the password, the email address, the applications that have been granted access, the devices that are signed in, and the billing details. Signing out ends the session, and a client that registered a back-channel logout URI is told when it ends.

Getting a client

A Netquirk operator registers a service as a client. The client record carries the redirect URIs, the allowed scopes, the token endpoint authentication method and the secret, so the registration has to match the service exactly.