Add R API for Custom OAuth Integrations (and add support getDelegatedAzureToken in VSCode and Positron sessions)

[zachhannum]

Summary

Resolves rstudio/rstudio-pro#

This PR adds comprehensive R API support for custom OAuth integrations in Posit Workbench, enabling users to authenticate with external services through Workbench's OAuth infrastructure. It also enhances getDelegatedAzureToken() to work in non-RStudio IDEs (VSCode, Positron).

Usage Examples

# List all OAuth integrations
integrations <- getOAuthIntegrations()

# Find an authenticated integration by name
integration <- findOAuthIntegration(name = "github-prod", authenticated = TRUE)

# Get OAuth credentials for an integration
creds <- getOAuthCredentials(audience = integration$guid)

# Use the access token
httr::GET(
  "https://api.github.com/user",
  httr::add_headers(Authorization = paste("Bearer", creds$access_token))
)

# Get delegated Azure token (now works in VSCode/Positron)
token <- getDelegatedAzureToken("https://storage.azure.com")

Implementation Details

• Uses Workbench RPC endpoints for OAuth operations
• Authenticates via X-RS-Session-Server-RPC-Cookie header
• Supports custom CA bundles via REQUESTS_CA_BUNDLE and CURL_CA_BUNDLE environment variables
• Comprehensive error handling for OAuth2 errors, missing cookies, and version mismatches
• Gracefully handles environments outside Workbench

Testing

• Unit tests cover error conditions including missing environment variables, version checks, RPC cookie handling, and parameter validation
• Tests verify graceful degradation outside Workbench environments

[Copilot]

Pull request overview

This PR adds R API support for OAuth integrations in Posit Workbench and extends Azure token functionality to work in VSCode and Positron. The main additions enable R users to authenticate with external services through Workbench's OAuth infrastructure and retrieve delegated Azure tokens in non-RStudio IDEs.

Key changes:

• Added four new OAuth-related functions: getOAuthIntegrations(), findOAuthIntegration(), getOAuthIntegration(), and getOAuthCredentials()
• Enhanced getDelegatedAzureToken() to fall back to RPC endpoints when RStudio API is unavailable
• Added comprehensive error handling for version checks, session validation, and OAuth2 errors

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
R/auth.R	Core implementation of OAuth API functions and internal helpers for RPC calls, session checks, and version validation
tests/testthat/test-oauth.R	Unit tests covering error conditions, environment variable handling, and parameter validation
DESCRIPTION	Added httr and jsonlite as Suggests dependencies for HTTP/JSON functionality
NAMESPACE	Exported four new OAuth-related functions
man/getOAuthIntegrations.Rd	Documentation for retrieving all OAuth integrations
man/findOAuthIntegration.Rd	Documentation for searching OAuth integrations by criteria
man/getOAuthIntegration.Rd	Documentation for retrieving a specific integration by GUID
man/getOAuthCredentials.Rd	Documentation for retrieving OAuth credentials
man/getDelegatedAzureToken.Rd	Updated documentation with return value description
man/rstudio-documents.Rd	Updated documentation for documentNew type parameter
R/document-api.R	Modified documentNew to use explicit choices parameter

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[atheriel]

I'm fine with this so long as Kevin (as the actual maintainer) doesn't have major issues.

[kevinushey]

Overall LGTM, but I think we want to avoid the auto-unboxing behavior and instead explicitly indicate whether we desire unboxing for specific elements of the values we're POSTing.