- name
Provider name (e.g., "github", "google"). Cosmetic
only; used in logging and audit events
- auth_url
Authorization endpoint URL
- token_url
Token endpoint URL
- userinfo_url
User info endpoint URL (optional)
- introspection_url
Token introspection endpoint URL (optional; RFC 7662)
- revocation_url
Token revocation endpoint URL (optional; RFC 7009)
- issuer
OIDC issuer URL (optional; required for ID token validation).
This is the base URL that identifies the OpenID Provider (OP). It is used
during ID token validation to verify the iss claim in the ID
token matches the expected issuer. It is also used to fetch the provider's
JSON Web Key Set (JWKS) for verifying ID token signatures (typically via
the OIDC discovery document located at /.well-known/openid-configuration
relative to the issuer URL)
- use_nonce
Whether to use OIDC nonce. This adds a nonce parameter to
the authorization request and validates the nonce claim in the ID token.
This is recommended for OIDC flows to mitigate replay attacks
- use_pkce
Whether to use PKCE. This adds a code_challenge parameter to
the authorization request and requires a code_verifier when exchanging
the authorization code for tokens. This is prevents authorization code
interception attacks
- pkce_method
PKCE code challenge method ("S256" or "plain"). "S256" is
recommended. "plain" should only be used for non-compliant providers that
do not support "S256"
- userinfo_required
Whether to fetch userinfo after token exchange.
User information will be stored in the userinfo field of the returned
OAuthToken object. This requires a valid userinfo_url to be set.
If fetching the userinfo fails, the token exchange will fail.
For the low-level constructor oauth_provider(), when not explicitly
supplied, this is inferred from the presence of a non-empty userinfo_url:
if a userinfo_url is provided, userinfo_required defaults to TRUE,
otherwise it defaults to FALSE. This avoids unexpected validation errors
when userinfo_url is omitted (since it is optional).
- userinfo_id_selector
A function that extracts the user ID from the userinfo response.#'
Should take a single argument (the userinfo list) and return the user ID
as a string.
This is used when userinfo_id_token_match is TRUE.
Optional otherwise; when not supplied, some features (like subject matching)
will be unavailable. Helper constructors like oauth_provider() and oauth_provider_oidc()
provide a default selector that extracts the sub field.
- userinfo_id_token_match
Whether to verify that the user ID ("sub") from the ID token
matches the user ID extracted from the userinfo response. This requires both
userinfo_required and id_token_validation to be TRUE (and thus a valid userinfo_url
and issuer to be set, plus potentially setting the client's scope to include "openid",
so that an ID token is returned). Furthermore, the provider's userinfo_id_selector must be configured
to extract the user ID from the userinfo response. This check helps ensure
the integrity of the user information by confirming that both sources agree on the user's identity.
For oauth_provider(), when not explicitly supplied, this is inferred as
TRUE only if both userinfo_required and id_token_validation are TRUE;
otherwise it defaults to FALSE.
- id_token_required
Whether to require an ID token to be returned
during token exchange. If no ID token is returned, the token exchange
will fail. This requires the provider to be a valid OpenID Connect
provider and may require setting the client's scope to include "openid".
Note: At the S7 class level, this defaults to FALSE so that pure OAuth 2.0
providers can be configured without OIDC. Helper constructors like
oauth_provider() and oauth_provider_oidc() will enable this when an
issuer is supplied or OIDC is explicitly requested.
- id_token_validation
Whether to perform ID token validation after token exchange.
This requires the provider to be a valid OpenID Connect provider with a configured
issuer and the token response to include an ID token (may require setting
the client's scope to include "openid").
Note: At the S7 class level, this defaults to FALSE. Helper constructors like
oauth_provider() and oauth_provider_oidc() turn this on when an issuer
is provided or when OIDC is used.
- extra_auth_params
Extra parameters for authorization URL
- extra_token_params
Extra parameters for token exchange
- extra_token_headers
Extra headers for token exchange requests (named character vector)
- token_auth_style
How to authenticate when exchanging tokens. One of:
"header": HTTP Basic (client_secret_basic)
"body": Form body (client_secret_post)
"client_secret_jwt": JWT client assertion signed with HMAC using client_secret
(RFC 7523)
"private_key_jwt": JWT client assertion signed with an asymmetric key
(RFC 7523)
- jwks_cache
JWKS cache backend. If not provided, a cachem::cache_mem(max_age = 3600)
(1 hour) cache will be created. May be any cachem‑compatible backend, including
cachem::cache_disk() for a filesystem cache shared across workers, or a custom
implementation created via custom_cache() (e.g., database/Redis backed).
TTL guidance: Choose max_age in line with your identity platform’s JWKS rotation
and cache‑control cadence. A range of 15 minutes to 2 hours is typically sensible;
the default is 1 hour. Shorter TTLs adopt new keys faster at the cost of more JWKS
traffic; longer TTLs reduce traffic but may delay new keys slightly. Signature
verification will automatically perform a one‑time JWKS refresh when a new kid
appears in an ID token.
Cache keys are internal, hashed by issuer and pinning configuration. Cache values are
lists with elements jwks and fetched_at (numeric epoch seconds)
- jwks_pins
Optional character vector of RFC 7638 JWK thumbprints
(base64url) to pin against. If non-empty, fetched JWKS must contain keys
whose thumbprints match these values depending on jwks_pin_mode.
Use to reduce key substitution risks by pre-authorizing expected keys
- jwks_pin_mode
Pinning policy when jwks_pins is provided. Either
"any" (default; at least one key in JWKS must match) or "all" (every
RSA/EC/OKP public key in JWKS must match one of the configured pins)
- jwks_host_issuer_match
When TRUE, enforce that the discovery jwks_uri host
matches the issuer host (or a subdomain). Defaults to FALSE at the class
level, but helper constructors for OIDC (e.g., oauth_provider_oidc() and
oauth_provider_oidc_discover()) enable this by default for safer config.
The generic helper oauth_provider() will also automatically set this to
TRUE when an issuer is provided and either id_token_validation or
id_token_required is TRUE (OIDC-like configuration). Set explicitly to
FALSE to opt out. For providers that legitimately publish JWKS on a
different host (e.g., Google), prefer setting jwks_host_allow_only to
the exact hostname rather than disabling this check
- jwks_host_allow_only
Optional explicit hostname that the jwks_uri must match.
When provided, jwks_uri host must equal this value (exact match). You can
pass either just the host (e.g., "www.googleapis.com") or a full URL; only
the host component will be used. If you need to include a port or an IPv6
literal, pass a full URL (e.g., https://[::1]:8443) — the port is ignored
and only the hostname part is used for matching. Takes precedence over
jwks_host_issuer_match
- allowed_algs
Optional vector of allowed JWT algorithms for ID tokens.
Use to restrict acceptable alg values on a per-provider basis. Supported
asymmetric algorithms include RS256, RS384, RS512, PS256, PS384,
PS512, ES256, ES384, ES512, and EdDSA (Ed25519/Ed448 via OKP).
Symmetric HMAC algorithms HS256, HS384, HS512 are also supported but
require that you supply a client_secret and explicitly enable HMAC
verification via the option options(shinyOAuth.allow_hs = TRUE).
Defaults to c("RS256","RS384","RS512","PS256","PS384","PS512", "ES256","ES384","ES512","EdDSA"), which intentionally excludes HS*.
Only include HS* if you are certain the client_secret is stored strictly
server-side and is never shipped to, or derivable by, the browser or other
untrusted environments. Prefer rotating secrets regularly when enabling this.
- allowed_token_types
Character vector of acceptable OAuth token types
returned by the token endpoint (case-insensitive). When non-empty, the
token response MUST include token_type and it must be one of the allowed
values; otherwise the flow fails fast with a shinyOAuth_token_error.
When empty, no check is performed and token_type may be omitted by the
provider. The oauth_provider() helper defaults to c("Bearer") for all
providers because the package only supports Bearer tokens (i.e.,
client_bearer_req() sends Authorization: Bearer). This ensures that if
a provider returns a non-Bearer token type (e.g., DPoP, MAC), the flow
fails fast rather than misusing the token. Set allowed_token_types = character() explicitly to opt out of enforcement.
- leeway
Clock skew leeway (seconds) applied to ID token exp/iat/nbf checks
and state payload issued_at future check. Default 30. Can be globally
overridden via option shinyOAuth.leeway