Package options control settings shared by the whole R process,
including network timeouts and diagnostic logging.
oauth_client() and oauth_module_server()
arguments apply to one app registration or module. The Usage guide covers login setup.
For example, give a slow provider up to ten seconds per network
request. Put this near the top of app.R, before creating
the provider and client:
A longer timeout gives a slow provider more time to respond, but
delays failure when the service is unavailable. Restore the default with
options(shinyOAuth.timeout = NULL).
Options affect every session sharing that R process; they are app-wide settings rather than per-user settings.
Times use seconds unless a setting explicitly says milliseconds.
These options control diagnostic events and the request details they contain.
options(shinyOAuth.audit_hook = function(event){ ... })
– receive structured audit and error events
options(shinyOAuth.audit_include_http = FALSE) –
exclude HTTP request details from audit events (default:
TRUE)
options(shinyOAuth.audit_include_raw_session_token = TRUE)
– include the raw shiny_session[["token"]] in native
audit-hook payloads. By default, hooks receive only
shiny_session[["session_token_digest"]]
options(shinyOAuth.audit_redact_http = FALSE) –
disable automatic redaction of sensitive data in audit events (default:
TRUE). Debug only: raw mode can expose cookies,
authorization headers, codes, state values, and client IP
addresses
options(shinyOAuth.telemetry_path_scrubber = function(path) NULL)
– return approved route labels for audit and OTel paths, which are
omitted by default. Return NULL for unknown routes, remove
identifying segments, and make the function idempotent.
options(shinyOAuth.audit_digest_key = ...) – shared
HMAC-SHA256 key of at least 32 bytes for audit/OTel correlation. The
default is a random per-process key; invalid configured keys cause an
error.
options(shinyOAuth.otel_tracing_enabled = FALSE) –
disable ‘shinyOAuth’ OpenTelemetry span creation and async trace-context
propagation. Default: TRUE
options(shinyOAuth.otel_logging_enabled = FALSE) –
disable ‘shinyOAuth’ OpenTelemetry log emission. Default:
TRUE
options(shinyOAuth.otel_include_authorization_details = TRUE)
– include raw scope names, claim targets, and ACR values in telemetry.
Default: FALSE (counts only). These fields can reveal
private information and produce many distinct telemetry values.
See Audit logging for R hook examples and OpenTelemetry for log and trace exporter setup.
Network settings limit request duration and response size.
options(shinyOAuth.tls_min_version = "1.2") -
require TLS 1.2 or later for package HTTPS requests (the default). Use
"1.3" for a higher minimum; an absent option or
NULL restores TLS 1.2. Set this before discovery or login.
It applies to async workers too; browser and reverse-proxy TLS must be
configured separately.
options(shinyOAuth.timeout = 5) – default HTTP
timeout (seconds) applied to all outbound requests (discovery, JWKS,
token exchange, userinfo). Increase if your provider/network is slow.
Values beyond curl’s supported timeout range are capped
options(shinyOAuth.retry_max_tries = 3L) – maximum
attempts after network errors or HTTP 408, 429 or 5xx responses. Code
exchange and refresh skip automatic retries, apart from one DPoP
nonce-challenge retry.
options(shinyOAuth.dpop_nonce_max_bytes = 4096L) –
maximum DPoP nonce size in bytes; supported range 1 to 65536.
options(shinyOAuth.retry_backoff_base = 0.5) – base
backoff in seconds used for exponential backoff with jitter
options(shinyOAuth.retry_backoff_cap = 5) –
per‑attempt cap on backoff seconds (before jitter)
options(shinyOAuth.retry_after_cap = 60) – maximum
synchronous sleep in seconds for a server-provided
Retry-After value; this is separate from the client-side
backoff cap
options(shinyOAuth.retry_status = c(408L, 429L, 500:599))
– HTTP statuses considered transient and retried
options(shinyOAuth.user_agent = "shinyOAuth/<version> R/<version> httr2/<version>")
– override the HTTP User-Agent. The default includes the installed
package and R versions.
options(shinyOAuth.allow_redirect = FALSE) – reject
redirects on sensitive provider requests by default. The opt-in permits
redirects in all sessions, potentially forwarding codes, tokens or
credentials to another destination.
options(shinyOAuth.max_body_bytes = 1048576) -
maximum response size (default 1 MiB) for package requests and
connection calls. perform_resource_req() applies it to
prepared requests as well as URLs.
A task timeout limits how long background work may run. Configure workers first, as shown in Usage.
options(shinyOAuth.async_timeout = 10000) – per-task
timeout in milliseconds for mirai async tasks. When using mirai with
dispatcher (the default), timed-out tasks are automatically cancelled
and resolve as a mirai error. Use NULL (the default) for no
timeout, or a whole number from 0 to 2147483647. Ignored when falling
back to the ‘future’ backendBackground workers can return warnings and messages to the app. Turn replay off if another logging system already handles those diagnostics.
options(shinyOAuth.replay_async_conditions = FALSE) –
when FALSE, warnings and messages captured from async
workers are silently discarded instead of being re-emitted on the main R
process. Default is TRUE (replay all captured conditions).
Useful if worker diagnostics are too noisy or handled separately via
audit_hookSome providers omit the token lifetime. This fallback lets ordinary OAuth clients track expiry in that case.
options(shinyOAuth.default_expires_in = 3600) –
fallback token lifetime (in seconds) when the provider omits
expires_in from the token responseThese settings control which token responses and addresses the app accepts.
options(shinyOAuth.access_token_cnf = "opaque") –
use "opaque" to avoid decoding access-token binding data.
The compatibility default "jwt" reads cnf
without signature verification.
options(shinyOAuth.leeway = 30) – default clock skew
leeway (seconds) for ID token
exp/iat/nbf checks and state
payload issued_at future check
options(shinyOAuth.max_id_token_lifetime = 86400) –
maximum ID token lifetime in seconds (exp - iat). This is
an additional package check beyond the OIDC expiry check. Default
86400 (24 hours). Set to Inf to disable the
check
options(shinyOAuth.allowed_non_https_hosts = c("localhost", "127.0.0.1", "::1", "[::1]"))
- allows these hosts to use http:// in non-OIDC URL checks;
it does not relax OIDC discovery
options(shinyOAuth.allow_insecure_oidc_loopback = TRUE)
– development-only opt-in for OIDC issuer and endpoint URLs on HTTP
loopback origins; production OIDC metadata URLs must use HTTPS
options(shinyOAuth.allowed_hosts = c()) – when
non-empty, restricts accepted hosts to this list
options(shinyOAuth.allow_hs = TRUE) – opt‑in HMAC
validation for ID tokens (HS256/HS384/HS512). Requires a strictly
server‑side client_secret and exactly one HS algorithm in
id_token_allowed_algs, binding the shared key to one
algorithm (RFC 8725 section 3.1)
options(shinyOAuth.client_assertion_ttl = 120L) –
lifetime in seconds for JWT client assertions used with
client_secret_jwt or private_key_jwt token
endpoint authentication. Finite values below 60 seconds are coerced to
60 seconds, finite values above 300 seconds are clamped to 300 seconds,
and NA or non-finite values fall back to the 120-second
default
options(shinyOAuth.state_fail_delay_ms = 0) – delay
before state-validation failures, in milliseconds. Default
0 adds no delay; one positive number sets a fixed delay,
two set random bounds. Positive delays block R even with
async = TRUE; they add timing noise rather than
constant-time validation.
allowed_hosts patterns support globs (*,
?). For example, c(".example.com") matches the
domain and its subdomains; "*" accepts any host.
Pending login records let the app recognize the returning browser. Shared stores must consume each record only once, even when several R processes handle requests.
options(shinyOAuth.allow_non_atomic_state_store = TRUE)
– allow separate reads and deletes in a shared store. Default
FALSE requires atomic [["take"]](). Enabling
this can let concurrent requests reuse a login record; the default
rejects this backend. See custom_cache().options(shinyOAuth.state_max_token_chars = 8192) –
maximum allowed length of the base64url-encoded state query
parameteroptions(shinyOAuth.state_max_wrapper_bytes = 8192) –
maximum decoded byte size of the outer JSON wrapper (before
parsing)options(shinyOAuth.state_max_ct_b64_chars = 8192) –
maximum allowed length of the base64url-encoded ciphertext inside the
wrapperoptions(shinyOAuth.state_max_ct_bytes = 8192) – maximum
decoded byte size of the ciphertext before attempting AES-GCM
decryptThese limits keep oversized state parameters from using excessive CPU or memory during decoding and decryption.
options(shinyOAuth.callback_max_code_bytes = 8192) –
maximum decoded authorization-code bytes. Oversized values are rejected
without truncation.
options(shinyOAuth.callback_max_state_bytes = 8192)
– maximum byte length of the state query parameter (outer
token string)
options(shinyOAuth.callback_max_error_bytes = 256) –
maximum byte length of the error query parameter
options(shinyOAuth.callback_max_error_description_bytes = 4096)
– maximum byte length of the error_description query
parameter
options(shinyOAuth.callback_max_error_uri_bytes = 2048)
– maximum byte length of the error_uri query
parameter
options(shinyOAuth.callback_max_iss_bytes = 2048) –
maximum byte length of the iss query parameter (RFC 9207
issuer identification)
options(shinyOAuth.callback_max_query_bytes = <derived>)
– maximum raw query bytes. Applies before parsing to app queries,
callbacks and hosted Request Objects.
options(shinyOAuth.callback_max_browser_token_bytes = 256)
– maximum byte length of the browser_token argument
accepted by handle_callback()
options(shinyOAuth.callback_max_form_post_body_bytes = <derived>)
– maximum byte length of the raw form_post callback body
before parsing
options(shinyOAuth.callback_max_form_post_handle_bytes = 128)
– maximum byte length of the transient shinyOAuth_form_post
handle query parameter
options(shinyOAuth.callback_max_form_post_id_bytes = 256)
– maximum byte length of the transient
shinyOAuth_form_post_id module-id query parameter
These limits reject oversized callback URLs and POST bodies before they cause excessive processing or logging.
Generated login state must fit both
shinyOAuth.callback_max_state_bytes and the state envelope
limits above. Their outer-token defaults both allow 8192 bytes
(base64url state is ASCII). Lowering either limit can restrict ordinary
logins with many scopes or other state metadata.
prepare_call() checks both budgets before storing pending
login state, publishing a Request Object, or sending PAR.
Use check_oauth21(client) to review settings without
making requests or changing the app. The report separates configuration
problems, recommendations and things that need deployment testing. See
check_oauth21()
for an example and the specification revision assessed.
options(shinyOAuth.skip_browser_token = TRUE) – skip
browser cookie binding in tests or interactive sessionsoptions(shinyOAuth.skip_id_sig = TRUE) – skip ID token
signature verification in tests or interactive sessionsoptions(shinyOAuth.allow_unsigned_userinfo_jwt = TRUE)
– accept unsigned (alg=none) UserInfo JWTs in tests or
interactive sessions; outside those contexts ‘shinyOAuth’ errors instead
of honoring itoptions(shinyOAuth.debug = TRUE) – re‑raise errors
during token exchangeoptions(shinyOAuth.expose_error_body = TRUE) – enable
sanitized diagnostic text for local debugging. Fields are capped at 512
UTF-8 bytes and can still contain private provider data. The option is
disabled by default and takes effect only in tests or interactive
sessions.Response limits cover both downloaded and decoded gzip data; other
encodings are rejected. Use
perform_resource_req(token, request) to retain the decoded
size limit, adding client for DPoP or mTLS. Direct
httr2::req_perform() uses httr2’s transport settings
instead.
Overrides allow selected extra parameters beyond the normal client and provider arguments.
By default, shinyOAuth blocks security-critical parameters in
extra_auth_params, extra_token_params, and
extra_token_headers to protect state binding, PKCE and
client authentication from accidental overrides.
Set the callback format with
oauth_client(response_mode = ...).
options(shinyOAuth.unblock_auth_params = c("redirect_uri"))
– allow selected authorization-parameter overrides.
options(shinyOAuth.unblock_token_params = c(...)) –
allow selected token-exchange parameter overrides.
options(shinyOAuth.unblock_token_headers = c("authorization"))
– allow selected token-header overrides, matched case-insensitively.
Authorization and Cookie are blocked by
default.