% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/oauth-server-metadata.R
\name{oauth_server_metadata}
\alias{oauth_server_metadata}
\title{Discover OAuth server metadata}
\usage{
oauth_server_metadata(issuer, type = c("openid", "oauth"), url = NULL)
}
\arguments{
\item{issuer}{The issuer URL, e.g. \code{"https://accounts.google.com"}. The
metadata URL is derived from it according to \code{type}.}

\item{type}{Which well-known suffix to use when \code{url} is not supplied:
\itemize{
\item \code{"openid"} (the default) appends \verb{/.well-known/openid-configuration},
the form served by essentially every major provider. Despite the name,
it is a superset that also advertises the OAuth endpoints, so it is the
better default even for plain OAuth.
\item \code{"oauth"} inserts \verb{/.well-known/oauth-authorization-server} between the
origin and any path, as defined in \href{https://datatracker.ietf.org/doc/html/rfc8414}{RFC 8414}. Use this for the few
providers that serve only the OAuth document.
}}

\item{url}{Optionally, the full metadata document URL. Use this as an escape
hatch for providers that follow neither well-known convention. When
supplied, \code{issuer} is only used for validation and can be omitted.}
}
\value{
An S3 list with class \code{httr2_oauth_server_metadata} containing the
full parsed metadata document. Endpoints that the provider does not
advertise are simply absent.
}
\description{
\code{oauth_server_metadata()} fetches and parses an OAuth 2.0 Authorization
Server Metadata document (\href{https://datatracker.ietf.org/doc/html/rfc8414}{RFC 8414}) or OpenID Connect Discovery
document, returning the endpoints advertised by an issuer.

Use it to discover values like \code{authorization_endpoint}, \code{token_endpoint},
and \code{device_authorization_endpoint} rather than hard-coding them. Pass the
result to \code{\link[=oauth_client]{oauth_client()}} as \code{metadata} and the endpoints are wired up for
you:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{metadata <- oauth_server_metadata("https://accounts.google.com")
client <- oauth_client("id", metadata = metadata, secret = "...")
token <- oauth_flow_auth_code(client)
}\if{html}{\out{</div>}}

As a security measure, the \code{issuer} reported in the returned document is
validated against the requested \code{issuer} (\href{https://datatracker.ietf.org/doc/html/rfc8414#section-3.3}{Section 3.3 of RFC 8414}); a mismatch
is an error. This check is skipped when \code{url} is supplied without \code{issuer}.
}
\examples{
\dontshow{if (is_online()) withAutoprint(\{ # examplesIf}
oauth_server_metadata("https://accounts.google.com")
\dontshow{\}) # examplesIf}
}
\seealso{
Other OAuth flows:
\code{\link[=req_oauth_auth_code]{req_oauth_auth_code()}},
\code{\link[=req_oauth_bearer_jwt]{req_oauth_bearer_jwt()}},
\code{\link[=req_oauth_client_credentials]{req_oauth_client_credentials()}},
\code{\link[=req_oauth_password]{req_oauth_password()}},
\code{\link[=req_oauth_refresh]{req_oauth_refresh()}},
\code{\link[=req_oauth_token_exchange]{req_oauth_token_exchange()}}
}
\concept{OAuth flows}
