Authentication flow

Overview

This vignette walks through what happens when a user signs in through oauth_module_server(). It explains the main OAuth 2.0 and OpenID Connect (OIDC) steps in package terms, so you can follow the flow without needing deep protocol knowledge.

For a concise quick-start (minimal and manual button examples, options, and security checklist) see: vignette("usage", package = "shinyOAuth").

For an explanation of logging key events during the flow, see: vignette("audit-logging", package = "shinyOAuth").

What happens during the authentication flow?

shinyOAuth handles the OAuth 2.0 Authorization Code flow, plus optional OIDC checks, from start to finish. Below is the sequence of steps and why each one matters.

1. First page load: set a browser token

On the first load of your app, the module asks the browser to set a small random cookie (SameSite=Strict by default; Secure when required by HTTPS or SameSite=None).

This browser token is mirrored to Shiny as an input. Its purpose is to ensure that the same browser that starts login is the one that comes back after the redirect. If the browser cannot create or read this cookie bridge (for example because cookies are blocked or Web Crypto is unavailable), the module surfaces browser_cookie_error and stops before login continues. If the mirrored token looks invalid, shinyOAuth rejects it, records the event, and asks the browser to generate a fresh token before login or callback processing continues.

If oauth_module_server(auto_redirect = TRUE), an unauthenticated session triggers immediate redirection to the provider authorization endpoint.

If oauth_module_server(auto_redirect = FALSE), you manually call $request_login() (e.g., when your user clicks a button).

3. Build the authorization URL (`prepare_call()`)

To redirect the user to the provider, the module builds an authorization URL from the provider’s authorization endpoint. The URL includes a few values that keep the flow linked to the right session and protect the callback:

State: a random value used to link the callback to this login attempt and help block forged callbacks; shinyOAuth also seals extra context into it
PKCE: a code_verifier and matching code_challenge that prove the same browser session finishes the flow
Nonce (OIDC): a random value that is checked again when validating the ID token

shinyOAuth seals the state by storing extra context inside an encrypted and authenticated payload. That payload contains:

state, client_id, redirect_uri
requested scopes
provider fingerprint (issuer/auth/token URLs)
client-policy fingerprint for callback-time policy binding
issued_at timestamp
observability metadata like an internal trace id

Sealing the state helps prevent tampering, stale callbacks, and mix-ups with other providers or clients.

On the server side, the package also stores a few one-time callback values in the state store (for example a cachem backend), under a derived key based on the plain state value:

browser token
code_verifier
nonce (OIDC)

These values are used later during callback validation.

If the client has authorization_request_mode = "request", shinyOAuth switches from plain query parameters to a signed JWT-based authorization request. This is the JAR pattern (RFC 9101). In that mode, the package builds a Request Object JWT containing the OAuth authorization parameters that would otherwise appear directly on the browser URL. shinyOAuth signs these Request Objects, but does not encrypt them as JWE, so they are protected from tampering but their contents are not hidden.

If the provider has a par_url configured, the module uses Pushed Authorization Requests (PAR, RFC 9126) before redirecting the browser. In that mode, the authorization request is first sent server-to-server to the provider’s PAR endpoint as a form-encoded POST. The browser is then redirected with only client_id and a request_uri handle, so the sealed state, redirect_uri, and other authorization parameters do not need to appear in the browser URL.

4. App redirects to the provider

Without JAR and without PAR, the browser of the app user is redirected to the provider’s authorization endpoint with the usual OAuth query parameters: response_type=code, client_id, redirect_uri, state=<sealed state>, PKCE parameters, nonce (OIDC), scope, claims (OIDC, when configured via oauth_client(claims = ...)), acr_values (OIDC, when required_acr_values is set on the client), plus any configured extra parameters.

With JAR enabled but without PAR, the browser is still redirected to the provider’s authorization endpoint, but the URL now carries the signed Request Object instead of the raw authorization parameters. In practice, the redirect contains client_id plus request=<signed JWT>.

With PAR enabled, the browser is still redirected to the provider’s authorization endpoint, but the front-channel URL contains only the PAR handle: client_id and request_uri. If JAR is also enabled, the signed Request Object is what gets pushed to the PAR endpoint, and the browser still sees only client_id plus request_uri.

5. User authenticates and authorizes

Once at the provider’s authorization page, the user is prompted to log in and authorize the app to access the requested scopes.

6. Provider redirects user back to the app

The provider redirects the user’s browser back to your Shiny app (your redirect_uri), including the code and state parameters, and optionally RFC 9207 iss, plus error, error_description, and error_uri on failure.

7. Callback processing & state verification (`handle_callback()`)

Once the user is redirected back to the app, the module processes the callback. In plain terms, it checks that the callback belongs to the login attempt that started earlier and only then continues to token exchange. The main checks are:

Wait for a usable browser token input if it has not reached Shiny yet; when the cookie bridge fails, the module surfaces browser_cookie_error instead of attempting authentication without that binding
Enforce callback query size caps before and after parsing to protect against unusually large or abusive callback inputs on sensitive parameters such as code, state, error, error_description, error_uri, and iss
Validate the callback iss query parameter against the provider’s configured/discovered issuer so the callback must come from the expected provider (per RFC 9207). When oauth_client(enforce_callback_issuer = TRUE) is enabled, callbacks that omit iss are also rejected before token exchange. A mismatch produces an issuer_mismatch error; a missing required iss produces an issuer_missing error and corresponding audit event
If the callback is an error response (?error=...), still require a valid state parameter and browser-token binding before showing the provider error. That way, attacker-controlled error values are not trusted on their own. The provider’s error_uri is only surfaced when it is an absolute HTTPS URL
Decrypt and verify the sealed state, making sure it is authentic and still fresh
Check that embedded context matches the expected client and provider
Fetch and immediately delete the one-time state entry from the configured state store
- If the entry is missing, malformed, or deletion fails, the flow aborts with a shinyOAuth_state_error
- Audit events are emitted on failures (e.g., state_store_lookup_failed, state_store_removal_failed)
- In multi-worker deployments, shared state stores are expected to provide an atomic $take() method for single-use semantics. Without that, shinyOAuth rejects shared stores by default unless the operator explicitly opts into the weaker replay-risk fallback with options(shinyOAuth.allow_non_atomic_state_store = TRUE)
Verify that user’s browser token matches the previously stored browser token
Ensure PKCE components are available when required

Note: in asynchronous token exchange mode, the module may pre‑decrypt the sealed state and prefetch plus remove the state store entry on the main thread before handing work to the async worker, preserving the same single‑use and strict failure behavior.

8. Exchange authorization code for tokens

Once the callback checks pass, the module sends the authorization code to the token endpoint to obtain tokens.

A POST request is made to the token endpoint with grant_type=authorization_code, the code, the redirect_uri, and the code_verifier (PKCE). Client authentication depends on how the provider expects the client to identify itself: public (client_id only), HTTP Basic (client_secret_basic), body params (client_secret_post), JWT-based assertions (client_secret_jwt, private_key_jwt), or mTLS when configured. Most users only need to configure the client correctly; shinyOAuth builds the right request from there.

When the client is configured with dpop_private_key, shinyOAuth also attaches a DPoP proof to the token request. For authorization-code exchange and refresh, if the authorization server responds with a DPoP-Nonce challenge, shinyOAuth caches the supplied nonce and retries the token request once with a fresh DPoP proof that includes it. Generic transport and HTTP retries still stay disabled for these non-idempotent token requests, so the package does not replay them beyond that RFC 9449 nonce handshake. The response must include at least access_token. Malformed or error responses abort the flow.

After a successful response, shinyOAuth also checks two basic things:

If the token response includes scope, shinyOAuth can reconcile it against the requested scopes (defaults to strict enforcement; configurable via the client scope_validation setting)
If the provider was configured with a non-empty allowed_token_types, the token response must include token_type and its value must be one of the allowed types (case-insensitive, e.g., Bearer)

What changes when mTLS is enabled (RFC 8705)

When the provider uses mutual TLS (token_auth_style = "tls_client_auth" or "self_signed_tls_client_auth"), shinyOAuth sends the configured client certificate on authorization-server requests and prefers any discovered mtls_endpoint_aliases.

Certificate-bound access tokens are a separate RFC 8705 policy. When the provider advertises tls_client_certificate_bound_access_tokens = TRUE and the client opts in with mtls_request_certificate_bound_access_tokens = TRUE, shinyOAuth prefers the mTLS endpoints for authorization-server requests even when token_auth_style itself is not an mTLS auth style, and then treats the resulting access tokens as certificate-bound:

For authorization-server requests such as PAR, authorization-code exchange, refresh, introspection, and revocation, shinyOAuth sends the configured client certificate on the TLS connection and prefers any discovered mtls_endpoint_aliases
For protected-resource requests such as client_bearer_req() calls to downstream APIs, and for userinfo when it is acting as a certificate-bound resource, shinyOAuth checks that the token’s cnf.x5t#S256 thumbprint matches the configured certificate before sending the request

What changes when DPoP is enabled (RFC 9449)

When the client is configured with dpop_private_key, shinyOAuth adds DPoP proofs to token requests and later protected-resource requests:

Authorization-code exchange and refresh calls to the token endpoint carry a DPoP proof. If the authorization server responds with a DPoP-Nonce challenge, shinyOAuth retries once with a fresh proof that includes the supplied nonce, then reuses the most recently learned authorization-server nonce on later token requests until the server rotates it
Later get_userinfo() calls and downstream client_bearer_req() requests also attach DPoP proofs when the effective access-token type is DPoP and the caller supplies the corresponding OAuthClient
- Resource-server nonces are cached per issuing server rather than per exact endpoint, so same-server protected-resource paths can reuse a nonce while token-endpoint and resource-server nonce state stay separate
- If an idempotent DPoP request is retried after a transient transport or HTTP failure, shinyOAuth mints a fresh proof for the retry instead of replaying the same proof JWT

9. Validate ID token (OIDC only)

When using oauth_provider(id_token_validation = TRUE), the following verifications are performed before any userinfo fetch. The list below is intentionally a bit more detailed than a typical app needs day to day; the main point is that shinyOAuth does these checks for you before making external calls:

Signature: checked against the provider JWKS (with optional pinning) for supported asymmetric algorithms (RS256, RS384, RS512, ES256, ES384, ES512, EdDSA). HMAC algorithms (HS256/HS384/HS512) are only allowed with explicit opt-in (options(shinyOAuth.allow_hs = TRUE)) and a sufficiently strong server-held secret. RSA-PSS (PS256, PS384, PS512) is not currently supported
Token format: shinyOAuth accepts signed JWS ID tokens only. Encrypted ID tokens (JWE) are rejected because the package does not perform JWE decryption; configure the provider to return signed-only ID tokens
Core claims: iss must match the expected issuer; aud must include client_id; sub must be present; iat must be a single finite numeric; time-based claims (exp is required, nbf optional) are evaluated with a small configurable leeway; tokens issued in the future are rejected
JWT header type (typ, when present): must indicate a JWT (JWT, case-insensitive). Other values (e.g., at+jwt) are rejected for ID tokens
Maximum ID token lifetime: exp - iat is checked against options(shinyOAuth.max_id_token_lifetime) (default 24 hours); tokens with unreasonably long lifetimes are rejected
Authorized party (azp): when an ID token names multiple audiences, shinyOAuth requires azp = client_id to keep the client binding explicit. If azp is present at all, it must equal client_id
Nonce: must match the previously stored value (if configured)
auth_time validation (OIDC Core §3.1.2.1): when max_age is present in extra_auth_params, the ID token’s auth_time claim must be present, must not be in the future beyond leeway, and must satisfy now - auth_time <= max_age + leeway
at_hash (Access Token hash, OIDC Core §3.1.3.8): when the ID token contains an at_hash claim, the access token binding is verified. When id_token_at_hash_required = TRUE on the provider, the ID token must contain this claim or login fails
Requested claims (OIDC Core §5.5): if the client requested specific claims via the claims parameter with essential = TRUE, value, or values, and claims_validation is "warn" or "strict", the decoded ID token payload is checked for missing essential claims and unsatisfied requested claim values. These trigger a warning or error depending on the mode. For claims$id_token, this enforcement only runs after shinyOAuth has validated the ID token; configure the provider with id_token_validation = TRUE or use_nonce = TRUE so those checks run on trusted token content. This is skipped when claims_validation = "none" (the default)
ACR enforcement (OIDC Core §2, §3.1.2.1): if the client was created with required_acr_values, the ID token’s acr claim must be present and match one of the specified values. This ensures the provider performed the expected authentication context (e.g., MFA). If the acr claim is missing or not in the allowlist, login fails with a shinyOAuth_id_token_error. The authorization request also includes an acr_values parameter as a voluntary hint to the provider

10. Fetch userinfo (optional)

If userinfo is requested via oauth_provider(userinfo_required = TRUE) (for which you should have a userinfo_url configured), the module calls the userinfo endpoint with the access token and stores the returned claims. This happens after ID token validation, so the earlier token checks pass before another external call is made. If the request fails, the flow aborts with an error.

When the access token is certificate-bound, shinyOAuth treats the userinfo call as protected-resource access: it uses the mTLS alias for userinfo_endpoint when configured, sends the client certificate on the TLS connection, and requires the token’s cnf.x5t#S256 thumbprint to match that certificate before making the request.

The userinfo endpoint may return either a standard JSON response or, less commonly, a JWT response (per OIDC Core section 5.3.2). When the endpoint returns Content-Type: application/jwt, the body is verified as a signed JWT against the provider JWKS. Only signed JWS userinfo responses are supported. Encrypted UserInfo JWTs (JWE) are rejected; configure the provider to return signed-only JWTs when using application/jwt responses. When userinfo_signed_jwt_required = TRUE on the provider, the endpoint must return application/jwt or the flow is aborted. UserInfo JWT verification is limited to asymmetric algorithms from the provider’s allowed_algs (RS*, ES*, or EdDSA); HS256, HS384, and HS512 are rejected on this surface even if HS* is otherwise enabled for ID tokens.

Subject match: whenever shinyOAuth has both userinfo and a validated ID token baseline, it checks that sub in userinfo equals sub in the ID token. Setting oauth_provider(userinfo_id_token_match = TRUE) additionally makes the flow fail closed when userinfo is fetched but no validated ID token baseline is available
Requested claims (OIDC Core §5.5): if the client requested specific userinfo claims via the claims parameter with essential = TRUE, value, or values, and claims_validation is "warn" or "strict", the userinfo response is checked for missing essential claims and unsatisfied requested claim values. These trigger a warning or error depending on the mode

11. Build the `OAuthToken` object

Once the token response and any preceding verification steps have succeeded, the module builds the OAuthToken object that your app will work with. This happens before optional token introspection, but the module still waits for any remaining checks before marking the session as authenticated.

This is an S7 OAuthToken object which contains:

access_token (string)
token_type (string, e.g., Bearer or DPoP)
refresh_token (optional string)
expires_at (numeric timestamp, seconds since epoch; Inf for non-expiring tokens)
id_token (optional string)
id_token_validated (logical, indicating whether the ID token was cryptographically verified)
id_token_claims (read-only named list exposing the decoded JWT payload, e.g., sub, acr, amr, auth_time)
cnf (optional confirmation claim set, such as an mTLS certificate thumbprint)
granted_scopes (normalized scope tokens currently associated with the access token)
granted_scopes_verified (logical indicating whether the current token response explicitly proved those scopes)
userinfo (optional list)

12. Token introspection (optional)

Some providers support RFC 7662 token introspection. This is an extra server-to-server check where shinyOAuth asks the provider whether a token is currently active and receives related metadata.

If you enable introspect = TRUE when creating your oauth_client(), the module calls the provider’s introspection endpoint after the token object has been built and requires the response to indicate active = TRUE before the session is treated as authenticated. If introspection fails, or if the token is reported as inactive, login stops and $authenticated is not set to TRUE.

You can optionally ask shinyOAuth to check additional provider-dependent fields via oauth_client(introspect_elements = ...):

"sub" – require introspection sub to match the session subject
"client_id" – require introspection client_id to match your OAuth client id
"scope" – validate introspection scope against requested scopes (respects the client’s scope_validation mode)

Note that not all providers may return each of these fields in introspection responses.

13. Mark session as authenticated

The $authenticated value as returned by oauth_module_server() now becomes TRUE, meaning all requested verifications have passed.

14. Clean URL & tidy UI; clear browser token

The user’s browser was redirected to your app with OAuth 2.0 query parameters (code, state, etc.). To keep the URL cleaner and avoid leaving sensitive values in the address bar, these values are removed with JavaScript. Optionally, the page title may also be adjusted (see the tab_title_ arguments in oauth_module_server()).

The browser token cookie is also cleared and immediately re-issued with a fresh value, so a future flow starts with a new per-session token.

15. Post-flow session management

Once login is complete, the module manages token lifetime during the active session. Depending on your settings, that may include:

Proactive refresh: if enabled via oauth_module_server(refresh_proactively = TRUE) and a refresh token exists, the access token is refreshed before expiry
Expiration: expired tokens are cleared automatically, setting the $authenticated flag to FALSE
Re-authentication: optionally, oauth_module_server(reauth_after_seconds = ...) can force periodic re-authentication

Refresh behavior (`refresh_token()`)

When the module refreshes a session, or when you call refresh_token() directly, it performs an OAuth 2.0 refresh-token grant against the provider’s token endpoint and updates the OAuthToken object. In short:

A token request is sent with grant_type=refresh_token and the current refresh_token
When DPoP is enabled and the token endpoint responds with DPoP-Nonce, shinyOAuth retries the refresh request once with a fresh proof that includes that nonce
The response must include a new access_token. expires_at is updated from expires_in when present; otherwise shinyOAuth synthesizes a finite fallback lifetime (default 3600 seconds, configurable via options(shinyOAuth.default_expires_in = ...))
If the provider rotates the refresh token (returns a new refresh_token), it is stored; otherwise the original is preserved
If oauth_provider(userinfo_required = TRUE), userinfo is re-fetched using the fresh access token
If oauth_client(introspect = TRUE), the refreshed access token is introspected through the same client policy before the session is updated

If you are running a security-sensitive app, set options(shinyOAuth.default_expires_in = ...) to the provider’s documented lifetime instead of relying on the package default, and consider oauth_module_server(reauth_after_seconds = ...) when you need a hard upper bound on session age.

Refresh can behave a little differently for OIDC ID tokens:

Per OIDC Core Section 12.2, refresh responses may omit id_token. When that happens, shinyOAuth keeps the original id_token, so refresh does not necessarily revalidate identity
If the provider does return an id_token during refresh, shinyOAuth enforces OIDC 12.2 subject continuity: the refresh-returned id_token must have the same sub as the original id_token from login
- If an original id_token did not exist in the session, and the refresh does return one, the refresh fails (cannot establish subject claim match with no baseline)
- If id_token_validation = TRUE, the refresh-returned id_token is fully validated (signature + claims); the sub claim match is enforced as part of validation
- If id_token_validation = FALSE, shinyOAuth still enforces the sub match by parsing the JWT payload (ensuring that the sub claim still matches but without full validation)
- In both validation paths, iss and aud claims in the refreshed ID token are compared against the original ID token’s values (not just the provider configuration) per OIDC Core Section 12.2, to cover edge cases with multi-tenant providers or rotating issuer URIs
- shinyOAuth also enforces continuity for auth_time when the original ID token had it, rejects a refreshed nonce when it changes, and requires azp to match when either token carries it

If refresh fails inside oauth_module_server(), the module exposes the failure through its reactive state (for example, auth$error == "token_refresh_error" plus auth$error_description). By default it also clears the current session token; if oauth_module_server(indefinite_session = TRUE), the token is kept and auth$token_stale becomes TRUE. In the default mode, $authenticated becomes FALSE while the error is present. With indefinite_session = TRUE, $authenticated stays TRUE even if a refresh error is present.

16. Logout and token revocation

When auth$logout() is called, the module:

Attempts to revoke both refresh and access tokens at the provider (RFC 7009) if a revocation_url is configured. This runs asynchronously only when oauth_module_server(async = TRUE)
Clears the local session (OAuthToken, browser cookie)
Emits a "logout" audit event
Re-issues a fresh browser token for subsequent logins

You can also revoke tokens directly via revoke_token(client, token, which = "refresh").

To automatically attempt revocation when a Shiny session ends (for example, a tab close or session timeout), set revoke_on_session_end = TRUE:

This requires the provider to have a configured revocation_url; otherwise oauth_module_server() rejects revoke_on_session_end = TRUE at startup.

auth <- oauth_module_server(
  "auth",
  client = client,
  revoke_on_session_end = TRUE
)

This is best-effort: the session may end while the provider is unavailable, and revocation failures do not block local session cleanup.