[Openvpn-devel] Introduce webauth auth pending method and deprecate openurl

Message ID 20210716121848.67888-1-arne@rfc2549.org
State Changes Requested
Headers show
Series
  • [Openvpn-devel] Introduce webauth auth pending method and deprecate openurl
Related show

Commit Message

Arne Schwabe July 16, 2021, 12:18 p.m.
The experience with openurl/OPEN_URL has shown that just sending
a URL to a client is not enough and we often need different
behaviour of the client depending on circumstances. Replace
OPEN_URL with a more flexible WEBAUTH pending auth method.

Signed-off-by: Arne Schwabe <arne@rfc2549.org>
---
 doc/management-notes.txt    | 41 ++++++++++++++++++++++++++-----------
 include/openvpn-plugin.h.in |  2 +-
 2 files changed, 30 insertions(+), 13 deletions(-)

Comments

Arne Schwabe July 16, 2021, 12:33 p.m. | #1
Am 16.07.21 um 14:18 schrieb Arne Schwabe:
> The experience with openurl/OPEN_URL has shown that just sending
> a URL to a client is not enough and we often need different
> behaviour of the client depending on circumstances. Replace
> OPEN_URL with a more flexible WEBAUTH pending auth method.

Just as FYI this is more of an RFC to give other people an early
opportunity to object/remark or request changes to the protocol as we
are going to implement this very soon this way if no objections are raised.

Arne
Selva Nair July 16, 2021, 1:49 p.m. | #2
Hi,

On Fri, Jul 16, 2021 at 8:19 AM Arne Schwabe <arne@rfc2549.org> wrote:

> The experience with openurl/OPEN_URL has shown that just sending
> a URL to a client is not enough and we often need different
> behaviour of the client depending on circumstances. Replace
> OPEN_URL with a more flexible WEBAUTH pending auth method.
>

As the two other methods are signalled as OPEN_URL and CR_TEXT, please
consider using WEB_AUTH.  The corresponding IV_SSO value can still be named
"webauth" as you have below, consistent with crtext and openurl.

I know it's just a keyword, but consistency makes it easier to write
consuming code without repeatedly referring to the docs.


> Signed-off-by: Arne Schwabe <arne@rfc2549.org>
> ---
>  doc/management-notes.txt    | 41 ++++++++++++++++++++++++++-----------
>  include/openvpn-plugin.h.in |  2 +-
>  2 files changed, 30 insertions(+), 13 deletions(-)
>
> diff --git a/doc/management-notes.txt b/doc/management-notes.txt
> index c20344298..4572d967f 100644
> --- a/doc/management-notes.txt
> +++ b/doc/management-notes.txt
> @@ -645,11 +645,11 @@ Before issuing a client-pending-auth to a client
> instead of a
>  client-auth/client-deny, the server should check the IV_SSO
>  environment variable for whether the method is supported. Currently
>  defined methods are crtext for challenge/response using text
> -(e.g., TOTP), openurl and proxy_url for opening a URL in the client to
> -continue authentication. A client supporting the first two methods would
> -set
> +(e.g., TOTP), openurl (deprecated) and webauth for opening a URL in
>

As we have not released any versions with openurl, why not just replace it
webauth? Anyway, below you are replacing proxy_url to use WEB_AUTH instead
of PROXY_URL.


> +the client to continue authentication. A client supporting the last
> +two methods would set


> -    setenv IV_SSO openurl,crtext
> +    setenv IV_SSO webauth,crtext
>

The last two methods as per the text above are openutl and webauth. Reword
as
"A client supporting webauth and crtext would set
setenv IV_SSO webauth,crtext"


>
>  The variable name IV_SSO is historic as AUTH_PENDING was first used
>  to signal single sign on support. To keep compatibility with existing
> @@ -668,33 +668,50 @@ notification as
>  where {EXTRA} is formatted as received from the server.
>  Currently defined formats for {EXTRA} are detailed below.
>
> -openurl
> -========
> +webauth and openurl
> +===================
>  For a web based extra authentication (like for
>  SSO/SAML) {EXTRA} should be
>
>      OPEN_URL:url
>
> -and client should ask the user to open the URL to continue.
> +or
> +
> +    WEBAUTH:flags:url

+
> +The OPEN_URL method is deprecated as it does not allow to send flags which
> +proved to be needed to signal certain behaviour to the client.
> +
> +The client should ask the user to open the URL to continue.
>
>  The space in a control message is limited, so this url should be kept
>  short to avoid issues. If a longer url is required a URL that redirects
> -to the longer URL should be sent instead.
> +to the longer URL should be sent instead. The total length is limited to
> 1024
> +bytes which includes the INFO_PRE:WEBAUTH:flags.

+
> +flags is a list of flags which are separated by commas. Currently defined
> +flags are:
> +
> +- proxy     (see next pargraph)
> +- hidden    start the webview in hidden mode (see openvpn3 webauth
> documentation)
> +- external  Do not use an internal webview but use an external browser.
> Some
> +            authentication providers refuse to work in an internal
> webview.
> +
>
>  A complete documentation how URLs should be handled on the client is
> available
>  in the openvpn3 repository:
>
>  https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md
>
> -proxy_url
> -========
> -This is a variant of openurl that allows opening a url via an
> +webauth with proxy
> +==================
> +This is a variant of webauth that allows opening a url via an
>  HTTP proxy. It could be used to avoid issues with OpenVPN connection's
>  persist-tun that may cause the web server to be unreachable.
>  The client should announce proxy_url in its IV_SSO and parse the
>  PROXY_URL message. The format of {EXTRA} in this case is
>
> -
> PROXY_URL:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>:url
> +
> WEBAUTH:proxy=<proxy>;<proxy_port>;<proxyuser_base64>;<proxy_password_base64>,flags:url

 The proxy should be a literal IPv4 address or IPv6 address enclosed in []
> to avoid
>  ambiguity in parsing. A literal IP address is preferred as DNS might not
> be
> diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in
> index 79969bf89..944294b22 100644
> --- a/include/openvpn-plugin.h.in
> +++ b/include/openvpn-plugin.h.in
> @@ -578,7 +578,7 @@ OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t
> OPENVPN_PLUGIN_FUNC(openvpn_plugin_op
>   * auth_pending_file is
>   * line 1: timeout in seconds
>   * line 2: Pending auth method the client needs to support (e.g. openurl)
> - * line 3: EXTRA (e.g. OPEN_URL:http://www.example.com)
> + * line 3: EXTRA (e.g. WEBAUTH::http://www.example.com)
>   *
>   * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and
>   * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to
> --
> 2.32.0
>

Looks good otherwise.

Selva
<div dir="ltr"><div>Hi,</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Jul 16, 2021 at 8:19 AM Arne Schwabe &lt;<a href="mailto:arne@rfc2549.org">arne@rfc2549.org</a>&gt; wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">The experience with openurl/OPEN_URL has shown that just sending<br>
a URL to a client is not enough and we often need different<br>
behaviour of the client depending on circumstances. Replace<br>
OPEN_URL with a more flexible WEBAUTH pending auth method.<br></blockquote><div><br></div><div>As the two other methods are signalled as OPEN_URL and CR_TEXT, please consider using WEB_AUTH.  The corresponding IV_SSO value can still be named &quot;webauth&quot; as you have below, consistent with crtext and openurl.</div><div><br></div><div>I know it&#39;s just a keyword, but consistency makes it easier to write consuming code without repeatedly referring to the docs.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Signed-off-by: Arne Schwabe &lt;<a href="mailto:arne@rfc2549.org" target="_blank">arne@rfc2549.org</a>&gt;<br>
---<br>
 doc/management-notes.txt    | 41 ++++++++++++++++++++++++++-----------<br>
 include/<a href="http://openvpn-plugin.h.in" rel="noreferrer" target="_blank">openvpn-plugin.h.in</a> |  2 +-<br>
 2 files changed, 30 insertions(+), 13 deletions(-)<br>
<br>
diff --git a/doc/management-notes.txt b/doc/management-notes.txt<br>
index c20344298..4572d967f 100644<br>
--- a/doc/management-notes.txt<br>
+++ b/doc/management-notes.txt<br>
@@ -645,11 +645,11 @@ Before issuing a client-pending-auth to a client instead of a<br>
 client-auth/client-deny, the server should check the IV_SSO<br>
 environment variable for whether the method is supported. Currently<br>
 defined methods are crtext for challenge/response using text<br>
-(e.g., TOTP), openurl and proxy_url for opening a URL in the client to<br>
-continue authentication. A client supporting the first two methods would<br>
-set<br>
+(e.g., TOTP), openurl (deprecated) and webauth for opening a URL in<br></blockquote><div><br></div><div>As we have not released any versions with openurl, why not just replace it webauth? Anyway, below you are replacing proxy_url to use WEB_AUTH instead of PROXY_URL.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+the client to continue authentication. A client supporting the last<br>
+two methods would set </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
-    setenv IV_SSO openurl,crtext<br>
+    setenv IV_SSO webauth,crtext<br></blockquote><div><br></div><div>The last two methods as per the text above are openutl and webauth. Reword as </div><div>&quot;A client supporting webauth and crtext would set</div><div>setenv IV_SSO webauth,crtext&quot;</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
 The variable name IV_SSO is historic as AUTH_PENDING was first used<br>
 to signal single sign on support. To keep compatibility with existing<br>
@@ -668,33 +668,50 @@ notification as<br>
 where {EXTRA} is formatted as received from the server.<br>
 Currently defined formats for {EXTRA} are detailed below.<br>
<br>
-openurl<br>
-========<br>
+webauth and openurl<br>
+===================<br>
 For a web based extra authentication (like for<br>
 SSO/SAML) {EXTRA} should be<br>
<br>
     OPEN_URL:url<br>
<br>
-and client should ask the user to open the URL to continue.<br>
+or<br>
+<br>
+    WEBAUTH:flags:url</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+<br>
+The OPEN_URL method is deprecated as it does not allow to send flags which<br>
+proved to be needed to signal certain behaviour to the client.<br>
+<br>
+The client should ask the user to open the URL to continue.<br>
<br>
 The space in a control message is limited, so this url should be kept<br>
 short to avoid issues. If a longer url is required a URL that redirects<br>
-to the longer URL should be sent instead.<br>
+to the longer URL should be sent instead. The total length is limited to 1024<br>
+bytes which includes the INFO_PRE:WEBAUTH:flags.</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+<br>
+flags is a list of flags which are separated by commas. Currently defined<br>
+flags are:<br>
+<br>
+- proxy     (see next pargraph)<br>
+- hidden    start the webview in hidden mode (see openvpn3 webauth documentation)<br>
+- external  Do not use an internal webview but use an external browser. Some<br>
+            authentication providers refuse to work in an internal webview.<br>
+<br>
<br>
 A complete documentation how URLs should be handled on the client is available<br>
 in the openvpn3 repository:<br>
<br>
 <a href="https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md" rel="noreferrer" target="_blank">https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md</a><br>
<br>
-proxy_url<br>
-========<br>
-This is a variant of openurl that allows opening a url via an<br>
+webauth with proxy<br>
+==================<br>
+This is a variant of webauth that allows opening a url via an<br>
 HTTP proxy. It could be used to avoid issues with OpenVPN connection&#39;s<br>
 persist-tun that may cause the web server to be unreachable.<br>
 The client should announce proxy_url in its IV_SSO and parse the<br>
 PROXY_URL message. The format of {EXTRA} in this case is<br>
<br>
-    PROXY_URL:&lt;proxy&gt;:&lt;proxy_port&gt;:&lt;proxyuser_base64&gt;:&lt;proxy_password_base64&gt;:url<br>
+    WEBAUTH:proxy=&lt;proxy&gt;;&lt;proxy_port&gt;;&lt;proxyuser_base64&gt;;&lt;proxy_password_base64&gt;,flags:url </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
 The proxy should be a literal IPv4 address or IPv6 address enclosed in [] to avoid<br>
 ambiguity in parsing. A literal IP address is preferred as DNS might not be<br>
diff --git a/include/<a href="http://openvpn-plugin.h.in" rel="noreferrer" target="_blank">openvpn-plugin.h.in</a> b/include/<a href="http://openvpn-plugin.h.in" rel="noreferrer" target="_blank">openvpn-plugin.h.in</a><br>
index 79969bf89..944294b22 100644<br>
--- a/include/<a href="http://openvpn-plugin.h.in" rel="noreferrer" target="_blank">openvpn-plugin.h.in</a><br>
+++ b/include/<a href="http://openvpn-plugin.h.in" rel="noreferrer" target="_blank">openvpn-plugin.h.in</a><br>
@@ -578,7 +578,7 @@ OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_op<br>
  * auth_pending_file is<br>
  * line 1: timeout in seconds<br>
  * line 2: Pending auth method the client needs to support (e.g. openurl)<br>
- * line 3: EXTRA (e.g. OPEN_URL:<a href="http://www.example.com" rel="noreferrer" target="_blank">http://www.example.com</a>)<br>
+ * line 3: EXTRA (e.g. WEBAUTH::<a href="http://www.example.com" rel="noreferrer" target="_blank">http://www.example.com</a>)<br>
  *<br>
  * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and<br>
  * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to<br>
-- <br>
2.32.0<br></blockquote><div> </div><div>Looks good otherwise.</div><div><br></div><div>Selva</div></div></div>

Patch

diff --git a/doc/management-notes.txt b/doc/management-notes.txt
index c20344298..4572d967f 100644
--- a/doc/management-notes.txt
+++ b/doc/management-notes.txt
@@ -645,11 +645,11 @@  Before issuing a client-pending-auth to a client instead of a
 client-auth/client-deny, the server should check the IV_SSO
 environment variable for whether the method is supported. Currently
 defined methods are crtext for challenge/response using text
-(e.g., TOTP), openurl and proxy_url for opening a URL in the client to
-continue authentication. A client supporting the first two methods would
-set
+(e.g., TOTP), openurl (deprecated) and webauth for opening a URL in
+the client to continue authentication. A client supporting the last
+two methods would set
 
-    setenv IV_SSO openurl,crtext
+    setenv IV_SSO webauth,crtext
 
 The variable name IV_SSO is historic as AUTH_PENDING was first used
 to signal single sign on support. To keep compatibility with existing
@@ -668,33 +668,50 @@  notification as
 where {EXTRA} is formatted as received from the server.
 Currently defined formats for {EXTRA} are detailed below.
 
-openurl
-========
+webauth and openurl
+===================
 For a web based extra authentication (like for
 SSO/SAML) {EXTRA} should be
 
     OPEN_URL:url
 
-and client should ask the user to open the URL to continue.
+or
+
+    WEBAUTH:flags:url
+
+The OPEN_URL method is deprecated as it does not allow to send flags which
+proved to be needed to signal certain behaviour to the client.
+
+The client should ask the user to open the URL to continue.
 
 The space in a control message is limited, so this url should be kept
 short to avoid issues. If a longer url is required a URL that redirects
-to the longer URL should be sent instead.
+to the longer URL should be sent instead. The total length is limited to 1024
+bytes which includes the INFO_PRE:WEBAUTH:flags.
+
+flags is a list of flags which are separated by commas. Currently defined
+flags are:
+
+- proxy     (see next pargraph)
+- hidden    start the webview in hidden mode (see openvpn3 webauth documentation)
+- external  Do not use an internal webview but use an external browser. Some
+            authentication providers refuse to work in an internal webview.
+
 
 A complete documentation how URLs should be handled on the client is available
 in the openvpn3 repository:
 
 https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md
 
-proxy_url
-========
-This is a variant of openurl that allows opening a url via an
+webauth with proxy
+==================
+This is a variant of webauth that allows opening a url via an
 HTTP proxy. It could be used to avoid issues with OpenVPN connection's
 persist-tun that may cause the web server to be unreachable.
 The client should announce proxy_url in its IV_SSO and parse the
 PROXY_URL message. The format of {EXTRA} in this case is
 
-    PROXY_URL:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>:url
+    WEBAUTH:proxy=<proxy>;<proxy_port>;<proxyuser_base64>;<proxy_password_base64>,flags:url
 
 The proxy should be a literal IPv4 address or IPv6 address enclosed in [] to avoid
 ambiguity in parsing. A literal IP address is preferred as DNS might not be
diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in
index 79969bf89..944294b22 100644
--- a/include/openvpn-plugin.h.in
+++ b/include/openvpn-plugin.h.in
@@ -578,7 +578,7 @@  OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_op
  * auth_pending_file is
  * line 1: timeout in seconds
  * line 2: Pending auth method the client needs to support (e.g. openurl)
- * line 3: EXTRA (e.g. OPEN_URL:http://www.example.com)
+ * line 3: EXTRA (e.g. WEBAUTH::http://www.example.com)
  *
  * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and
  * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to