Improve control over redirects during auth code flows #248

atheriel · 2023-07-05T16:16:52Z

When sheparding a user through an interactive authorisation code flow to access APIs protected by OAuth2, the oauth_flow_auth_code() function runs a temporary webserver on localhost to capture the code. This is a very common technique for OAuth client libraries.

Unfortunately, this doesn't work in environments where localhost is probably inaccessible to users -- which is normally the case on RStudio Server and Posit Workbench. Previously the oauth_flow_auth_code() function would hang indefinitely in these environments.

This commit fixes this failure mode by attempting to detect when this temporary localhost server will actually work and only runs one if it will.

Of course, this doesn't resolve the issue for users that can't run a localhost server -- so in this situation, we now allow users to manually paste the authorisation code into the console from... somewhere. In the likely event that they don't want to be redirected to localhost for this step, this commit also fulfills the longstanding request for control over the redirect URL.

The combination of a manual copy & paste step with a custom redirect URL is what the gargle package terms the "pseudo out-of-band" flow, and the design used here is largely based on that package.

Because of this compatibility, users could register the existing public page at https://www.tidyverse.org/google-callback/ with their OAuth provider, host their own clone, or create a variant.

Control over the redirect URL is backwards-compatible but does require making the host_name parameter deprecated, unfortunately.

Unit tests for new functions are included, as are various updates to the documentation.

Fixes #165 and #176.

jennybc

Exciting!

I feel like we should discuss this recommendation:

Because of this compatibility, users could register the existing public page at https://www.tidyverse.org/google-callback/ with their OAuth provider, host their own clone, or create a variant.

I've gotten the question over in gargle land whether it's OK for other folks to use https://www.tidyverse.org/google-callback/ and, while I can't see any reason to say "no, please don't", it also feels a bit odd. How do we feel about that? 🤔

jennybc · 2023-07-05T16:59:12Z

R/oauth-flow-auth-code.R

-#' low-level functions can be used to assemble a custom flow for APIs that are
-#' further from the spec:
+#' `oauth_flow_auth_code()` is a high-level wrapper that should work with APIs
+#' that adhere relatively closely to the spec. When possible, it redirects users


I wonder if "redirects users" is the right phrasing. Because, when this works, the user tends to be completely unaware of the brief existence of the local webserver. Maybe reword this?

What about "redirects the browser"?

Updated the wording.

R/oauth-flow-auth-code.R

atheriel · 2023-07-05T17:55:49Z

You're right, I don't feel like we can recommend using the gargle site in its current incarnation. The language on that page is very narrowly scoped to its target audience. I mentioned it mostly for demo purposes.

It's also my hope that the upcoming Workbench changes for redirects will make this pseudo-OOB workflow more uncommon -- it's really here as a last resort.

(As an aside: compatibility with gargle here might make it easier to refactor gargle to use httr2 one day.)

hadley

Looks great!

I think if we continue further down this road, we'll probably want a vignette on the pseudo-OOB approach.

R/oauth-flow-auth-code.R

hadley · 2023-07-06T20:32:28Z

R/oauth-flow-auth-code.R

+
+  # For backwards compatibility, fall back to the original redirect URL
+  # construction.
+  if (!is.null(host_name)) {


Can you formally deprecate host_name? (https://lifecycle.r-lib.org/articles/communicate.html#deprecate-an-argument-keeping-the-existing-default)

tests/testthat/test-oauth-flow-auth-code.R

R/oauth-flow-auth-code.R

When sheparding a user through an interactive authorisation code flow to access APIs protected by OAuth2, the oauth_flow_auth_code() function runs a temporary webserver on localhost to capture the code. This is a very common technique for OAuth client libraries. Unfortunately, this doesn't work in environments where localhost is probably inaccessible to users -- which is normally the case on RStudio Server and Posit Workbench. Previously the oauth_flow_auth_code() function would hang indefinitely in these environments. This commit fixes this failure mode by attempting to detect when this temporary localhost server will actually work and only runs one if it will. Of course, this doesn't resolve the issue for users that can't run a localhost server -- so in this situation, we now allow users to manually paste the authorisation code into the console from... somewhere. In the likely event that they don't want to be redirected to localhost for this step, this commit also fulfills the longstanding request for control over the redirect URL. The combination of a manual copy & paste step with a custom redirect URL is what the gargle package terms the "pseudo out-of-band" flow, and the design used here is largely based on that package. Because of this compatibility, users could register the existing public page at https://www.tidyverse.org/google-callback/ with their OAuth provider, host their own clone, or create a variant. Control over the redirect URL is backwards-compatible but does require making the 'host_name' parameter deprecated, unfortunately. Unit tests for new functions are included, as are various updates to the documentation. Fixes r-lib#165 and r-lib#176. Signed-off-by: Aaron Jacobs <[email protected]>

R/oauth-flow-auth-code.R

DESCRIPTION

R/oauth-flow-auth-code.R

NEWS.md

jonthegeek · 2023-08-25T12:26:58Z

This looks great! I can't wait for it to be merged!

hadley · 2023-08-29T21:03:52Z

R/oauth-flow-auth-code.R

                                 host_ip = "127.0.0.1",
-                                 port = httpuv::randomPort()
+                                 port = httpuv::randomPort(),
+                                 redirect_uri = "http://localhost"


I wonder if we should deprecate port too, replacing this default with something that automatically adds the random port; i.e. we make redirect_uri the primary argument and extract the other pieces using url_parse().

Oh that's what I said above, previously 😆. Let's leave this as is for this PR and consider a refactoring in a future PR: #291.

Fixes #149, but will need #248 to be useful.

atheriel · 2023-08-30T13:33:11Z

R/oauth-flow-auth-code.R

@@ -56,9 +56,11 @@ req_oauth_auth_code <- function(req, client,
                                pkce = TRUE,
                                auth_params = list(),
                                token_params = list(),
+                                type = c("desktop", "web"),


For consistency, maybe we should use type "hosted" here instead of type "web".

It occurred to me that maybe we could do this automatically based on whether or not the redirect_url was to localhost?

Let me merge this and then present a concrete proposal.

For data scientists using local tools or working in the IDE, authentication with APIs or databases that use the OAuth2 authorisation code flow (e.g. Google, Azure, or GitHub) typically work by running a temporary HTTP server on localhost and using that as the redirect URL. When a user gets redirected to localhost, the temporary HTTP server captures the code automatically and surfaces it to the caller. Unfortunately, this doesn't work at all on Workbench, because you can't just "redirect to localhost" like you can on your desktop. In r-lib#248 and follow-ups we added a workaround for this issue that we term the "pseudo out-of-band" flow -- that mechanism was pioneered by the {gargle} package in response to Google deprecating the original "out-of-band" flow. This commit adds support for a *third* mechanism for the auth code flow which uses a feature of the upcoming Workbench release that allows it to serve as a redirect URL for arbitrary OAuth2 applications on a static /oauth_redirect_callback endpoint. httr2 can retrieve any code sent to this URL by calling a simple JSON API at a static /oauth_code endpoint. This mechanism has strong appeal over the pseudo out-of-band flow because it sidesteps the requirement that users copy & paste the code, making it feel much more natural and automatic. It also avoids the need to ask users to host a static "capture your code" page, a la <https://www.tidyverse.org/google-callback/>, because every Workbench instance now has one. (This Workbench feature was explicitly designed for packages like httr2 to make use of so that the auth code flow starts feeling like magic once again.) I've decided to introduce client-specific environment variables here -- specifically, HTTR2_OAUTH_REDIRECT_URL and HTTR2_OAUTH_CODE_SOURCE_URL -- rather than having platform-specific ones prefixed with `WORKBENCH_`. If you're running a daily build of Workbench locally, you can test this as follows: local({ # Automatically determine the Workbench server's URL. We use # RSTUDIO_HTTP_REFERER here, which is only set in RStudio Pro sessions. url_split <- strsplit(Sys.getenv("RSTUDIO_HTTP_REFERER"), "/s/", fixed = TRUE)[[1]] if (nchar(url_split[1]) != 0L && length(url_split) == 2L) { base_url <- url_split[1] Sys.setenv( HTTR2_OAUTH_REDIRECT_URL = sprintf("%s/oauth_redirect_callback", base_url), HTTR2_OAUTH_CODE_SOURCE_URL = sprintf("%s/oauth_code", base_url) ) } }) client <- oauth_client( id = "28acfec0674bb3da9f38", secret = obfuscated(paste0( "J9iiGmyelHltyxqrHXW41ZZPZamyUNxSX1_uKnv", "PeinhhxET_7FfUs2X0LLKotXY2bpgOMoHRCo" )), token_url = "https://github.com/login/oauth/access_token", name = "hadley-oauth-test" ) oauth_flow_auth_code( client, auth_url = "https://github.com/login/oauth/authorize" ) In the future we can set the environment variables in Workbench sessions directly. Unit tests are included. Signed-off-by: Aaron Jacobs <[email protected]>

For data scientists using local tools or working in the IDE, authentication with APIs or databases that use the OAuth2 authorisation code flow (e.g. Google, Azure, or GitHub) typically work by running a temporary HTTP server on localhost and using that as the redirect URL. When a user gets redirected to localhost, the temporary HTTP server captures the code automatically and surfaces it to the caller. Unfortunately, this doesn't work at all on Workbench, because you can't just "redirect to localhost" like you can on your desktop. In #248 and follow-ups we added a workaround for this issue that we term the "pseudo out-of-band" flow -- that mechanism was pioneered by the {gargle} package in response to Google deprecating the original "out-of-band" flow. This commit adds support for a *third* mechanism for the auth code flow which uses a feature of the upcoming Workbench release that allows it to serve as a redirect URL for arbitrary OAuth2 applications on a static /oauth_redirect_callback endpoint. httr2 can retrieve any code sent to this URL by calling a simple JSON API at a static /oauth_code endpoint. This mechanism has strong appeal over the pseudo out-of-band flow because it sidesteps the requirement that users copy & paste the code, making it feel much more natural and automatic. It also avoids the need to ask users to host a static "capture your code" page, a la <https://www.tidyverse.org/google-callback/>, because every Workbench instance now has one. (This Workbench feature was explicitly designed for packages like httr2 to make use of so that the auth code flow starts feeling like magic once again.) I've decided to introduce client-specific environment variables here -- specifically, HTTR2_OAUTH_REDIRECT_URL and HTTR2_OAUTH_CODE_SOURCE_URL -- rather than having platform-specific ones prefixed with `WORKBENCH_`. If you're running a daily build of Workbench locally, you can test this as follows: local({ # Automatically determine the Workbench server's URL. We use # RSTUDIO_HTTP_REFERER here, which is only set in RStudio Pro sessions. url_split <- strsplit(Sys.getenv("RSTUDIO_HTTP_REFERER"), "/s/", fixed = TRUE)[[1]] if (nchar(url_split[1]) != 0L && length(url_split) == 2L) { base_url <- url_split[1] Sys.setenv( HTTR2_OAUTH_REDIRECT_URL = sprintf("%s/oauth_redirect_callback", base_url), HTTR2_OAUTH_CODE_SOURCE_URL = sprintf("%s/oauth_code", base_url) ) } }) client <- oauth_client( id = "28acfec0674bb3da9f38", secret = obfuscated(paste0( "J9iiGmyelHltyxqrHXW41ZZPZamyUNxSX1_uKnv", "PeinhhxET_7FfUs2X0LLKotXY2bpgOMoHRCo" )), token_url = "https://github.com/login/oauth/access_token", name = "hadley-oauth-test" ) oauth_flow_auth_code( client, auth_url = "https://github.com/login/oauth/authorize" ) In the future we can set the environment variables in Workbench sessions directly. Unit tests are included. Signed-off-by: Aaron Jacobs <[email protected]>

atheriel force-pushed the aj-oauth-auth-code-improvements branch from 21deb15 to faa980d Compare July 5, 2023 16:29

jennybc reviewed Jul 5, 2023

View reviewed changes

hadley approved these changes Jul 6, 2023

View reviewed changes

atheriel commented Jul 6, 2023

View reviewed changes

R/oauth-flow-auth-code.R Outdated Show resolved Hide resolved

atheriel force-pushed the aj-oauth-auth-code-improvements branch 3 times, most recently from 478bc46 to 23bf886 Compare July 7, 2023 13:44

atheriel force-pushed the aj-oauth-auth-code-improvements branch from 23bf886 to cdb4cce Compare July 7, 2023 13:44

hadley approved these changes Jul 18, 2023

View reviewed changes

R/oauth-flow-auth-code.R Outdated Show resolved Hide resolved

DESCRIPTION Show resolved Hide resolved

R/oauth-flow-auth-code.R Outdated Show resolved Hide resolved

NEWS.md Outdated Show resolved Hide resolved

hadley reviewed Aug 29, 2023

View reviewed changes

hadley added a commit that referenced this pull request Aug 29, 2023

Support non-root path in oauth_flow_auth_code_listen()

0e18628

Fixes #149, but will need #248 to be useful.

hadley mentioned this pull request Aug 29, 2023

Support non-root path in oauth_flow_auth_code_listen() #290

Closed

hadley added 4 commits August 29, 2023 16:08

use_lifecycle()

1743ddb

Tweak news

c8a91c9

Tweak docs

e93ab04

Make type of code entry explicit

925635a

hadley requested a review from jennybc August 29, 2023 22:39

atheriel commented Aug 30, 2023

View reviewed changes

hadley merged commit 7f603ff into r-lib:main Aug 30, 2023
12 checks passed

atheriel deleted the aj-oauth-auth-code-improvements branch September 25, 2023 14:39

atheriel mentioned this pull request Sep 25, 2023

Add support for using Workbench's generic OAuth2 code capture #320

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve control over redirects during auth code flows #248

Improve control over redirects during auth code flows #248

atheriel commented Jul 5, 2023

jennybc left a comment

jennybc Jul 5, 2023

atheriel Jul 5, 2023

atheriel Jul 7, 2023

atheriel commented Jul 5, 2023

hadley left a comment

hadley Jul 6, 2023

atheriel Jul 7, 2023

jonthegeek commented Aug 25, 2023

hadley Aug 29, 2023 •

edited

Loading

hadley Aug 29, 2023

atheriel Aug 30, 2023

hadley Aug 30, 2023

hadley Aug 30, 2023

Improve control over redirects during auth code flows #248

Improve control over redirects during auth code flows #248

Conversation

atheriel commented Jul 5, 2023

jennybc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atheriel commented Jul 5, 2023

hadley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonthegeek commented Aug 25, 2023

hadley Aug 29, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hadley Aug 29, 2023 •

edited

Loading