Authenticate with external accounts using OIDC

After successful authentication at the provider, an account is
automatically created at docspell and the user is logged in.

modules/restserver/src/main/resources/reference.conf

@@ -64,17 +64,62 @@ docspell.server {
   # Configures OpenID Connect or OAuth2 authentication. Only the
   # "Authorization Code Flow" is supported.
   #
-  # When using OpenID Connect, a scope is mandatory.
-  # TODO
+  # Multiple authentication providers are supported. Each is
+  # configured in the array below. The `provider` block gives all
+  # details necessary to authenticate agains an external OpenIdConnect
+  # or OAuth provider. This requires at least two URLs for
+  # OpenIdConnect and three for OAuth2. The `user-url` is only
+  # required for OpenIdConnect, if the account data is to be retrieved
+  # from the user-info endpoint and not from the access token. This
+  # will use the access token to authenticate at the provider to
+  # obtain user info. Thus, it doesn't need to be validated and
+  # therefore no `sign-key` setting is needed. However, if you want to
+  # extract the account information from the access token, it must be
+  # validated here and therefore the correct signature key and
+  # algorithm must be provided.
+  #
+  # After successful authentication, docspell needs to create the
+  # account. For this a username and collective name is required.
+  # There are the following ways to specify how to retrieve this info
+  # depending on the value of `collective-key`. The `user-key` is used
+  # to search the JSON structure, that is obtained from the JWT token
+  # or the user-info endpoint, for the login name to use. It traverses
+  # the JSON structure recursively, until it finds an object with that
+  # key. The first value is used.
+  #
+  # If it starts with `fixed:`, like "fixed:collective", the name
+  # after the `fixed:` prefix is used as collective as is. So all
+  # users are in the same collective.
+  #
+  # If it starts with `lookup:`, like "lookup:collective_name", the
+  # value after the prefix is used to search the JSON response for an
+  # object with this key, just like it works with the `user-key`.
+  #
+  # If it starts with `account:`, like "account:doscpell-collective",
+  # it works the same as `lookup:` only that it is interpreted as the
+  # account name of form `collective/name`. The `user-key` value is
+  # ignored in this case.
   #
   # Below are examples for OpenID Connect (keycloak) and OAuth2
   # (github).
   openid =
     [ { enabled = false,
+
+        # This illustrates to use a custom keycloak setup as the
+        # authentication provider. For details, please refer to its
+        # documentation.
+        #
+        # Keycloak can be configured to return the collective name for
+        # each user in the access token. It may also be configured to
+        # return it in the user info response. If it is already in the
+        # access token, an additional request can be omitted. Set the
+        # `sign-key` to an empty string then. Otherwise provide the
+        # algo and key from your realm settings. In this example, the
+        # realm is called "home".
         provider = {
           provider-id = "keycloak",
           client-id = "docspell",
-          client-secret = "21cd4550-6328-439e-bf06-911e4cdd56a6",
+          client-secret = "example-secret-439e-bf06-911e4cdd56a6",
           scope = "docspell",
           authorize-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/auth",
           token-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/token",
@@ -82,9 +127,22 @@ docspell.server {
           #user-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/userinfo",
           sign-key = "b64:MII…ZYL09vAwLn8EAcSkCAwEAAQ==",
           sig-algo = "RS512"
-        }
+        },
+        # The collective of the user is given in the access token as
+        # property `docspell_collective`.
+        collective-key = "lookup:docspell_collective",
+        # The username to use for the docspell account
+        user-key = "preferred_username"
       },
       { enabled = false,
+
+        # Provider settings for using github as an authentication
+        # provider. Note that this is only an example to illustrate
+        # how it works. Usually you wouldn't want to let every user on
+        # github in ;-).
+        #
+        # Github doesn't have full OpenIdConnect yet, but supports the
+        # OAuth2 code flow.
         provider = {
           provider-id = "github",
           client-id = "<your github client id>",
@@ -95,7 +153,17 @@ docspell.server {
           user-url = "https://api.github.com/user",
           sign-key = ""
           sig-algo = "RS256" #unused but must be set to something
-        }
+        },
+
+        # If the authentication provider doesn't provide the
+        # collective name, simply use a fixed one. This means all
+        # users from this provider are in the same collective!
+        collective-key = "fixed:demo",
+
+        # Github provides the login name via the `login` property as
+        # response from the user-url. This value is used to construct
+        # the account in docspell.
+        user-key = "login"
       }
     ]