| Message ID | 20210716121848.67888-1-arne@rfc2549.org |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | [Openvpn-devel] Introduce webauth auth pending method and deprecate openurl | expand |
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
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 <<a href="mailto:arne@rfc2549.org">arne@rfc2549.org</a>> 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 "webauth" as you have below, consistent with crtext and openurl.</div><div><br></div><div>I know it'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 <<a href="mailto:arne@rfc2549.org" target="_blank">arne@rfc2549.org</a>><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>"A client supporting webauth and crtext would set</div><div>setenv IV_SSO webauth,crtext"</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'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:<proxy>:<proxy_port>:<proxyuser_base64>:<proxy_password_base64>:url<br> + WEBAUTH:proxy=<proxy>;<proxy_port>;<proxyuser_base64>;<proxy_password_base64>,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>
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
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(-)