Package 'shinyOAuth'

Description

This function inspects a configured OAuthClient and its OAuthProvider for compliance with the OAuth 2.1 draft 16 (ruleset ⁠1.1.0⁠) specification. It reports configuration gaps, unresolved external prerequisites, and recommendations without changing the configuration or making requests.

Usage

check_oauth21(config, context = list(), draft = "draft-ietf-oauth-v2-1-16")

Arguments

Details

Ruleset ⁠1.1.0⁠ covers code/refresh, enabled PAR, required UserInfo and introspection, and the additional operations selected in context. Signing and encryption key retrieval is included when applicable. Future resource URLs, arbitrary request customization, browser/proxy TLS, registered redirect matching, secret custody, and authorization/resource server behavior require separate evidence. Optional DPoP, mTLS, PAR, JAR and JARM are not required as a bundle.

configuration_compliant is FALSE if an applicable mandatory configuration check fails; otherwise NA if a mandatory configuration check is unresolved; otherwise TRUE when a nonempty set of applicable mandatory checks passes. Recommendations and external unknowns do not change that verdict. In particular, the legacy assertion type JWT is a recommendation finding; the assertion audience is a separate mandatory check for JWT authentication. requirement_source distinguishes OAuth core, OIDC, extension specifications, security guidance and local package/application policy. Callback capacity thresholds are package recommendations, not draft-defined numeric minima; complete encoded requests still need deployment testing. OAuth 2.1 assessment is opt-in and does not change existing OAuth 2.0 configuration or requests.

A positive verdict applies only to the recorded scope and ruleset, with the current configuration, options, runtime and declared context. It is not certification or a test of a live deployment. Rerun after policy changes. Reports contain no client/provider objects, credentials, keys or endpoint URLs. No caches or state stores are read or changed; their method contracts are inspected without invoking them.

Value

A shinyOAuth_oauth21_assessment list with configuration_compliant, checks, draft, ruleset_version, package_version, assessed_at, assessment_scope, and operations. checks is a data frame with stable id, scope, status (pass, fail, warn, unknown, not_applicable), requirement (MUST, SHOULD, info), message, remediation, reference, evidence_source, requirement_source, and logical affects_verdict columns. Only rows with affects_verdict = TRUE enter aggregation; unknown external obligations remain visible separately. warn records a compatibility warning, such as accepting a missing token type, and does not by itself fail the verdict.

References

https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-16

https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rfc7523bis-11

https://www.rfc-editor.org/rfc/rfc9207.html

Examples

provider <- oauth_provider(
  name = "Example",
  auth_url = "https://auth.example/authorize",
  token_url = "https://auth.example/token",
  token_auth_style = "public", use_pkce = TRUE, pkce_method = "S256"
)
client <- oauth_client(
  provider, client_id = "example-client",
  redirect_uri = "https://app.example/callback"
)
assessment <- check_oauth21(client)
assessment[["checks"]][assessment[["checks"]][["status"]] != "pass", ]

Description

Deprecated alias for resource_req(). Use resource_req() for Bearer, DPoP, and mTLS-protected resource requests instead.

Usage

client_bearer_req(
  token,
  url,
  method = "GET",
  headers = NULL,
  query = NULL,
  follow_redirect = FALSE,
  check_url = TRUE,
  client = NULL,
  token_type = NULL,
  dpop_nonce = NULL,
  resource_hosts = NULL,
  oauth_client = NULL
)

Arguments

Value

Same value as resource_req().

Description

Connect shinyOAuth to a shared storage backend, such as Redis or a database, by wrapping your R functions in a cachem-like interface. Use the result as state_store in oauth_client() to share pending login state, or as jwks_cache in oauth_provider() to share provider signing keys (JWKS).

A shared state store is needed when a login can start on one R process and its callback can arrive at another, for example in a multi-worker deployment without sticky routing. A shared signing-key cache lets workers reuse keys fetched from the provider rather than maintaining separate caches.

Usage

custom_cache(
  get,
  set,
  remove,
  take = NULL,
  info = NULL,
  set_if_absent = NULL,
  worker_safe = FALSE
)

Arguments

Details

This helper adapts your storage functions; it does not create a database, open connections, or make process-local storage shared. Your backend must preserve stored R values and expire entries after their configured lifetime.

Value

An R6 object exposing cachem-like ⁠[["get"]]/[["set"]]/[["remove"]]/[["info"]]⁠ methods and the optional ⁠[["take"]]⁠ and ⁠[["set_if_absent"]]⁠ atomic methods.

Shared login state in multi-worker deployments

The default cachem::cache_mem() state store belongs to one R process. If a load balancer sends the returning callback to another worker, that worker cannot find the pending login and validation fails. Configure all workers with access to the same external store when routing does not keep the authorization request and callback on the same process.

For a shared state_store, implement take: it must read and delete a pending login as one indivisible operation, so two requests cannot use it. Redis GETDEL and SQL ⁠DELETE ... RETURNING⁠ are examples of backend operations that can do this. Use the same state_key and matching provider/client settings on every worker. Separate reads and deletes, including those in cachem::cache_disk(), cannot ensure single-use state under concurrent access. See the deployment guidance. For the form_post and form_post.jwt callback bridges, also implement set_if_absent to reserve callback slots without replacing pending responses.

Store values are small R lists; preserve them without interpreting fields. Pending login records in external stores are AES-GCM sealed with a distinct key derived from state_key and bound to the client, provider, and state key. The backend receives an opaque sealed_state_record string instead of the browser binding, PKCE verifier, and nonce. Existing unsealed external records are rejected; users with logins pending across an upgrade must restart login. The default process-local memory store keeps records within the R trust boundary. Encryption does not replace backend access controls, expiry, or atomic take: a backend able to restore consumed entries can still violate single-use state.

With request_object_mode = "request_uri", hosted Request Objects are stored as separate records containing the signed or encrypted JWT and its expiry. These records do not use the pending-login sealed_state_record wrapper. A signed, unencrypted JWT has readable claims, including authorization request details. Configure Request Object JWE encryption when those claims need confidentiality, and apply backend access controls and expiry to these records.

For a state store, returning max_age in seconds from info() also lets oauth_module_server() align the browser cookie lifetime with the store. Reporting this value does not expire entries; your backend must enforce it.

Shared provider signing keys

A shared jwks_cache can reduce repeated key downloads when several R workers use the same provider. This is independent of sharing login state: sharing signing keys alone does not let another worker resume a login.

Key caching uses get and set. Also implement set_if_absent to coordinate rate-limited forced key refreshes across workers, for example when the provider rotates its signing keys. Without that atomic operation, forced refresh is disabled for custom/shared caches. Use separate stores or key namespaces for login state and signing keys when they require different expiry policies.

For asynchronous login and token operations, a custom signing-key cache defaults to synchronous fallback. Set worker_safe = TRUE only if its functions and captured values remain usable after serialization into a new R process. Open database/file connections and other process-bound resources must not be captured; open and close connections inside each operation instead. Serialization success alone does not establish worker safety. Standard cachem::cache_mem() and cachem::cache_disk() backends support worker dispatch without this opt-in. Other cache implementations can expose a scalar logical worker_safe member with the same contract. State stores are not used in callback workers.

Examples

# This in-memory example illustrates the cache interface in one R process.
# It does not share entries across workers or implement timed expiry.
# A production shared store must implement both itself.
mem <- new.env(parent = emptyenv())

my_cache <- custom_cache(
  get = function(key, missing = NULL) {
    base::get0(key, envir = mem, ifnotfound = missing, inherits = FALSE)
  },

  set = function(key, value) {
    assign(key, value, envir = mem)
    invisible(NULL)
  },

  remove = function(key) {
    if (exists(key, envir = mem, inherits = FALSE)) {
      rm(list = key, envir = mem)
    }
    invisible(NULL)
  },

  # In a shared store, replace this with the backend's atomic get-and-delete
  # operation, such as Redis GETDEL. This R environment is process-local.
  take = function(key, missing = NULL) {
    val <- base::get0(key, envir = mem, ifnotfound = missing, inherits = FALSE)
    if (exists(key, envir = mem, inherits = FALSE)) {
      rm(list = key, envir = mem)
    }
    val
  },

  info = function() list(max_age = Inf)
)

Description

Retrieve profile information using the user's access token. Call this when fetching a profile on demand, reloading profile fields, or managing tokens outside the Shiny module. It returns the provider's profile as an R list. The Shiny module fetches and stores this information during login when userinfo_required = TRUE; that result is available as auth[["token"]]@userinfo.

Usage

get_userinfo(
  client,
  token,
  token_type = NULL,
  shiny_session = NULL,
  oauth_client = NULL
)

Arguments

Details

The provider must have a userinfo_url: the OpenID Connect (OIDC) UserInfo endpoint, or an OAuth provider's profile API. With OIDC, this function checks that userinfo belongs to the same user as a validated ID token. Pass the complete OAuthToken, which carries the validated ID token needed for this check. OIDC providers with a UserInfo endpoint require this baseline by default, including when userinfo_required = FALSE disables automatic retrieval. Raw access tokens and unvalidated ID tokens then cause an error. An explicit userinfo_id_token_match = FALSE permits profile retrieval without a validated identity; when one is available, its subject is always compared.

Ordinary JSON profiles and signed JWT UserInfo responses are supported. Signed responses are verified using the provider's signing keys and userinfo_allowed_algs; encrypted UserInfo is not supported. Set userinfo_signed_jwt_required on the provider to require a signed response, including when fetching manually with userinfo_required = FALSE, and userinfo_jwt_required_time_claims on the client to require time claims such as exp. Present time claims are checked even when not required.

Standard OIDC profile claims in ID tokens and UserInfo are checked against their JSON types, including strings for names and email, a number for updated_at, and an address object with string-valued standard members. Applications should validate formats and policies for the claim values they use, and supply schemas for custom extension claims.

For certificate-bound tokens (mTLS) and key-bound tokens (DPoP), the helper uses the client's certificate or signing key and checks the token binding. It handles one DPoP nonce challenge with a fresh-proof retry. See the advanced security vignette for configuration.

Value

A list containing the user information returned by the provider. For JSON responses, arrays are simplified to vectors or data frames where possible. Signed JWT responses retain arrays as lists.

Examples

# get_userinfo(), introspect_token(), and refresh_token() are typically
# called by oauth_module_server() according to your provider/client and
# module settings, rather than directly by application code. The module
# also calls revoke_token() during logout when the provider supports it.
# These helpers are exported for custom login flows, on-demand profile or
# token checks, and applications that manage token lifetime themselves.
#
# The examples below require a real token from a completed login.
# Inside a reactive expression in server(), after creating auth with
# oauth_module_server() and confirming auth[["authenticated"]]:
if (interactive()) {
  token <- auth[["token"]]
  user_info <- get_userinfo(client, token)

  # Requires an introspection endpoint. NA means activity is unknown.
  result <- introspect_token(client, token)
  isTRUE(result[["active"]])

  # Requires a refresh token. Keep the returned replacement.
  token <- refresh_token(client, token)

  # Requires a revocation endpoint to invalidate the token at the provider.
  result <- revoke_token(client, token, token_kind = "refresh")
}

Description

Check a returning login request and exchange the provider's temporary authorization code for an OAuthToken (OAuth 2.0 Authorization Code flow). Use this in a custom callback handler after starting authorization with prepare_call(). It applies shinyOAuth's state, token, and configured identity checks while your application manages the HTTP callback and stores the returned token. oauth_module_server() handles these responsibilities for Shiny sessions.

Usage

handle_callback(
  client,
  code,
  state,
  browser_token,
  shiny_session = NULL,
  iss = NULL,
  oauth_client = NULL,
  payload = NULL
)

Arguments

Details

Pass the returned code, the callback's state, and the browser token saved for this login. This helper accepts direct code/state callbacks only. For signed responses using JWT Secured Authorization Response Mode (JARM; "jwt", "query.jwt", or "form_post.jwt"), use oauth_module_server() and, for POST responses, oauth_form_post_ui(). There is no public JARM resume API.

Value

An OAuthToken object. If callback validation, token exchange, or token verification fails, the function raises an error.

Examples

# Advanced example: your code supplies browser redirects and callback handling.
# For a Shiny app, oauth_module_server() manages these steps for you.

if (interactive()) {
  # Define client
  client <- oauth_client(
    provider = oauth_provider_github(),
    client_id = Sys.getenv("GITHUB_OAUTH_CLIENT_ID"),
    client_secret = Sys.getenv("GITHUB_OAUTH_CLIENT_SECRET"),
    redirect_uri = "http://127.0.0.1:8100"
  )

  # Get the login URL and store state in client's state store
  # `<browser_token>` must be unpredictable and persisted for this transaction
  # in storage bound to the application's exact origin (scheme, host, port).
  # The module combines origin-scoped storage with an independent marker cookie
  # and checks both on return. A cookie alone does not provide this boundary:
  # cookies can be shared by applications on different ports of the same host.
  # Shiny applications should use oauth_module_server() for the complete flow.
  authorization_url <- prepare_call(client, "<browser_token>")

  # Redirect user to authorization URL; retrieve code & state from the query;
  # recover this transaction's `<browser_token>` through the origin-bound flow
  # and verify its independent marker before calling handle_callback().
  code <- "..."
  state <- "..."
  browser_token <- "..."

  # Handle callback, exchanging code for token and validating state
  token <- handle_callback(client, code, state, browser_token)
}

Description

Ask the provider to check an access or refresh token. This is called token introspection and requires a configured introspection_url. Use it when you need the provider's current token status rather than only a locally recorded expiry time: a token may have been revoked before its expiry. To require it automatically during login and refresh, set introspect = TRUE on oauth_client().

Usage

introspect_token(
  client,
  token,
  token_kind = c("access", "refresh"),
  async = FALSE,
  shiny_session = NULL,
  oauth_client = NULL,
  oauth_token = NULL,
  which = NULL
)

Arguments

Details

Read result[["active"]]: TRUE means active, FALSE means inactive, and NA means the result is unknown. Use isTRUE(result[["active"]]) if your code must require a definite confirmation.

Unsupported endpoints, missing tokens, unsuccessful HTTP responses, and unusable response bodies return a descriptive status. The provider must return active as a JSON boolean. Other types return "invalid_active". Encoded or decoded body limits return "body_too_large"; unsupported compression returns "unsupported_encoding". Both leave active = NA. Other transport failures and decoding errors raise conditions (or reject the asynchronous promise) instead of returning a status result. Requests use the client's configured credentials and token_auth_style.

Value

A list with fields:

• supported: logical, TRUE when an introspection endpoint is configured.

• active: logical or NA, where NA means the provider did not return a usable RFC 7662 active value.

• raw: parsed introspection response list, or NULL when the endpoint is unsupported or the response could not be parsed.

• status: machine-readable status such as "ok", "introspection_unsupported", "missing_token", "invalid_json", "missing_active", "invalid_active", or "http_<code>".

Examples

# get_userinfo(), introspect_token(), and refresh_token() are typically
# called by oauth_module_server() according to your provider/client and
# module settings, rather than directly by application code. The module
# also calls revoke_token() during logout when the provider supports it.
# These helpers are exported for custom login flows, on-demand profile or
# token checks, and applications that manage token lifetime themselves.
#
# The examples below require a real token from a completed login.
# Inside a reactive expression in server(), after creating auth with
# oauth_module_server() and confirming auth[["authenticated"]]:
if (interactive()) {
  token <- auth[["token"]]
  user_info <- get_userinfo(client, token)

  # Requires an introspection endpoint. NA means activity is unknown.
  result <- introspect_token(client, token)
  isTRUE(result[["active"]])

  # Requires a refresh token. Keep the returned replacement.
  token <- refresh_token(client, token)

  # Requires a revocation endpoint to invalidate the token at the provider.
  result <- revoke_token(client, token, token_kind = "refresh")
}

Description

Test whether a URL is allowed by shinyOAuth's ordinary scheme and host rules. HTTPS is accepted by default. HTTP is limited to local development hosts unless you change allowed_non_https_hosts. Supply allowed_hosts to restrict which services your app may contact.

Call this when checking configured endpoint URLs or diagnosing a URL-policy rejection. The provider and API request helpers apply these checks internally; a direct call lets you inspect the result without making a network request.

Usage

is_ok_host(
  url,
  allowed_non_https_hosts = getOption("shinyOAuth.allowed_non_https_hosts", default =
    c("localhost", "127.0.0.1", "::1", "[::1]")),
  allowed_hosts = getOption("shinyOAuth.allowed_hosts", default = NULL)
)

Arguments

Details

Both host lists support * (any characters), ⁠?⁠ (one character), and a leading dot: ".example.com" matches the domain and its subdomains. "*" permits every host. If allowed_hosts is empty, only the scheme rules apply. Missing values, empty strings, and malformed URLs return FALSE.

If the scheme is absent, this helper tries HTTP, then HTTPS. Request helpers can impose additional requirements, including an absolute URL. OIDC discovery has a separate HTTPS policy and requires an explicit loopback development opt-in; a TRUE result here does not override it.

Defaults come from shinyOAuth.allowed_hosts and shinyOAuth.allowed_non_https_hosts.

Value

Logical indicator (TRUE if all URLs pass all checks; FALSE otherwise)

Examples

# HTTPS allowed by default
is_ok_host("https://example.com")

# HTTP allowed for localhost
is_ok_host("http://localhost:8100")

# Restrict to a specific domain (allowlist)
is_ok_host("https://api.example.com", allowed_hosts = c(".example.com"))

# Caution: a catch-all pattern disables host restrictions
# (only scheme rules remain). Avoid unless you truly intend it
is_ok_host("https://anywhere.example", allowed_hosts = c("*"))

Description

Choose who may use saved OAuth connections: the browser that created them, or an account already authenticated by your application. Supply the policy to oauth_connections() with the matching retention mode. These factories do not set cookies, authenticate users or enable retention on oauth_module_server() calls by themselves.

Usage

oauth_browser_owner(
  idle_timeout = 1800,
  absolute_timeout = 28800,
  same_site = c("Lax", "Strict"),
  allow_http_loopback = FALSE,
  max_entries = 1000L
)

oauth_account_owner(
  resolver,
  idle_timeout,
  absolute_timeout,
  reauth_after_seconds,
  max_entries = 1000L
)

## S3 method for class 'OAuthOwnerPolicy'
print(x, ...)

Arguments

Details

Browser retention identifies an authorized browser session, not a verified person. The owner cookie is HttpOnly, host-only, has root path and uses Secure and a ⁠__Host-⁠ name on HTTPS. It contains no OAuth token or patient data. Server-side idle and absolute limits are authoritative. A cookie is never accepted as an owner without a matching live server record for this application origin.

Cookies are shared across ports on the same host, even with HttpOnly, Secure and a ⁠__Host-⁠ name (RFC 6265 section 8.5). All HTTPS services on that host that receive the owner cookie must be trusted, because they can read and replay it. The origin hash in the cookie name distinguishes applications but does not isolate the cookie from other ports. Use separate hostnames for mutually untrusted services.

Cookie rotation invalidates the previous session generation immediately and preserves the original absolute lifetime. Local logout removes the live owner session. The manager checks that generation before code exchange and credential commit, with no grace period for pending authorization, and handles credential cleanup after logout. An external provider login cannot establish a local owner or implicitly link browser connections to an account.

A full owner registry rejects new retained owners without evicting live sessions or retirement records. Browser session end does not release ownership; logout or idle/absolute expiry does. Account logout retains its retired generation until authenticated_at + reauth_after_seconds so it cannot be enrolled again. Size max_entries for that entire window, not only simultaneous Shiny sessions.

Account retention requires finite idle, absolute and local reauthentication lifetimes. The internal session registry re-runs resolver when resolving or validating an owner and checks the intended subject/session generation. Expiry or logout retires that generation until a fresh local authentication session is supplied. A resolver error fails closed with a redacted error. The application remains responsible for validating its local session, including signature, expiry, revocation and account changes. Supplying this configuration is not proof that an arbitrary user ID is authenticated.

Value

An OAuthOwnerPolicy configuration object. Browser policies use an opaque server-issued cookie and server-side owner registry. Account policies use the trusted local-session resolver described below.

See Also

oauth_connection_store_memory()

Examples

# Browser connections expire after 15 minutes idle or 8 hours in total.
oauth_browser_owner(idle_timeout = 15 * 60, absolute_timeout = 8 * 3600)

# Supply your application's trusted local-login validator for account retention.
# It must revalidate the session on each call and return the documented fields.
account_policy <- function(validate_local_session) {
  oauth_account_owner(
    resolver = validate_local_session,
    idle_timeout = 15 * 60,
    absolute_timeout = 8 * 3600,
    reauth_after_seconds = 8 * 3600
  )
}

Description

Create a client with the credentials assigned by your provider, the URL where users return after login, and the permissions your app needs. Pass the result to oauth_module_server().

Usage

oauth_client(
  provider,
  client_id,
  client_secret = character(0),
  redirect_uri,
  enforce_callback_issuer = NULL,
  scopes = character(0),
  resource = character(0),
  claims = NULL,
  state_store = cachem::cache_mem(max_age = 300),
  state_payload_max_age = 300,
  state_entropy = 64,
  state_key = random_urlsafe(128),
  client_assertion_private_key = NULL,
  client_assertion_private_key_kid = NULL,
  client_assertion_alg = NULL,
  client_assertion_audience = NULL,
  mtls_client_cert_file = NULL,
  mtls_client_key_file = NULL,
  mtls_client_key_password = NULL,
  mtls_client_ca_file = NULL,
  mtls_certificate_bound_access_tokens = FALSE,
  request_object_mode = c("parameters", "request", "request_uri"),
  response_mode = NULL,
  request_object_signing_alg = NULL,
  request_object_audience = NULL,
  request_object_encryption_alg = NULL,
  request_object_encryption_enc = NULL,
  request_object_encryption_kid = NULL,
  request_object_ttl = 45,
  request_object_nbf_skew = NULL,
  dpop_private_key = NULL,
  dpop_private_key_kid = NULL,
  dpop_signing_alg = NULL,
  dpop_require_access_token = NULL,
  scope_validation = c("warn", "strict", "none"),
  claims_validation = c("none", "warn", "strict"),
  userinfo_jwt_required_time_claims = character(0),
  required_acr_values = character(0),
  introspect = FALSE,
  introspection_checks = character(0),
  authorization_server_mode = c("single", "multi_issuer", "multi_redirect_uri"),
  authorization_server_redirect_uris = character(0),
  dpop_require_observed_cnf = FALSE,
  jarm_signed_response_alg = NULL,
  jarm_encrypted_response_alg = NULL,
  jarm_encrypted_response_enc = NULL,
  jarm_decryption_private_key = NULL,
  jarm_decryption_private_key_kid = NULL,
  jarm_max_lifetime = 600,
  endpoint_auth = list(),
  mtls_require_observed_cnf = TRUE,
  trusted_id_token_audiences = character(0),
  compare_callback_issuer = NULL,
  client_assertion_typ = "JWT",
  authorization_method = "GET",
  resource_bases = character(),
  required_scopes = character(),
  label = default_client_label(provider),
  ...,
  introspect_elements = NULL,
  token_targets = list(),
  default_token_target = if (length(token_targets) == 1L) {
     names(token_targets)
 }
    else {
     character()
 }
)

Arguments

Details

Create the client outside server() so its settings and pending login state remain available when the callback returns. Configure provider, client_id, client_secret (if issued), redirect_uri, and scopes from the app registration. Use state_store and state_key for shared login state across workers, and validation arguments to require particular scopes, claims, or authentication context. See the usage vignette for a complete app, or the advanced security vignette for certificate and signed-request settings.

Value

OAuthClient object

Examples

# Register an app with GitHub and store its credentials in your environment.
# This creates the configuration; it does not start login or contact GitHub.
client <- oauth_client(
  provider = oauth_provider_github(),
  client_id = "your-client-id",
  client_secret = "your-client-secret",
  redirect_uri = "http://127.0.0.1:8100",
  scopes = c("read:user", "user:email")
)

# In a real app, read credentials with Sys.getenv() and create client
# outside server(). Inside server(), start login with:
# auth <- oauth_module_server("auth", client)

Description

Build a list of settings to register a certificate-based client with your provider using mutual TLS (mTLS). Use this when preparing metadata for dynamic client registration or when your provider asks for certificate identifiers, public keys, or certificate-bound token settings. It derives those settings from an oauth_client() already configured for mTLS.

The result is a metadata list, ready to include in a registration request. Submit it through your provider's registration process; this function does not register the client or upload the certificate.

Usage

oauth_client_mtls_registration(
  client,
  tls_client_auth_type = c("subject_dn", "san_dns", "san_uri", "san_ip", "san_email"),
  tls_client_auth_value = NULL,
  jwks_uri = NULL,
  oauth_client = NULL
)

Arguments

Details

For tls_client_auth, the result identifies the client certificate using one selected subject or alternative-name field. For self_signed_tls_client_auth, it contains an inline jwks with the certificate chain (x5c), or the supplied jwks_uri.

For certificate-bound tokens without mTLS client authentication, the result uses the corresponding registration authentication method (for example, public becomes none) and sets tls_client_certificate_bound_access_tokens = TRUE. See the advanced security vignette for when these configurations are useful.

Value

A JSON-ready list of RFC 7591/RFC 8705 client metadata.

Examples

# Set these environment variables to your existing certificate and key files.
provider <- oauth_provider(
  name = "Example service",
  auth_url = "https://example.com/authorize",
  token_url = "https://example.com/token",
  token_auth_style = "tls_client_auth"
)
client <- oauth_client(
  provider = provider,
  client_id = "example-client",
  redirect_uri = "http://127.0.0.1:8100/callback",
  mtls_client_cert_file = Sys.getenv("OAUTH_MTLS_CERT_FILE"),
  mtls_client_key_file = Sys.getenv("OAUTH_MTLS_KEY_FILE")
)
oauth_client_mtls_registration(client)

Description

Use your Apple developer key to create the client secret expected by Sign in with Apple. Pass the returned string as client_secret to oauth_client(). Unlike a fixed password, this secret expires; replace it before its expiry.

Usage

oauth_client_secret_apple(
  client_id,
  team_id,
  key_id,
  private_key,
  expires_in = 15776700,
  issued_at = Sys.time(),
  audience = "https://appleid.apple.com"
)

Arguments

Details

The helper signs a JWT with ES256. It places your Team ID in iss, your client ID in sub, Apple's URL in aud, and the key ID in the header. The lifetime must not exceed 15,777,000 seconds (about six months).

Value

A compact signed JWT string suitable for oauth_client(..., client_secret = ...)

Examples

## Not run: 
key <- openssl::ec_keygen(curve = "P-256")

oauth_client_secret_apple(
  client_id = "com.example.web",
  team_id = "ABCDEFGHIJ",
  key_id = "ABC123DEFG",
  private_key = key
)

## End(Not run)

Description

Combine one module's reactive token with its client and approved API addresses configured on oauth_client(). Call ⁠[["request"]]()⁠ on the returned connection instead of assembling a token, client and URL for each request. It reads the reactive token again after refresh or logout and restricts requests to the configured APIs. This optional wrapper expires with its Shiny session; it does not implement refresh itself or retain credentials across redirects. Clients with token_targets must use the module's connection() factory, which retains the authorization's permission limits alongside its tokens.

Usage

oauth_connection(
  client,
  token_reactive,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Create the reference once inside server(). Access it only in that session's reactive context. ⁠[["summary"]]()⁠ excludes tokens, identity claims and extension context. ⁠[["is_usable"]]()⁠ checks local presence, known expiry and required scopes; it cannot guarantee remote authorization. Unknown token expiry is unusable.

Paths are relative to the selected base directory. Absolute and root-relative references (including pagination links) must stay within that same base. Dot segments and ambiguous encodings are rejected; redirects are never followed. Bearer, DPoP and mTLS use the existing transport and the configured client.

Use request-level required_scopes for optional operations. They must be included in the client's requested scopes and covered by the current grant. The package cannot infer arbitrary API permissions from an HTTP method/path. The legacy module continues to own refresh and logout. Retained connection storage and its independent lifecycle are available through oauth_connections() and oauth_connections_server().

Value

An OAuthConnection with ⁠[["id"]]⁠, ⁠[["is_usable"]]()⁠, ⁠[["summary"]]()⁠ and ⁠[["request"]](resource_id, path = "", query = NULL, method = "GET", required_scopes = character(), configure = NULL)⁠. Requests return httr2 responses. configure can add a body and application headers; see OAuthConnection for its contract.

Examples

## Not run: 
# Configure outside server():
client <- oauth_client(provider, "registered-app",
  redirect_uri = "https://app.example/callback", scopes = "read",
  resource_bases = c(api = "https://api.example/v1"))
# Inside server():
auth <- oauth_module_server("auth", client)
connection <- oauth_connection(client, shiny::reactive(auth[["token"]]))
data <- shiny::reactive({
  shiny::req(connection[["is_usable"]]())
  connection[["request"]]("api", "records", required_scopes = "read")
})

## End(Not run)

Description

Stores encrypted credential envelopes and coordinates their lifecycle across Shiny sessions in one R process. Create one store outside server(). This adapter does not survive process restarts and rejects use from a copied worker process. It is a connection-manager building block, not an authentication API.

Usage

oauth_connection_store_memory(
  max_age = 28800,
  refresh_timeout = 60,
  max_entries = 1000L
)

## S3 method for class 'OAuthConnectionStore'
print(x, ...)

Arguments

Details

Methods are trusted server-side operations. The manager must validate the current owner session and generation before calling them. The opaque owner identifier scopes records and can survive session rotation; knowledge of an owner or connection ID does not authenticate a user. Records contain ciphertext only. Encryption keys stay with the manager, outside this adapter. Never expose these methods or credential imports as HTTP routes.

• ⁠[["create"]](owner, id, transaction, client, fingerprint, sealed, expires_at)⁠ returns a record with a new revision, or NULL for a duplicate connection/transaction.

• ⁠[["read"]](owner, id)⁠ returns the owner's record, or NULL when absent, expired, or owned by someone else. It includes the sealed envelope for internal use.

• ⁠[["list"]](owner)⁠ returns metadata lists without ciphertext or operation IDs.

• ⁠[["begin_refresh"]](owner, id, revision)⁠ claims an active record and returns its new revision and operation ID. A conflicting claim returns NULL.

• ⁠[["commit_refresh"]](owner, id, operation, revision, sealed)⁠ installs credentials only for the current claim, returning the updated record or NULL.

• ⁠[["fail_refresh"]](owner, id, operation, revision, outcome)⁠ releases a claim only for "not_consumed"; "possibly_consumed" and "consumed" remove the old envelope and mark the record "uncertain". Returns the record or NULL.

• ⁠[["disconnect"]](owner, id, revision)⁠ first installs a credential-free tombstone, then returns list(record, previous) for bounded remote cleanup. Conflicts return NULL; the caller must reload before retrying.

• ⁠[["disconnect_owner"]](owner)⁠ tombstones all of that owner's records and returns the previous records for bounded cleanup. Other owners are unaffected.

Reads expire abandoned refresh claims before returning data. Tombstones and transaction IDs remain at least until the original absolute expiry so late completions cannot restore a disconnected grant. Operations are synchronous and do not yield or perform network calls. Atomicity applies to this R process only. A separate shared backend needs its own verified concurrency contract.

Value

An OAuthConnectionStore adapter with the methods described below.

See Also

oauth_client(), oauth_connection()

Examples

# Create once, outside server(), then supply to oauth_connections().
store <- oauth_connection_store_memory(max_age = 8 * 3600, max_entries = 100)

Description

Create one manager outside server() for a named set of client/API configurations from oauth_client() or smart_client(). Use oauth_connections_ui() to handle callbacks and oauth_connections_server() for each Shiny session. Each successful authorization creates a separate connection, including repeated authorizations at the same client. Connections are independent local records. Providers may reuse an upstream grant, so revoking one can invalidate tokens held by other connections. Within a manager, refreshes sharing one credential are serialized. Rotation or an uncertain refresh invalidates other records holding the same credential; authorize those records again. Their identity and permissions are never replaced by another connection's response. Successful revocation also invalidates known copies of that credential. Distinct tokens may still share an upstream grant whose revocation effects the manager cannot predict. Retired credential digests survive connection replacement and expiry for at least the store's maximum age and the longest client state lifetime. A separate registry holds at most 10,000 digests or pending reservations. A full registry rejects refresh or skips remote revocation before sending credentials; it does not evict retirement evidence. Existing unrelated access remains usable.

Usage

oauth_connections(
  clients,
  app_origin,
  retention = c("shiny", "browser", "account"),
  retention_seconds = 28800,
  owner_policy = NULL,
  store = NULL,
  keys = NULL,
  callback_policy = "distinct_routes"
)

## S3 method for class 'OAuthConnections'
print(x, ...)

Arguments

Details

A manager is bound to one UI/server module ID and one public origin. Create another manager for another namespace. The memory store and owner registries survive Shiny sessions, not R restarts; copies in another R process fail closed.

In session-only mode, a pending authorization survives navigation through the existing single-use OAuth state and browser binding, while existing grants are discarded with the old Shiny session. Browser/account mode additionally binds authorization to the initiating local owner and its session generation.

These are optional package interfaces, not SMART protocol objects. This manager supports generic OAuth clients and the SMART discovery, scope and launch policies configured by smart_client().

Value

An OAuthConnections server-side configuration object. Printing shows only the retention mode and client count. It contains client configuration and deployment keys and must never be sent to the browser.

See Also

oauth_connections_ui(), oauth_connections_server()

Examples

# Replace this example provider and client ID with your registered application.
provider <- oauth_provider(
  name = "Example service",
  auth_url = "https://example.com/authorize",
  token_url = "https://example.com/token",
  token_auth_style = "public"
)
client <- oauth_client(
  provider = provider,
  client_id = "example-client",
  redirect_uri = "http://127.0.0.1:8100/callback/service",
  resource_bases = c(api = "https://api.example.com")
)

# Create the manager once, outside server(). Default retention is one Shiny session.
manager <- oauth_connections(
  clients = list(service = client),
  app_origin = "http://127.0.0.1:8100"
)
ui <- oauth_connections_ui(
  shiny::fluidPage(
    shiny::actionButton("connect", "Connect to service"),
    shiny::verbatimTextOutput("connections")
  ),
  id = "auth",
  manager = manager
)
server <- function(input, output, session) {
  auth <- oauth_connections_server("auth", manager)
  shiny::observeEvent(input[["connect"]], auth[["connect"]]("service"))
  output[["connections"]] <- shiny::renderPrint(auth[["connections"]]())
}

# Construct the app without launching it or contacting the provider.
app <- shiny::shinyApp(
  ui,
  server,
  uiPattern = ".*",
  options = list(port = 8100)
)

Description

Call once inside server() with the manager and ID used by oauth_connections_ui(). The returned methods select stored connections by opaque IDs and recheck the local owner for every operation. Tokens are kept on the server and are not returned by summaries.

Usage

oauth_connections_server(
  id,
  manager,
  async = FALSE,
  refresh_proactively = FALSE,
  refresh_lead_seconds = 60,
  refresh_check_interval_ms = 10000
)

Arguments

Details

References expire with this Shiny session even when their stored grants survive. A new session obtains new references after owner verification. The manager coordinates refresh across its connections. Refresh preserves the original authentication time and retention expiry. Reactive connection reads also recheck expiry at refresh_check_interval_ms, including references used without connections() or errors(). These checks notify dependent expressions when lifecycle state changes; unchanged polling does not rerun application requests or extend owner inactivity limits. Notifications to application code reflect only this owner's record changes. Without an ID, connection() returns NULL when no authorization remains, selects the sole retained authorization, or raises shinyOAuth_access_error with reason selection_required when several remain. Expired, limited and uncertain authorizations count toward ambiguity; disconnected rows do not.

The connection factory, ⁠$access_token()⁠ and ⁠$has_scopes()⁠ avoid rerunning consumers on unchanged token rotations. Acquisition never extends owner idle limits or replays application requests. See vignette("external-integrations"). Resource requests and status reads never reset owner inactivity, including when reactive expressions rerun after automatic refresh. Call touch() from a user input event handler to count an application action as activity. Do not call it from polling observers or ordinary reactive readers. Connecting, explicitly refreshing and disconnecting also count as activity.

Remote revocation is best effort: at most ten seconds per disconnect/logout batch, at most two seconds and one HTTP attempt per credential. Results are accepted, unsupported, missing, failed or not_attempted for access and refresh credentials. accepted describes the endpoint response, not proof of prior token validity. Local disconnect remains effective if revocation fails. A provider may revoke an entire authorization grant or related credentials (RFC 7009 section 2.1). Separate connection IDs do not establish independent provider grants, even after repeated consent or account selection. Consequently, default revoke = TRUE may also end access for sibling connections or other applications covered by the provider's revocation policy. Use revoke = FALSE when preserving those authorizations is required. This also applies to credentials returned by work already in flight. Removed credentials remain valid remotely until the provider expires or revokes them. Local summaries and is_usable() do not detect such remote changes: handle API authorization failures and obtain a new authorization.

Use this API inside its owning session's reactive context. Session setup requires a matching HTTP Origin on the Shiny request. Raw HTTP routes cannot import credentials or select an owner. The manager supports one R process.

Value

A server-side list with:

• connect(client_name): request a new authorization without discarding others. EHR-only clients report fresh_ehr_launch_required and return FALSE; use their registered smart_launch_route() to start authorization.

• connections(): reactive list of redacted connection summaries.

• connection(connection_id = NULL): an OAuthConnection for requests, refresh, scope checks and server-side ⁠$access_token()⁠ retrieval for external SDKs.

• reauthorize(connection_id): end this local authorization and start its replacement with the retained scope limit, without upstream revocation. Local state preparation is checked first; rejection preserves current access. The replacement summary includes replaces_connection_id. Failed/cancelled replacement leaves the old reference invalid. Unrelated authorizations remain usable; shared-credential protections still apply. EHR-only clients require a fresh EHR launch instead.

• touch(): record explicit user activity after checking the current owner. Call from an input event handler; returns TRUE invisibly.

• disconnect(connection_id, revoke = TRUE): remove local usability first, then return separate local and remote revocation results. remote$access aggregates the primary and acquired target tokens, with precedence failed, not_attempted, unsupported, accepted, missing.

• disconnect_all(revoke = TRUE): cancel pending authorizations and disconnect this owner's stored connections; return a list of results.

• logout(revoke = TRUE, reload = TRUE): invalidate the local owner/session generation first, disconnect its connections, and normally reload the UI. This does not log the user out of the external OAuth provider or the app's own account authentication system.

• errors(): reactive list of per-client module error codes, with no raw provider text. An ended owner is reported as owner_unavailable.

Examples

# Replace this example provider and client ID with your registered application.
provider <- oauth_provider(
  name = "Example service",
  auth_url = "https://example.com/authorize",
  token_url = "https://example.com/token",
  token_auth_style = "public"
)
client <- oauth_client(
  provider = provider,
  client_id = "example-client",
  redirect_uri = "http://127.0.0.1:8100/callback/service",
  resource_bases = c(api = "https://api.example.com")
)

# Create the manager once, outside server(). Default retention is one Shiny session.
manager <- oauth_connections(
  clients = list(service = client),
  app_origin = "http://127.0.0.1:8100"
)
ui <- oauth_connections_ui(
  shiny::fluidPage(
    shiny::actionButton("connect", "Connect to service"),
    shiny::verbatimTextOutput("connections")
  ),
  id = "auth",
  manager = manager
)
server <- function(input, output, session) {
  auth <- oauth_connections_server("auth", manager)
  shiny::observeEvent(input[["connect"]], auth[["connect"]]("service"))
  output[["connections"]] <- shiny::renderPrint(auth[["connections"]]())
}

# Construct the app without launching it or contacting the provider.
app <- shiny::shinyApp(
  ui,
  server,
  uiPattern = ".*",
  options = list(port = 8100)
)

Description

Wrap the application's UI with the same manager and module ID used by oauth_connections_server(). Browser retention establishes its HttpOnly owner cookie on an ordinary page request before Shiny starts. OAuth callbacks use the existing validated callback bridge and clean continuation. This wrapper also includes the browser dependency and response headers; do not add a separate use_shinyOAuth() call or nest oauth_ui().

Usage

oauth_connections_ui(
  base_ui,
  id,
  manager,
  request_uri_resolver = NULL,
  app_base_path = "/",
  launch_routes = list(),
  additional_clients = list()
)

Arguments

Details

Raw GET and form POST callbacks never create or rotate an owner. A POST may lack a SameSite owner cookie. With Strict owner cookies, a validated callback first serves an inert same-origin document that navigates to the clean continuation, allowing the browser to send its existing cookie. The document does not establish an owner or exchange credentials. A managed continuation must carry a still-valid owner before credentials can be exchanged. Ordinary entry without a Strict cookie also uses a bounded same-origin navigation before creating an empty owner. Browsers must supply same-origin Fetch Metadata or a same-origin Referer or Origin header on that request. The shinyOAuth_owner_recovery query parameter is reserved for this navigation. A validated ordinary callback for additional_clients can establish a new empty manager owner independently. An invalid cookie on an ordinary page is cleared using an HTTP response and a same-origin redirect; the next request establishes a new empty browser owner.

The cookie is scoped to its host. Separate applications on that host must be trusted; different ports or paths do not isolate their cookies. The wrapper adds no owner cookie for session-only or account retention.

Value

A request UI function for shinyApp(..., uiPattern = ".*").

See Also

oauth_browser_owner(), oauth_ui()

Examples

# Replace this example provider and client ID with your registered application.
provider <- oauth_provider(
  name = "Example service",
  auth_url = "https://example.com/authorize",
  token_url = "https://example.com/token",
  token_auth_style = "public"
)
client <- oauth_client(
  provider = provider,
  client_id = "example-client",
  redirect_uri = "http://127.0.0.1:8100/callback/service",
  resource_bases = c(api = "https://api.example.com")
)

# Create the manager once, outside server(). Default retention is one Shiny session.
manager <- oauth_connections(
  clients = list(service = client),
  app_origin = "http://127.0.0.1:8100"
)
ui <- oauth_connections_ui(
  shiny::fluidPage(
    shiny::actionButton("connect", "Connect to service"),
    shiny::verbatimTextOutput("connections")
  ),
  id = "auth",
  manager = manager
)
server <- function(input, output, session) {
  auth <- oauth_connections_server("auth", manager)
  shiny::observeEvent(input[["connect"]], auth[["connect"]]("service"))
  output[["connections"]] <- shiny::renderPrint(auth[["connections"]]())
}

# Construct the app without launching it or contacting the provider.
app <- shiny::shinyApp(
  ui,
  server,
  uiPattern = ".*",
  options = list(port = 8100)
)

Description

Accept the provider's login callback as an HTTP POST and continue login with oauth_module_server(). Use this when you select response_mode = "form_post" or "form_post.jwt", either because the provider requires it or to keep callback parameters out of the browser URL. The POST arrives before a Shiny session exists; this wrapper receives it and makes the validated callback available to the server module. For query-string callbacks, use oauth_ui().

Usage

oauth_form_post_ui(
  base_ui,
  id = NULL,
  client = NULL,
  callback_path = NULL,
  request_uri_resolver = NULL,
  clients = NULL
)

Arguments

Details

Set response_mode on your oauth_client(), wrap your UI here, and use the same id and client in oauth_module_server(). The wrapper includes the browser setup and privacy header supplied by oauth_ui(). For a callback path below the app root, pass uiPattern = ".*" to shiny::shinyApp() so Shiny routes the callback to this wrapper.

The wrapper checks the incoming address and login state, stores the callback temporarily, and redirects the browser to a normal Shiny page with a single-use handle. Raw callback values do not appear in that redirected URL. For "form_post.jwt", it also validates the signed response using JWT Secured Authorization Response Mode (JARM). Every accepted POST receives its own random handle. Handles expire after 120 seconds or the smaller of state_payload_max_age and the state store lifetime. The module still verifies the browser binding before consuming login state. Each client/provider/module namespace has a separate bounded pool in the state store: 1024 partitions of two slots, with each login assigned to one partition. A full partition rejects new callbacks until a slot is consumed or expires; a POST never evicts an unexpired response. Hash collisions can share capacity, but repeating one callback cannot displace another login's pending response. An expired handle fails validation and cannot select a later response stored in the same slot. Completed logins invalidate their remaining candidates. The process-local memory store also removes sibling candidates; shared stores retain them until expiry to avoid deleting a new occupant during cleanup. Shared stores require atomic take and set_if_absent; slots are claimed atomically with a short TTL. The process-local memory store reuses only consumed or expired slots. Pending form-post handles issued by an older version must be restarted after upgrading.

Value

A Shiny UI function. Pass it to shiny::shinyApp() and, for non-root callback paths, use uiPattern = ".*" so Shiny routes the callback path to this UI function.

Deployment behind a proxy

If a proxy receives HTTPS and forwards HTTP to Shiny, supply a request_uri_resolver that reconstructs the public address after verifying the request came from your trusted proxy. The default resolver does not trust forwarded headers. The resulting address must match the configured redirect origin and callback path. See the advanced security vignette.

Callback size limits are documented in the package options reference.

Examples

if (
  # Example requires a local or remote Keycloak realm whose client allows
  # http://127.0.0.1:8100/callback as a valid redirect URI.
  nzchar(Sys.getenv("KEYCLOAK_BASE_URL")) &&
    nzchar(Sys.getenv("KEYCLOAK_REALM")) &&
    nzchar(Sys.getenv("KEYCLOAK_CLIENT_ID")) &&
    interactive()
) {
  library(shiny)
  library(shinyOAuth)

  options(shinyOAuth.allow_insecure_oidc_loopback = TRUE)

  provider <- oauth_provider_keycloak(
    base_url = Sys.getenv("KEYCLOAK_BASE_URL"),
    realm = Sys.getenv("KEYCLOAK_REALM")
  )

  client <- oauth_client(
    provider = provider,
    client_id = Sys.getenv("KEYCLOAK_CLIENT_ID"),
    client_secret = Sys.getenv("KEYCLOAK_CLIENT_SECRET"),
    redirect_uri = "http://127.0.0.1:8100/callback",
    scopes = c("openid", "profile", "email"),
    response_mode = "form_post"
  )

  base_ui <- fluidPage(
    uiOutput("login")
  )

  ui <- oauth_form_post_ui(base_ui, id = "auth", client = client)

  server <- function(input, output, session) {
    auth <- oauth_module_server("auth", client, auto_redirect = TRUE)

    output[["login"]] <- renderUI({
      if (auth[["authenticated"]]) {
        user_info <- auth[["token"]]@userinfo
        tagList(
          tags[["p"]]("You are logged in!"),
          tags[["pre"]](paste(capture.output(str(user_info)), collapse = "\n"))
        )
      } else {
        tags[["p"]]("You are not logged in.")
      }
    })
  }

  runApp(
    shinyApp(ui, server, uiPattern = ".*"),
    port = 8100,
    launch.browser = FALSE
  )
}

Description

Call oauth_module_server() inside your Shiny server() function to manage login for each user. It sends users to the provider, checks their return, and gives your app reactive login status and user information. Create client with oauth_client() outside server(), and wrap your complete UI with oauth_ui(ui, id = "auth", client = client), using the same module ID and client. Use oauth_form_post_ui() for POST callbacks. These wrappers include the browser dependency; no separate use_shinyOAuth() call is needed.

This uses the OAuth 2.0 Authorization Code flow, with OpenID Connect (OIDC) identity checks when configured for an OIDC provider.

Usage

oauth_module_server(
  id,
  client,
  auto_redirect = TRUE,
  async = FALSE,
  indefinite_session = FALSE,
  reauth_after_seconds = NULL,
  refresh_proactively = FALSE,
  refresh_lead_seconds = 60,
  refresh_check_interval_ms = 10000,
  revoke_on_session_end = FALSE,
  tab_title_cleaning = TRUE,
  tab_title_replacement = NULL,
  request_uri_base_url = NULL,
  browser_cookie_path = NULL,
  browser_cookie_samesite = c("Strict", "Lax", "None"),
  refresh_check_interval = NULL
)

Arguments

Details

Login starts automatically by default. Use auto_redirect = FALSE and auth[["request_login"]]() to start it from a button. Read auth[["authenticated"]] in reactive code, and use req(auth[["authenticated"]]) before server operations that require login. Your app must also enforce its own access rules.

See the usage vignette for a complete app and instructions for registration, API calls, and deployment.

Value

A shiny::reactiveValues() object. If you assign it to auth, its main fields are:

• auth[["authenticated"]]: TRUE when a token is present and the configured checks have passed, otherwise FALSE. With indefinite_session = TRUE, the flag stays true while a token is kept, including after refresh errors. With token targets, it tracks the retained authorization across individual token expiry and recoverable target failures. Connection methods check the selected token's lifetime and permissions before use; the configured authentication-age limit still applies to the whole authorization.

• auth[["token"]]: an OAuthToken, or NULL before login or after clearing the session. Read properties with @, for example auth[["token"]]@userinfo. Additional token response parameters are available in auth[["token"]]@extra_fields; auth[["token"]]@initial_extra_fields preserves the parameters from the initial code exchange across refreshes.

• auth[["error"]], auth[["error_description"]]: the error code and available diagnostic detail. Use your own user-facing message; these fields can include sensitive provider information.

• auth[["error_uri"]]: an optional provider help URL. Only absolute HTTPS URLs on provider or explicitly allowed hosts are surfaced. Treat it as untrusted navigation input. NULL means the provider omitted the URL or supplied a value that did not pass validation.

• auth[["token_stale"]]: TRUE when a target authorization retains an expired primary token, or an indefinite session keeps an expired token or one whose refresh failed. Resets after successful login, primary-token refresh, or authorization clearing, including logout and maximum authentication age. Refreshing a secondary target does not renew the primary token.

The object also supplies:

• auth$connection(): the current OAuthConnection, or NULL before login or after the module clears the authorization. The reference and its ⁠$id⁠ survive refresh; logout, reauthorization and session closure invalidate it. Use connection <- shiny::req(auth$connection()) inside reactive code, then connection$access_token() for a server-side SDK or database driver. Accessor-triggered refresh works without refresh_proactively = TRUE; the module's configured expiry/session-clearing policy still applies.

• auth$reauthorize(): invalidate the current local authorization and begin replacement with its retained scope limit, without upstream revocation. Local state preparation is checked first; rejection preserves current access. Failed/cancelled replacement after that does not revive old references. With no prior grant, this starts ordinary login. It does not force account selection or a password prompt; configured maximum authentication age still applies.

• auth[["request_login"]](): start login. Waits for browser setup when needed and does nothing if the session is already authenticated. Uses a browser form when the client selects authorization_method = "POST"; the app's Content Security Policy form-action must permit the provider endpoint.

• auth[["logout"]](): clear the local login and attempt to revoke tokens when supported, following async. It does not sign out of the provider account.

• auth[["build_auth_url"]](): advanced helper for a custom login link. Rejects POST clients; use request_login() for their form submission. Creates pending login state as well as the URL, so retain the result for the link instead of rebuilding it on every UI update. Rotates and checks the browser binding before creating state. Returns a promise resolving to the URL (or NA on failure or an obsolete result); use promises::then(). PAR URLs carry shinyOAuth.par_request_uri, shinyOAuth.par_expires_in, and shinyOAuth.par_expires_at attributes to help you decide when to regenerate the link. request_login() handles these details for button-based login. Inside observeEvent(), register the promise handler and then return invisible(NULL) so Shiny can process the browser acknowledgment. Do not return the pending promise from the observer itself.

• auth[["has_browser_token"]](): reports whether the browser token is available. Use it before building a custom login URL; it does not report whether the user is authenticated.

• auth[["set_browser_token"]](): asks the browser to establish its binding when missing. The token becomes available after the browser reports it back to Shiny. An existing token is left unchanged.

• auth[["clear_browser_token"]](): clears the browser binding. request_login() manages cookie setup automatically, and logout() handles cookie rotation when ending a session.

Other fields manage the module internally and are not needed in app code.

Asynchronous execution

With async = TRUE, configure mirai::daemons() or a non-sequential future::plan() before starting the app. Slow provider requests can then run outside the main R process. Without this, network waits can delay all Shiny sessions sharing that process.

Advanced operations sent to workers include PAR, signed Request Object preparation, and query JARM verification. State-store operations and Shiny Request Object publication stay in the main process. Discovery during app setup, standalone prepare_call(), and JARM verification in oauth_form_post_ui() remain synchronous. Use timeouts on those network and storage operations; see the package options reference.

Browser setup

Open the app at its registered return address in a regular browser with cookies, session storage, and Web Crypto enabled. Embedded IDE viewers may prevent login. On Posit Connect or Connect Cloud, open the direct app URL in a new browser tab rather than using the dashboard's embedded preview. In Connect Cloud, copy the sharing URL from Settings > URL. Register the exact public callback URL with your provider, including any callback path. The module emits a reminder once per R process when Posit's deployment environment markers are present; it does not detect whether a page is embedded. The binding token stays in origin- and tab-scoped session storage; the cookie contains an independent marker, which must match the stored record. The temporary browser cookie follows the state store's max_age, with a 300-second fallback when that lifetime is unavailable. The separate state_payload_max_age client setting limits the age of the login request. Each new login uses a fresh server-selected browser binding and its own marker cookie. Application callback routes and module namespaces identify the storage record. Separate tabs can complete logins independently; complete a login in the tab that started it. Starting another login in the same tab and module replaces that tab's pending binding. Pending logins must be restarted after upgrading from versions that used local storage. Private browser-binding inputs are excluded from Shiny bookmarks. Do not copy auth[["browser_token"]] into custom bookmark values, URLs, or logs. Treat the entire hostname as a trust boundary: cookies are shared across ports, even with ⁠__Host-⁠, Secure, or HttpOnly. Use a dedicated hostname when other services are not trusted. The origin-scoped check prevents cookie adoption across ports, but co-hosted services can still disrupt cookies.

See Also

oauth_ui(), oauth_client(), OAuthToken, oauth_form_post_ui()

Examples

# Register http://127.0.0.1:8100 as the GitHub OAuth App callback URL.
if (
  # Example requires configured GitHub OAuth 2.0 app
  # (go to https://github.com/settings/developers to create one):
  nzchar(Sys.getenv("GITHUB_OAUTH_CLIENT_ID")) &&
    nzchar(Sys.getenv("GITHUB_OAUTH_CLIENT_SECRET")) &&
    interactive()
) {
  library(shiny)
  library(shinyOAuth)

  # Define client
  client <- oauth_client(
    provider = oauth_provider_github(),
    client_id = Sys.getenv("GITHUB_OAUTH_CLIENT_ID"),
    client_secret = Sys.getenv("GITHUB_OAUTH_CLIENT_SECRET"),
    redirect_uri = "http://127.0.0.1:8100",
    scopes = c("read:user", "user:email")
  )

  # Choose which app you want to run
  app_to_run <- NULL
  while (!isTRUE(app_to_run %in% c(1:4))) {
    app_to_run <- readline(
      prompt = paste0(
        "Which example app do you want to run?\n",
        "  1: Auto-redirect login\n",
        "  2: Manual login button\n",
        "  3: Fetch additional resource with access token\n",
        "  4: No app (all will be defined but none run)\n",
        "Enter 1, 2, 3, or 4... "
      )
    )
  }

  if (app_to_run %in% c(1:3)) {
    cli::cli_alert_info(paste0(
      "Will run example app {app_to_run} on {.url http://127.0.0.1:8100}\n",
      "Open this URL in a regular browser (viewers in RStudio/Positron/etc. ",
      "cannot perform necessary redirects)"
    ))
  }

  # Example app with auto-redirect (1) -----------------------------------------

  ui_1 <- oauth_ui(
    fluidPage(
      uiOutput("login")
    ),
    id = "auth",
    client = client
  )

  server_1 <- function(input, output, session) {
    # Auto-redirect (default):
    auth <- oauth_module_server(
      "auth",
      client,
      auto_redirect = TRUE
    )

    output[["login"]] <- renderUI({
      if (auth[["authenticated"]]) {
        user_info <- auth[["token"]]@userinfo
        tagList(
          tags[["p"]]("You are logged in!"),
          tags[["pre"]](paste(capture.output(str(user_info)), collapse = "\n"))
        )
      } else {
        tags[["p"]]("You are not logged in.")
      }
    })
  }

  app_1 <- shinyApp(ui_1, server_1)
  if (app_to_run == "1") {
    runApp(
      app_1,
      port = 8100,
      launch.browser = FALSE
    )
  }

  # Example app with manual login button (2) -----------------------------------

  ui_2 <- oauth_ui(
    fluidPage(
      actionButton("login_btn", "Login"),
      actionButton("logout_btn", "Logout"),
      uiOutput("login")
    ),
    id = "auth",
    client = client
  )

  server_2 <- function(input, output, session) {
    auth <- oauth_module_server(
      "auth",
      client,
      auto_redirect = FALSE
    )

    observeEvent(input[["login_btn"]], {
      auth[["request_login"]]()
    })
    observeEvent(input[["logout_btn"]], {
      auth[["logout"]]()
    })

    output[["login"]] <- renderUI({
      if (auth[["authenticated"]]) {
        user_info <- auth[["token"]]@userinfo
        tagList(
          tags[["p"]]("You are logged in!"),
          tags[["pre"]](paste(capture.output(str(user_info)), collapse = "\n"))
        )
      } else {
        tags[["p"]]("You are not logged in.")
      }
    })
  }

  app_2 <- shinyApp(ui_2, server_2)
  if (app_to_run == "2") {
    runApp(
      app_2,
      port = 8100,
      launch.browser = FALSE
    )
  }

  # Example app requesting additional resource with access token (3) -----------

  # Below app shows the authenticated username + their GitHub repositories,
  # fetched via GitHub API using the access token obtained during login

  ui_3 <- oauth_ui(
    fluidPage(
      uiOutput("ui")
    ),
    id = "auth",
    client = client
  )

  server_3 <- function(input, output, session) {
    auth <- oauth_module_server(
      "auth",
      client,
      auto_redirect = TRUE
    )

    repositories <- reactiveVal(NULL)
    repository_error <- reactiveVal(FALSE)

    observe({
      req(auth[["authenticated"]])

      # Example additional API request using the access token
      # (e.g., fetch user repositories from GitHub)
      # This loads one page; use the API's pagination for further results.
      repos_data <- tryCatch(
        {
          resp <- perform_resource_req(
            auth[["token"]],
            "https://api.github.com/user/repos",
            query = list(per_page = 30)
          )
          httr2::resp_check_status(resp)
          httr2::resp_body_json(resp, simplifyVector = TRUE)
        },
        error = function(e) NULL
      )

      repository_error(is.null(repos_data))
      repositories(repos_data)
    })

    # Render username + their repositories
    output[["ui"]] <- renderUI({
      if (isTRUE(auth[["authenticated"]])) {
        user_info <- auth[["token"]]@userinfo
        repos <- repositories()

        return(tagList(
          tags[["p"]](paste("You are logged in as:", user_info[["login"]])),
          tags[["h4"]]("Your repositories:"),
          if (repository_error()) {
            tags[["p"]]("Could not load repositories.")
          } else if (!is.null(repos) && length(repos) == 0) {
            tags[["p"]]("No repositories returned.")
          } else if (!is.null(repos)) {
            tags[["ul"]](
              Map(
                function(url, name) {
                  # Render names as text; accept only GitHub HTTPS links.
                  if (isTRUE(grepl("^https://github\\.com/", url))) {
                    tags[["li"]](tags[["a"]](
                      href = url,
                      target = "_blank",
                      rel = "noopener noreferrer",
                      name
                    ))
                  } else {
                    tags[["li"]](name)
                  }
                },
                repos[["html_url"]],
                repos[["full_name"]]
              )
            )
          } else {
            tags[["p"]]("Loading repositories...")
          }
        ))
      }

      return(tags[["p"]]("You are not logged in."))
    })
  }

  app_3 <- shinyApp(ui_3, server_3)
  if (app_to_run == "3") {
    runApp(
      app_3,
      port = 8100,
      launch.browser = FALSE
    )
  }
}

Description

Configure a service from its documented endpoint URLs and protocol settings when no named provider helper fits or OIDC discovery is unavailable. Pass the resulting provider to oauth_client(). For a supported service, its named helper is an easier starting point; for OIDC, oauth_provider_oidc_discover() can look up the settings.

Usage

oauth_provider(
  name,
  auth_url,
  token_url,
  userinfo_url = NA_character_,
  introspection_url = NA_character_,
  revocation_url = NA_character_,
  par_url = NA_character_,
  par_required = FALSE,
  authorization_request_front_channel_mode = "compat",
  request_object_signing_alg_values_supported = character(),
  request_object_encryption_alg_values_supported = character(),
  request_object_encryption_enc_values_supported = character(),
  request_object_encryption_jwk = NULL,
  signed_request_object_required = FALSE,
  request_parameter_supported = NA,
  request_uri_parameter_supported = NA,
  request_uri_registration_required = NA,
  token_endpoint_auth_signing_alg_values_supported = character(),
  dpop_signing_alg_values_supported = character(),
  authorization_response_iss_parameter_supported = FALSE,
  response_modes_supported = character(),
  mtls_endpoint_aliases = list(),
  mtls_client_certificate_bound_access_tokens = FALSE,
  issuer = NA_character_,
  issuer_match = "url",
  use_nonce = NULL,
  use_pkce = TRUE,
  pkce_method = "S256",
  userinfo_required = NULL,
  userinfo_id_token_match = NULL,
  userinfo_signed_jwt_required = FALSE,
  userinfo_id_selector = function(userinfo) {
     userinfo[["sub"]]
 },
  id_token_required = NULL,
  id_token_validation = NULL,
  extra_auth_params = list(),
  extra_token_params = list(),
  extra_token_headers = character(),
  token_auth_style = "header",
  jwks_cache = NULL,
  jwks_pins = character(),
  jwks_pin_mode = "any",
  jwks_host_issuer_match = NULL,
  jwks_host_allow_only = NULL,
  id_token_allowed_algs = c("RS256", "RS384", "RS512", "ES256", "ES384", "ES512",
    "Ed25519", "EdDSA"),
  allowed_token_types = c("Bearer"),
  leeway = getOption("shinyOAuth.leeway", 30),
  id_token_at_hash_required = FALSE,
  infer_oidc_from_issuer = TRUE,
  jwks_uri = NA_character_,
  userinfo_allowed_algs = NULL,
  jarm_signing_alg_values_supported = character(),
  jarm_encryption_alg_values_supported = character(),
  jarm_encryption_enc_values_supported = character(),
  jarm_tolerate_duplicate_top_level_iss = FALSE,
  endpoint_auth_metadata = list(),
  ...,
  allowed_algs = NULL,
  allow_missing_token_type = FALSE,
  token_target_mode = "none",
  token_response_scope_format = "space"
)

Arguments

Details

Supply name, auth_url, and token_url to start. Add userinfo_url to fetch profiles. Supplying issuer enables OIDC defaults, including ID token validation, unless infer_oidc_from_issuer = FALSE. Advanced arguments must match your provider's capabilities; see the advanced security vignette.

Value

OAuthProvider object

Examples

# Configure generic OAuth 2.0 provider (no OIDC)
generic_provider <- oauth_provider(
  name = "example",
  auth_url = "https://example.com/oauth/authorize",
  token_url = "https://example.com/oauth/token",
  # Optional URL for fetching user info:
  userinfo_url = "https://example.com/oauth/userinfo"
)

# Configure generic OIDC provider manually
# (This defaults to using nonce & ID token validation)
generic_oidc_provider <- oauth_provider_oidc(
  name = "My OIDC",
  base_url = "https://my-issuer.example.com"
)

# Configure a OIDC provider via OIDC discovery
# (requires network access)
if (interactive()) {
  # Using Auth0 sample issuer as an example
  oidc_discovery_provider <- oauth_provider_oidc_discover(
    issuer = "https://samples.auth0.com/"
  )
}

# GitHub preconfigured provider
github_provider <- oauth_provider_github()

# Google preconfigured provider
google_provider <- oauth_provider_google()

# Microsoft preconfigured provider
# For a complete app using a custom tenant ID, see:
# https://lukakoning.github.io/shinyOAuth/reference/oauth_provider_microsoft.html

# Spotify preconfigured provider
spotify_provider <- oauth_provider_spotify()

# Slack via OIDC discovery
# (requires network access)
if (interactive()) {
  slack_provider <- oauth_provider_slack()
}

# Keycloak
# (requires configured Keycloak realm; example below is therefore not run)
if (interactive()) {
  options(shinyOAuth.allow_insecure_oidc_loopback = TRUE)
  oauth_provider_keycloak(base_url = "http://localhost:8080", realm = "myrealm")
}

# Auth0
# (requires configured Auth0 domain; example below is therefore not run)
if (interactive()) {
  oauth_provider_auth0(domain = "your-tenant.auth0.com")
}

# Okta
# (requires configured Okta domain; example below is therefore not run)
if (interactive()) {
  oauth_provider_okta(domain = "dev-123456.okta.com")
}

Create an Apple OAuthProvider

Description

Look up Apple's login settings and return an OAuthProvider for use with oauth_client(). This helper makes an OIDC discovery request during setup.

Usage

oauth_provider_apple(name = "apple")

Arguments

Details

Configure your client with:

• Your Apple Services ID or App ID as client_id.

• A client secret created with oauth_client_secret_apple() using your Apple developer key.

• An HTTPS return address with a domain name; Apple does not accept localhost or IP addresses.

• response_mode = "form_post" and oauth_form_post_ui() when requesting email or name.

Read identity information from the validated ID token's claims. Apple has no userinfo endpoint, so userinfo_required is FALSE. The one-time user payload that Apple may send with a form POST callback is not mapped into token@userinfo; do not rely on this helper to retrieve that payload. Apple's documented email_verified strings ("true" and "false") are normalized to logical values in validated claims after signature and issuer verification. Other providers retain the standard JSON Boolean requirement.

Value

OAuthProvider object configured for Sign in with Apple

Examples

# Sign in with Apple requires an Apple Services ID, Team ID, key ID, and the
# corresponding P-256 private key. Network access is required for discovery.
if (interactive()) {
  apple_provider <- oauth_provider_apple()

  apple_secret <- oauth_client_secret_apple(
    client_id = "com.example.web",
    team_id = "ABCDEFGHIJ",
    key_id = "ABC123DEFG",
    private_key = openssl::read_key("AuthKey_ABC123DEFG.p8")
  )

  apple_client <- oauth_client(
    provider = apple_provider,
    client_id = "com.example.web",
    client_secret = apple_secret,
    redirect_uri = "https://example.com/oauth/callback",
    scopes = c("openid", "email", "name"),
    response_mode = "form_post"
  )
}

Create an Auth0 OAuthProvider (via OIDC discovery)

Description

Look up login settings for your Auth0 domain. Pass the result to oauth_client() with your registered app credentials. This helper makes a discovery request during setup.

Usage

oauth_provider_auth0(domain, name = "auth0", audience = NULL)

Arguments

Value

OAuthProvider object configured for the specified Auth0 domain

Examples

## Not run: 
oauth_provider_auth0("your-domain.auth0.com")

## End(Not run)

Create an authentik OAuthProvider (via OIDC discovery)

Description

Configure login for an authentik OAuth2/OIDC application. Supply the instance URL and application slug, then pass the registered credentials to oauth_client() with the scopes configured in authentik.

Usage

oauth_provider_authentik(
  base_url,
  application_slug,
  name = "authentik",
  token_auth_style = NULL
)

Arguments

Details

Uses authentik's default per-application issuer mode and preserves its trailing slash. Global issuer mode is not supported by this preset; configure the endpoints explicitly with oauth_provider() for that mode. For refresh tokens, both request "offline_access" and enable the corresponding scope mapping in authentik. Configure a signing key that supports RS256 for OIDC discovery. See authentik's provider guide.

Value

OAuthProvider object configured for the authentik application.

Examples

## Not run: 
oauth_provider_authentik("https://auth.example.com", "shiny-app")

## End(Not run)

Create an Amazon Cognito OAuthProvider (via OIDC discovery)

Description

Configure OIDC login for an Amazon Cognito user pool. Register an app client with the authorization code grant, configure a user pool login domain, and pass the app credentials to oauth_client() with the enabled OIDC scopes.

Usage

oauth_provider_cognito(issuer, name = "cognito", token_auth_style = NULL)

Arguments

Details

Use the exact user pool issuer, not the managed-login or custom domain. Discovery obtains authorization, token, and UserInfo URLs on that login domain while retaining the pool issuer for ID token validation. Both the original cognito-idp and updated issuer-cognito-idp issuer forms are supported, as are AWS partition-specific hostnames. No AWS credentials are needed for discovery.

See Cognito endpoints.

Value

OAuthProvider object configured for a Cognito user pool.

Examples

## Not run: 
oauth_provider_cognito(
  "https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_Example"
)

## End(Not run)

Create a GitHub OAuthProvider

Description

Create the provider configuration for a GitHub OAuth App, then pass it with your app credentials to oauth_client(). This configures profile retrieval from GitHub's API; GitHub does not return an OIDC ID token. GitHub's comma-separated token response scopes are normalized before granted permissions are validated and stored, including when name is customized.

Usage

oauth_provider_github(name = "github")

Arguments

Details

You can register a new GitHub OAuth 2.0 app in your OAuth App settings.

Value

OAuthProvider object for use with a GitHub OAuth 2.0 app

Examples

oauth_provider_github()

Create a GitLab OAuthProvider (via OIDC discovery)

Description

Configure OIDC sign-in with GitLab.com or a self-managed GitLab instance. Register an OAuth application on that instance, then pass its credentials to oauth_client() with scopes = c("openid", "profile", "email").

Usage

oauth_provider_gitlab(
  base_url = "https://gitlab.com",
  name = "gitlab",
  token_auth_style = NULL
)

Arguments

Details

Supply only the scopes your app needs; "openid" is enough to request an ID token. API and repository access require separate GitLab scopes. See GitLab's OIDC guide.

Value

OAuthProvider object configured for GitLab.

Examples

## Not run: 
oauth_provider_gitlab()
oauth_provider_gitlab("https://gitlab.example.edu")

## End(Not run)

Create a Globus Auth OAuthProvider

Description

Configure OIDC sign-in with Globus Auth using its published endpoints and RS512 ID token signatures. Register a confidential web application at https://app.globus.org/settings/developers and request scopes = c("openid", "profile", "email") on oauth_client().

Usage

oauth_provider_globus(name = "globus")

Arguments

Details

This preset does not make a discovery request. Globus currently advertises RS512 only, whereas generic OIDC discovery requires advertised RS256 support. The preset pins RS512 and the Globus JWKS URL, retaining signature, issuer, audience, nonce, UserInfo subject, and S256 PKCE validation.

This helper supports OIDC login. Globus API grants can return separate credentials for several resource servers in other_tokens. Those fields are preserved in token@extra_fields, but shinyOAuth does not automatically select, refresh, or revoke the nested tokens. Keep this login client's scopes limited to openid, profile, email, and optionally offline_access; use a separate Globus-aware integration for multi-resource API authorization. Never send the login access token to another resource server merely because a nested token granted access to it.

See the Globus Auth guide.

Value

OAuthProvider object configured for Globus Auth login.

Examples

oauth_provider_globus()

Create a Google OAuthProvider

Description

Use your Google app registration with oauth_client() to add Google sign-in. The helper configures OIDC validation and profile retrieval.

Usage

oauth_provider_google(name = "google")

Arguments

Details

You can register a new Google OAuth 2.0 app in the Google Cloud Console. Configure the client ID & secret in your OAuthClient.

This preset uses a restricted Google OIDC profile: ID tokens must have iss = "https://accounts.google.com", matching Google's discovery issuer. Google's ID token validation guidance also permits "accounts.google.com"; this alternate issuer is not accepted by this preset. Issuer comparison remains exact, as for other OIDC providers.

Value

OAuthProvider object for use with a Google OAuth 2.0 app

Examples

oauth_provider_google()

Create a Hugging Face OAuthProvider (via OIDC discovery)

Description

Configure Sign in with Hugging Face. Register an OAuth application in your Hugging Face settings, then pass its credentials to oauth_client().

Usage

oauth_provider_huggingface(name = "huggingface")

Arguments

Details

For login, request scopes = c("openid", "profile"), adding "email" only if needed. Repository access and inference require their own scopes, such as "read-repos" or "inference-api", and user consent. This preset targets confidential applications with a client secret. See Sign in with Hugging Face.

Value

OAuthProvider object configured for Hugging Face.

Examples

## Not run: 
oauth_provider_huggingface()

## End(Not run)

Create a Keycloak OAuthProvider (via OIDC discovery)

Description

Look up login settings for a Keycloak realm. Supply your server URL and realm name, then pass the result to oauth_client(). This helper contacts the Keycloak server during setup.

Usage

oauth_provider_keycloak(
  base_url,
  realm,
  name = paste0("keycloak-", realm),
  token_auth_style = "body",
  jarm_tolerate_duplicate_top_level_iss = TRUE
)

Arguments

Value

OAuthProvider object configured for the specified Keycloak realm

Examples

## Not run: 
oauth_provider_keycloak("https://login.example.com", realm = "myrealm")

## End(Not run)

Create a Microsoft (Entra ID) OAuthProvider

Description

Create provider settings for Microsoft Entra ID. Choose which accounts may sign in with tenant, then pass the provider and your own registered app's credentials to oauth_client().

Usage

oauth_provider_microsoft(
  name = "microsoft",
  tenant = c("common", "organizations", "consumers"),
  id_token_validation = NULL,
  userinfo_required = TRUE
)

Arguments

Details

Use a directory (tenant) ID to target one organization. "organizations" allows work or school accounts, "consumers" allows personal Microsoft accounts, and "common" allows both. Your app registration and app access rules must also permit the intended accounts.

ID token validation is enabled for these tenant choices. For a directory ID, the issuer must match that directory. "common" and "organizations" use Microsoft's tenant-independent issuer template and signing-key issuer rules. "consumers" uses the consumer tenant issuer. The helper restricts ID token algorithms to RS256 and fetches UserInfo from Microsoft Graph by default. Set userinfo_required = FALSE when using an API token that cannot call Graph; validated ID-token claims remain available through connection$identity().

Setting id_token_validation = FALSE disables ID token and nonce checks and leaves OAuth plus any configured profile retrieval. Keep the default for OIDC sign-in. Tenant domains and other unrecognized tenant identifiers require this explicit opt-out; otherwise use the directory GUID to retain OIDC validation.

Value

OAuthProvider object configured for Microsoft identity platform

Examples

if (
  # Example requires configured Microsoft Entra ID (Azure AD) tenant:
  nzchar(Sys.getenv("MS_TENANT")) &&
    interactive() &&
    requireNamespace("later", quietly = TRUE)
) {
  library(shiny)
  library(shinyOAuth)

  # Configure provider and client (Microsoft Entra ID with your tenant)
  client <- oauth_client(
    provider = oauth_provider_microsoft(
      # Provide your own tenant ID here (set as environment variable MS_TENANT)
      tenant = Sys.getenv("MS_TENANT")
    ),
    # Azure CLI public-client app ID; the tenant must permit this app.
    # For your deployed app, use your own registration and redirect URI:
    client_id = "04b07795-8ddb-461a-bbee-02f9e1bf7b46",
    client_secret = "",
    redirect_uri = "http://localhost:8100",
    scopes = c("openid", "profile", "email")
  )

  # UI
  ui <- oauth_ui(
    fluidPage(
      h3("OAuth demo (Microsoft Entra ID)"),
      uiOutput("oauth_error"),
      tags[["hr"]](),
      h4("Auth object (summary)"),
      verbatimTextOutput("auth_print"),
      tags[["hr"]](),
      h4("User info"),
      verbatimTextOutput("user_info")
    ),
    id = "auth",
    client = client
  )

  # Server
  server <- function(input, output, session) {
    auth <- oauth_module_server("auth", client)

    output[["auth_print"]] <- renderText({
      authenticated <- auth[["authenticated"]]
      tok <- auth[["token"]]
      err <- auth[["error"]]

      paste0(
        "Authenticated?",
        if (isTRUE(authenticated)) " YES" else " NO",
        "\n",
        "Has token? ",
        if (!is.null(tok)) "YES" else "NO",
        "\n",
        "Has error? ",
        if (!is.null(err)) "YES" else "NO",
        "\n\n",
        "Token present: ",
        !is.null(tok),
        "\n",
        "Has refresh token: ",
        !is.null(tok) && isTRUE(nzchar(tok@refresh_token)),
        "\n",
        "Has ID token: ",
        !is.null(tok) && !is.na(tok@id_token),
        "\n",
        "Expires at: ",
        if (!is.null(tok)) tok@expires_at else "N/A"
      )
    })

    output[["user_info"]] <- renderPrint({
      req(auth[["authenticated"]])
      auth[["token"]]@userinfo
    })

    observeEvent(
      list(auth[["error"]], auth[["error_description"]]),
      {
        if (interactive() && !is.null(auth[["error_description"]])) {
          rlang::inform(c(
            "OAuth error details",
            "i" = paste0("error: ", auth[["error"]]),
            "i" = paste0("error_description: ", auth[["error_description"]])
          ))
        }
      },
      ignoreInit = TRUE
    )

    output[["oauth_error"]] <- renderUI({
      if (is.null(auth[["error"]])) {
        return(NULL)
      }

      msg <- if (identical(auth[["error"]], "access_denied")) {
        "Sign-in was canceled or denied. Please try again."
      } else {
        "Authentication failed. Please try again."
      }

      div(class = "alert alert-danger", role = "alert", msg)
    })
  }

  # Need to open app in 'localhost:8100' to match with redirect_uri
  # of the public Azure CLI app (above). Browser must use 'localhost'
  # too to properly set the browser cookie. But Shiny only redirects to
  # '127.0.0.1' & blocks process once it runs. So we disable browser
  # launch by Shiny & then use 'later::later()' to open the browser
  # ourselves a short moment after the app starts
  later::later(
    function() {
      utils::browseURL("http://localhost:8100")
    },
    delay = 0.25
  )

  # Run app
  runApp(shinyApp(ui, server), port = 8100, launch.browser = FALSE)
}

Create a generic OpenID Connect (OIDC) OAuthProvider

Description

Build OIDC provider URLs from a base address and known endpoint paths. Use this when configuring an OIDC service without discovery, with its endpoint paths available from the service configuration or documentation. Use oauth_provider_oidc_discover() if your provider offers discovery, which looks up its actual URLs. This helper is for manual configuration; its default paths must match the service you are using.

Usage

oauth_provider_oidc(
  name,
  base_url,
  auth_path = "/authorize",
  token_path = "/token",
  userinfo_path = "/userinfo",
  introspection_path = "/introspect",
  use_nonce = TRUE,
  id_token_validation = TRUE,
  jwks_host_issuer_match = TRUE,
  allowed_token_types = c("Bearer"),
  ...,
  token_auth_style = "header",
  issuer = base_url
)

Arguments

Value

OAuthProvider object

Examples

# Configure generic OAuth 2.0 provider (no OIDC)
generic_provider <- oauth_provider(
  name = "example",
  auth_url = "https://example.com/oauth/authorize",
  token_url = "https://example.com/oauth/token",
  # Optional URL for fetching user info:
  userinfo_url = "https://example.com/oauth/userinfo"
)

# Configure generic OIDC provider manually
# (This defaults to using nonce & ID token validation)
generic_oidc_provider <- oauth_provider_oidc(
  name = "My OIDC",
  base_url = "https://my-issuer.example.com"
)

# Configure a OIDC provider via OIDC discovery
# (requires network access)
if (interactive()) {
  # Using Auth0 sample issuer as an example
  oidc_discovery_provider <- oauth_provider_oidc_discover(
    issuer = "https://samples.auth0.com/"
  )
}

# GitHub preconfigured provider
github_provider <- oauth_provider_github()

# Google preconfigured provider
google_provider <- oauth_provider_google()

# Microsoft preconfigured provider
# For a complete app using a custom tenant ID, see:
# https://lukakoning.github.io/shinyOAuth/reference/oauth_provider_microsoft.html

# Spotify preconfigured provider
spotify_provider <- oauth_provider_spotify()

# Slack via OIDC discovery
# (requires network access)
if (interactive()) {
  slack_provider <- oauth_provider_slack()
}

# Keycloak
# (requires configured Keycloak realm; example below is therefore not run)
if (interactive()) {
  options(shinyOAuth.allow_insecure_oidc_loopback = TRUE)
  oauth_provider_keycloak(base_url = "http://localhost:8080", realm = "myrealm")
}

# Auth0
# (requires configured Auth0 domain; example below is therefore not run)
if (interactive()) {
  oauth_provider_auth0(domain = "your-tenant.auth0.com")
}

# Okta
# (requires configured Okta domain; example below is therefore not run)
if (interactive()) {
  oauth_provider_okta(domain = "dev-123456.okta.com")
}

Discover and create an OpenID Connect (OIDC) OAuthProvider

Description

Supply your provider's issuer URL to create an OAuthProvider without entering each service URL yourself. The helper downloads the provider's discovery document (OpenID Connect Discovery) and enables OIDC login checks. Pass the result to oauth_client().

Usage

oauth_provider_oidc_discover(
  issuer,
  name = NULL,
  use_pkce = TRUE,
  use_nonce = TRUE,
  id_token_validation = TRUE,
  token_auth_style = NULL,
  id_token_allowed_algs = c("RS256", "RS384", "RS512", "ES256", "ES384", "ES512",
    "Ed25519", "EdDSA"),
  allowed_token_types = c("Bearer"),
  jwks_host_issuer_match = TRUE,
  issuer_match = c("url", "host", "none"),
  ...,
  allowed_algs = NULL
)

Arguments

Details

This function makes a network request. Call it once during app setup, outside server(). Copy the issuer URL exactly from your provider's configuration, including any trailing slash. A full discovery-document URL is also accepted.

Discovered token, UserInfo, introspection, and revocation endpoints are copied into the provider when present. Discovering an introspection endpoint does not itself require token introspection; set introspect = TRUE on oauth_client() when login and refresh must perform that check.

Discovery describes what a service supports. Your app's registration may require a particular token_auth_style, secret, or key; configure those to match the registration. Automatic selection prefers "header", then "body", then "public" when none is advertised and PKCE is enabled. For a public client registration, set token_auth_style = "public" explicitly. JWT and mTLS methods must also be selected explicitly. Explicit choices must match the discovery metadata. If token_endpoint_auth_methods_supported is omitted, the OIDC default is client_secret_basic ("header"); other methods must be advertised.

Value

OAuthProvider object configured from discovery

Discovery validation

The discovered issuer must match the requested identifier by default. Endpoints must use HTTPS. Host allowlisting does not permit HTTP: local OIDC development requires options(shinyOAuth.allow_insecure_oidc_loopback = TRUE) and a loopback host. options(shinyOAuth.allowed_hosts) can further restrict endpoint hosts. Signing-key hosts have their own policy: by default they must match the issuer host; use jwks_host_allow_only for a known different host.

The document must advertise the code flow (response_types_supported includes "code"), non-empty subject_types_supported, RS256 in id_token_signing_alg_values_supported, and a jwks_uri even when automatic ID token validation is disabled. The permitted ID token algorithms are the intersection of id_token_allowed_algs and the advertised algorithms; an empty intersection is an error. Discovery keeps PKCE S256 and errors when the provider explicitly excludes it, unless you select pkce_method = "plain".

Advanced metadata

Discovery also records capabilities for PAR, signed/encrypted requests, JARM, DPoP, mTLS, and callback issuer identification. Client construction checks the selected features against this metadata. See oauth_provider() for individual fields and the advanced security vignette for setup.

When omitted by the provider, OIDC defaults apply: the JAR request parameter is unsupported, request URIs are supported, request URI registration is not required, and response modes are c("query", "fragment"). A mode still has to be implemented by shinyOAuth to be usable. Caller-published request URI registration must be arranged with the provider; discovery cannot check your registration. PAR-issued handles do not need that client-hosted URI registration.

Examples

# Configure generic OAuth 2.0 provider (no OIDC)
generic_provider <- oauth_provider(
  name = "example",
  auth_url = "https://example.com/oauth/authorize",
  token_url = "https://example.com/oauth/token",
  # Optional URL for fetching user info:
  userinfo_url = "https://example.com/oauth/userinfo"
)

# Configure generic OIDC provider manually
# (This defaults to using nonce & ID token validation)
generic_oidc_provider <- oauth_provider_oidc(
  name = "My OIDC",
  base_url = "https://my-issuer.example.com"
)

# Configure a OIDC provider via OIDC discovery
# (requires network access)
if (interactive()) {
  # Using Auth0 sample issuer as an example
  oidc_discovery_provider <- oauth_provider_oidc_discover(
    issuer = "https://samples.auth0.com/"
  )
}

# GitHub preconfigured provider
github_provider <- oauth_provider_github()

# Google preconfigured provider
google_provider <- oauth_provider_google()

# Microsoft preconfigured provider
# For a complete app using a custom tenant ID, see:
# https://lukakoning.github.io/shinyOAuth/reference/oauth_provider_microsoft.html

# Spotify preconfigured provider
spotify_provider <- oauth_provider_spotify()

# Slack via OIDC discovery
# (requires network access)
if (interactive()) {
  slack_provider <- oauth_provider_slack()
}

# Keycloak
# (requires configured Keycloak realm; example below is therefore not run)
if (interactive()) {
  options(shinyOAuth.allow_insecure_oidc_loopback = TRUE)
  oauth_provider_keycloak(base_url = "http://localhost:8080", realm = "myrealm")
}

# Auth0
# (requires configured Auth0 domain; example below is therefore not run)
if (interactive()) {
  oauth_provider_auth0(domain = "your-tenant.auth0.com")
}

# Okta
# (requires configured Okta domain; example below is therefore not run)
if (interactive()) {
  oauth_provider_okta(domain = "dev-123456.okta.com")
}

Create an Okta OAuthProvider (via OIDC discovery)

Description

Look up login settings for your Okta domain and authorization server. Pass the result to oauth_client() with your registered app credentials. This helper makes a discovery request during setup.

Usage

oauth_provider_okta(domain, auth_server = "default", name = "okta")

Arguments

Value

OAuthProvider object configured for the specified Okta domain

Examples

## Not run: 
oauth_provider_okta("dev-123456.okta.com")

## End(Not run)

Create an ORCID OAuthProvider (via OIDC discovery)

Description

Configure researcher sign-in with ORCID. Discovery selects ORCID's client_secret_post authentication; pass a client secret to oauth_client().

Usage

oauth_provider_orcid(name = "orcid", sandbox = FALSE)

Arguments

Details

Request scopes = "openid" on the client. ORCID uses this instead of ⁠/authenticate⁠ for OIDC login; do not request both. Its OIDC metadata does not advertise profile or email scopes. Additional record permissions depend on whether you registered a Public or Member API client.

Sandbox and production require separate credentials and user accounts. Production redirect URIs must use HTTPS. ORCID does not advertise PKCE in its discovery metadata, so this confidential-client preset uses client authentication and validated OIDC nonce without claiming PKCE protection. See the ORCID authentication guide.

Value

OAuthProvider object configured for ORCID.

Examples

## Not run: 
oauth_provider_orcid()
oauth_provider_orcid(sandbox = TRUE)

## End(Not run)

Create a Slack OAuthProvider (via OIDC discovery)

Description

Look up Slack's OpenID Connect settings for Sign in with Slack. This helper contacts the discovery service during setup; pass its result to oauth_client() with your Slack app credentials.

Usage

oauth_provider_slack(
  name = "slack",
  profile = c("confidential", "public_pkce")
)

Arguments