Configure ownership of retained OAuth connections

Defines ownership of saved connections for oauth_connections(): either the browser that created them or an account authenticated by the application. The manager applies the policy when its matching retention mode is enabled; these functions create configuration only.

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

idle_timeout

Maximum owner inactivity in seconds. Resource and status reads do not count as activity. The manager's touch() records explicit activity; connecting, explicit refresh and disconnect also count.

absolute_timeout

Maximum owner lifetime in seconds, independent of activity. Must be at least idle_timeout.

same_site

Owner-cookie policy, "Lax" for top-level authorization navigation or "Strict". Embedded cross-site ownership is not supported. With "Strict", oauth_connections_ui() may show a brief intermediate page when returning from another site, so the browser can restore the saved session. See Deployment details below if a proxy changes browser headers.

allow_http_loopback

Explicit development-only exception for HTTP on localhost or a loopback address. Default FALSE requires HTTPS. The exception cannot provide a Secure, host-prefixed owner cookie.

max_entries

Maximum owner-registry entries per manager, a positive whole number. Browser mode counts browsers that authorize a service. A separate provisional visitor pool has the same limit; its oldest entries may be replaced and expire after at most five minutes, unless a live authorization transaction protects them until its expiry. When all visitor entries have pending authorizations, new visitors are rejected. Account mode counts authentication generations, including retired generations until their local reauthentication deadline. This limit is independent of the connection store's max_entries.

resolver

Trusted application function accepting the current Shiny session. On every call it must validate the application's local login and return NULL if unauthenticated, otherwise a plain list containing subject, session_id, generation, authenticated_at and expires_at. The first three are non-empty strings; the timestamps are finite Unix seconds. Subject is the stable local account ID. Session ID and generation identify the current local authentication session, as established by the application's verified local login rather than the external OAuth authorization.

reauth_after_seconds

Maximum age of the verified local authentication, in seconds. Required for account retention; refresh cannot reset this age.

x

An OAuthOwnerPolicy to print.

...

Unused print arguments.

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.

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.

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. Local-session validation belongs to the application's resolver, including signature, expiry, revocation and account changes.

Deployment details

Browser cookies are shared across ports on a hostname, so another HTTPS service receiving the owner cookie could reuse it. Cookie names do not establish separate trust boundaries for those services. With same_site = "Strict", external-entry recovery needs same-origin Fetch Metadata, Referer or Origin headers; a proxy must preserve that information.

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. Retired generations count toward max_entries throughout that window.

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)
#> $mode
#> [1] "browser"
#> 
#> $idle_timeout
#> [1] 900
#> 
#> $absolute_timeout
#> [1] 28800
#> 
#> $same_site
#> [1] "Lax"
#> 
#> $allow_http_loopback
#> [1] FALSE
#> 
#> $max_entries
#> [1] 1000
#> 
#> attr(,"class")
#> [1] "OAuthOwnerPolicy"

# 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
  )
}