From b2fe4ad3ed4a2e5954471530435d91703c6fc585 Mon Sep 17 00:00:00 2001
From: Marius Kittler <mkittler@suse.de>
Date: Mon, 12 Apr 2021 12:08:42 +0200
Subject: [PATCH] Update user authentication documentation to cover recent
 improvements

---
 docs/Installing.asciidoc | 44 +++++++++++++++++++++++++---------------
 etc/openqa/openqa.ini    | 18 ++++++++--------
 2 files changed, 38 insertions(+), 24 deletions(-)

diff --git a/docs/Installing.asciidoc b/docs/Installing.asciidoc
index f62bfd01c272..e1f08824cb02 100644
--- a/docs/Installing.asciidoc
+++ b/docs/Installing.asciidoc
@@ -303,9 +303,10 @@ according to
 [[authentication]]
 === User authentication
 
-OpenQA supports three different authentication methods - OpenID (default),
-OAuth2 (currently limited to GitHub) and Fake (for development).
-See `auth` section in `/etc/openqa/openqa.ini`.
+OpenQA supports three different authentication methods: OpenID (default),
+OAuth2 and Fake (for development).
+
+Use the `auth` section in `/etc/openqa/openqa.ini` to configure the method:
 
 [source,ini]
 --------------------------------------------------------------------------------
@@ -314,8 +315,15 @@ See `auth` section in `/etc/openqa/openqa.ini`.
 method = OpenID
 --------------------------------------------------------------------------------
 
-Independently of method used, the first user that logs in (if there is no admin yet)
-will automatically get administrator rights!
+Independently of method used, the first user that logs in (if there is no
+admin yet) will automatically get administrator rights!
+
+Note that only one authentication method and only one OpenID/OAuth2 provider
+can be configured at a time. When changing the method/provider no
+users/permissions are lost. However, a new and distinct user (with default
+permissions) will be created when logging in via a different method/provider
+because there is no automatic mapping of identities across different
+methods/providers.
 
 ==== OpenID
 
@@ -339,7 +347,15 @@ This method supports OpenID version up to 2.0.
 
 ==== OAuth2
 
-Login via OAuth 2.0 is currently limited to GitHub.
+An additional Mojolicious plugin is required to use this feature:
+
+[source,sh]
+-------------------------------------------------------------------------------
+# openSUSE
+zypper in 'perl(Mojolicious::Plugin::OAuth2)'
+-------------------------------------------------------------------------------
+
+Example for configuring OAuth2 with GitHub:
 
 [source,ini]
 --------------------------------------------------------------------------------
@@ -353,17 +369,13 @@ key = mykey
 secret = mysecret
 --------------------------------------------------------------------------------
 
-In order to use GitHub for authorization, the instance needs to be
-https://github.com/settings/applications/new[registered on GitHub]. Afterwards
-the key and secret will be visible to the application owner(s).
-
-Note: An additional Mojolicious plugin is required to use this feature:
+In order to use GitHub for authorization, an "OAuth App" needs to be
+https://github.com/settings/applications/new[registered on GitHub]. Use `…/login`
+as callback URL. Afterwards the key and secret will be visible to the application
+owner(s).
 
-[source,sh]
--------------------------------------------------------------------------------
-# openSUSE
-zypper in 'perl(Mojolicious::Plugin::OAuth2)'
--------------------------------------------------------------------------------
+As shown in the comments of the default configuration file, it is also possible
+to use different providers.
 
 ==== Fake
 
diff --git a/etc/openqa/openqa.ini b/etc/openqa/openqa.ini
index f0f96c81217f..c3f9d9eea394 100644
--- a/etc/openqa/openqa.ini
+++ b/etc/openqa/openqa.ini
@@ -87,23 +87,25 @@
 [auth]
 # method = Fake|OpenID|OAuth2
 
-# for GitHub/salsa.debian.org one can use:
+# for GitHub/salsa.debian.org and providers listed on https://metacpan.org/pod/Mojolicious::Plugin::OAuth2#Configuration
+# one can use:
 #[oauth2]
 #provider = github/debian_salsa
 #key = ...
 #secret = ...
 
-# alternatively, one can specify everything in this file with no magic provider name
+# alternatively, one can specify parameters manually without relying on magic a provider name:
 #[oauth2]
 #provider = custom
+#unique_name = debian_salsa
 #key = ...
 #secret = ...
-#authorize_url => https://salsa.debian.org/oauth/authorize?response_type=code
-#token_url     => https://salsa.debian.org/oauth/token
-#user_url      => https://salsa.debian.org/api/v4/user
-#token_scope   => read_user
-#token_label   => Bearer
-#nickname_from => username
+#authorize_url = https://salsa.debian.org/oauth/authorize?response_type=code
+#token_url = https://salsa.debian.org/oauth/token
+#user_url  = https://salsa.debian.org/api/v4/user
+#token_scope = read_user
+#token_label = Bearer
+#nickname_from = username
 
 [logging]
 #logging is to stderr (so systemd journal) by default