% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ppm-sso.R
\name{ppm_sso_login}
\alias{ppm_sso_login}
\alias{ppm_sso_logout}
\alias{ppm_sso_status}
\title{Posit Package Manager single sign-on (SSO) authentication}
\usage{
ppm_sso_login()

ppm_sso_logout()

ppm_sso_status(connect = FALSE)
}
\arguments{
\item{connect}{If \code{TRUE}, also checks if the token is valid by making a test
request to the Package Manager instance. This requires an active internet
connection and may take a few seconds. If \code{FALSE}, only checks if a
token is cached and not expired.}
}
\value{
\code{ppm_sso_login()} returns the obtained token invisibly.

\code{ppm_sso_logout()} does not return anything.

\code{ppm_sso_status()} returns a list with the following components:
\itemize{
\item \code{ppm_url}: The URL of the Package Manager instance.
\item \code{token_file}: The path of the cached token file.
\item \code{token}: The cached token (partially masked for display) or \code{NA} if
no token is found locally.
\item \code{valid}: \code{TRUE} if the token is valid (only if \code{connect = TRUE}),
\code{FALSE} if invalid, or \code{NA} if not checked.
\item \code{issuer}: The issuer of the token, or \code{NA} if not available.
\item \code{subject}: The subject of the token, or \code{NA} if not available.
\item \code{audience}: The audience of the token, or \code{NA} if not available.
\item \code{issued_at}: The issue time of the token as a POSIXct object, or \code{NA}
if not available.
\item \code{expires_at}: The expiration time of the token as a POSIXct object,
or \code{NA}  if not available.
\item \code{expired}: \code{TRUE} if the token is expired, \code{FALSE} if not expired,
or \code{NA} if expiration time is not available.
\item \code{expires_in}: The time until expiration as a difftime object, or
\code{NA} if expiration time is not available or the token is already
expired.
}
}
\description{
Posit Package Manager single sign-on (SSO) authentication
}
\details{
\subsection{Set up SSO authentication:}{
\itemize{
\item Set the \code{PACKAGEMANAGER_ADDRESS} environment variable to the URL of
your RStudio Package Manager instance. For example, add this line to
your \code{.Renviron} file:

\if{html}{\out{<div class="sourceCode">}}\preformatted{PACKAGEMANAGER_ADDRESS=https://<ppm-url>
}\if{html}{\out{</div>}}

Alternatively, you can also set it in your shell profile on Unix,
or in the System or User environment variables on Windows.
\item Set \code{options(repos)} to include a repository from your Package Manager
instance. Include \verb{__token__} as the username in the URL. For example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{options(repos = c(
  PPM = "https://__token__@<ppm-url>/<repo-path>",
  getOption("repos")
))
}\if{html}{\out{</div>}}

You probably want to add this to your \code{.Rprofile} file, so that it is
set in every R session.
\item Call \code{\link[=repo_get]{repo_get()}} to trigger authentication and caching of the token.
You should be prompted to log in via your browser, and the obtained
token will be cached for future use. Call \code{ppm_sso_status()} to check
the status of your authentication, including the path of the cached
token and its expiration time.
\item Alternatively, you can call \code{ppm_sso_login()} directly to trigger
the login process directly.
}

\code{ppm_sso_login()} initiates the SSO login process. You should be
prompted to log in via your browser, and the obtained token will be
cached for future use.
}

\code{ppm_sso_logout()} removes the cached token, effectively logging you
out. If there is no cached token, it does nothing.

\code{ppm_sso_status()} checks the status of your authentication, including
the path of the cached token and its expiration time.
}
\examples{
\dontshow{if (FALSE) withAutoprint(\{ # examplesIf}
Sys.setenv(PACKAGEMANAGER_ADDRESS = "https://<ppm-url>")
options(repos = c(
  PPM = "https://__token__@<ppm-url>/<repo-path>",
  getOption("repos")
))
ppm_sso_login()
ppm_sso_status()
ppm_sso_status(connect = TRUE)
ppm_sso_logout()
\dontshow{\}) # examplesIf}
}
\seealso{
\link{Authenticated repositories},
\url{https://docs.posit.co/rspm/admin/authentication/}
}
