Skip to content

OAuth2 client configuration

OAuthClientConfig's fields, the verified TLS every call to the provider runs over, and the bound each call the client makes is held to.

The OAuth2 client reads its provider’s endpoints and its own credentials from OAuthClientConfig, and holds every call it makes to that provider to TLS and to a bound. This page is both.

OAuthClientConfig lives in nest-rs-oauth-client and reads the oauth__client namespace — the OAuth client role has its own crate, so it has its own namespace rather than borrowing the one belonging to the crate that answers who the caller is.

OAuthClientConfig is a validator-validated struct: every URL field must be non-empty (length ≥ 1) or the boot fails loudly. All fields follow the dual-path rule.

FieldEnv varValidation
client_id<PREFIX>_OAUTH__CLIENT__CLIENT_IDlength ≥ 1
client_secret<PREFIX>_OAUTH__CLIENT__CLIENT_SECRETlength ≥ 1
auth_url<PREFIX>_OAUTH__CLIENT__AUTH_URLan https URL
token_url<PREFIX>_OAUTH__CLIENT__TOKEN_URLan https URL
redirect_url<PREFIX>_OAUTH__CLIENT__REDIRECT_URLan https URL, or http on a loopback address in a development or test profile
userinfo_url<PREFIX>_OAUTH__CLIENT__USERINFO_URLan https URL
scopes<PREFIX>_OAUTH__CLIENT__SCOPEScomma-separated list, each an RFC 6749 §3.3 scope-token
authorization_parameters<PREFIX>_OAUTH__CLIENT__AUTHORIZATION_PARAMETERSa JSON object of strings, under the provider’s parameter names — {"access_type":"offline"}; none the client sends itself (state, redirect_uri, …) or sends the token endpoint alone (client_secret, code_verifier, …), none empty or named twice
tls<PREFIX>_OAUTH__CLIENT__TLS_CA_CERT, TLS_CERT, TLS_KEYPEM, each with its _FILE spelling

OAuthClient::new runs validate() first, then holds every URL to TLS, then builds the client. The provider’s three endpoints are https: the authorization endpoint is where the user signs in (RFC 6749 §3.1), the token endpoint receives the client secret and the code (§3.2), and the userinfo endpoint a bearer token (RFC 6750 §5.3). The redirect may also be http on localhost, 127.0.0.1 or [::1] — the loopback exception of RFC 8252 §7.3, which keeps a local http://localhost:3000/callback working — in a declared development or test profile (<PREFIX>_ENV) alone, so staging and production take the code back over https, loopback included. Anything else fails the boot naming the variable, the RFC and the profile, never the URL, which may carry credentials. An OAuthClient::new over a config you composed in code names the field instead, OAuthClientConfig::redirect_url: no variable of the client’s was read for it.

The provider’s certificate is verified against the system’s authorities, or against the ones <PREFIX>_OAUTH__CLIENT__TLS_CA_CERT names, which replace them — an identity provider on a private network signed by your own authority is trusted that way. A provider requiring a client certificate gets TLS_CERT and TLS_KEY. All three are read at the start, so a renewed file takes effect at the next one: rotate it with a rolling restart. Material no handshake could use is refused naming the variable it was read from, or, in a config composed in code, its part of OAuthClientConfig::tls: its authorities, its certificate or its key. No setting turns verification off. The HTTP backend refuses redirects — following them during the token exchange is an SSRF risk per the oauth2 crate’s own guidance, and on a read it could send the bearer token anywhere — and fetch refuses a URL that is not https before anything is sent. Beneath both checks the backend itself speaks https alone, so no URL a provider builds at run time reaches the network in plaintext.

A provider that stops answering does not hold your callback. Every call the client makes — the code exchange, userinfo, and any fetch — carries three bounds, constants on the client:

ConstantValueCovers
OAuthClient::CONNECT_TIMEOUT3 sreaching the provider: the name lookup, the TCP and TLS handshakes
OAuthClient::CALL_TIMEOUT5 sthe whole call, from connecting to the last byte of the answer
OAuthClient::ANSWER_MAX_BYTES64 KiBthe most of an answer read

An identity provider answers each of these in well under a second, so a call past its bound is a provider that is not answering. That is the provider’s outage, not the caller’s failed sign-in, so it fails as AuthError::Unavailable — a 503 (RFC 9110 §15.6.4), filed at warn as every 503 — and its sentence names the endpoint and the bound that ended it:

authentication unavailable: the OAuth provider's token endpoint
(https://github.com/login/oauth/access_token) did not answer within 5s

A token response or a userinfo document is a few KiB, an id_token included, so an answer past 64 KiB is refused the same way — on its Content-Length, or as soon as the streamed body passes the cap — and is never buffered whole:

authentication unavailable: the OAuth provider's userinfo endpoint
(https://api.github.com/user) answered more than 65536 bytes, the most
an OAuth answer is read to

A provider that answers it cannot answer now — a 5xx, or 429 — is unavailable the same way, on the exchange as on a read, and its own Retry-After reaches the caller when it gave one in seconds; an HTTP-date is not converted against this server’s clock. A provider that answers and refuses — a §5.2 error on the exchange, any other status on a read — is the caller’s failure, AuthError::Failed, a 401.

A refused connection, like every failure the client reports, names the endpoint the same way. The endpoint appears as its scheme, host, port and path only (nest_rs::config::endpoint_shown): a query string or credentials in the URL never reach the sentence, and neither does anything the call carried — the client secret, the code, the PKCE verifier, the access token.

The bounds sit under the two nets above them. A callback makes at most three calls through the client (GitHub: the exchange, /user, /user/emails), so a login spends at most 15 s on its provider — inside the guard’s own bound on a strategy, AUTHENTICATE_TIMEOUT (18 s), and the HTTP edge’s request timeout (20 s by default). A provider that stops answering is reported by the client, naming the endpoint, before either of those speaks for it.

  • OAuth2 — the flow this client runs.
  • Social login — every provider composes this client, under its own variables.
  • Writing a strategy — the guard’s net above every strategy’s own bounds.