TheAnachronism/docspell
1
0
Fork 0
mirror of https://github.com/TheAnachronism/docspell.git synced 2025-06-23 10:58:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve logging and rename oauth->openid

Browse Source
This commit is contained in:
eikek
2021-09-05 23:43:25 +02:00
parent 984dda9da0
commit 8158e36d40
6 changed files with 82 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
modules/restserver/src/main/resources/reference.conf
View File

@ -61,53 +61,67 @@ docspell.server {
}
}
# Configures OpenID Connect or OAuth2 authentication. Only the
# "Authorization Code Flow" is supported.
# Configures OpenID Connect (OIDC) or OAuth2 authentication. Only
# the "Authorization Code Flow" is supported.
#
# Multiple authentication providers are supported. Each is
# Multiple authentication providers can be defined. 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.
# details necessary to authenticate agains an external OIDC or OAuth
# provider. This requires at least two URLs for OIDC and three for
# OAuth2. The `user-url` is only required for OIDC, if the account
# data is to be retrieved from the user-info endpoint and not from
# the JWT token. The access token is then used to authenticate at
# the provider to obtain user info. Thus, it doesn't need to be
# validated here 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. This would save
# another request. If the `sign-key` is left empty, the `user-url`
# is used and must be specified. If the `sign-key` is _not_ empty,
# the response from the authentication provider is validated using
# this key.
#
# 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.
# account. For this a username and collective name is required. The
# username is defined by the `user-key` setting. 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.
# There are the following ways to specify how to retrieve the full
# account id depending on the value of `collective-key`:
#
# 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 `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 `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.
# - 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:ds-account", it
# works the same as `lookup:` only that the value is interpreted
# as the full account name of form `collective/login`. The
# `user-key` value is ignored in this case.
#
# If these values cannot be obtained from the response, docspell
# fails the authentication by denying access. It is then assumed
# that the successfully authenticated user has not enough
# permissions to access docspell.
#
# Below are examples for OpenID Connect (keycloak) and OAuth2
# (github).
openid =
[ { enabled = false,
# The name to render on the login link/button.
display = "Keycloak"
# This illustrates to use a custom keycloak setup as the
# authentication provider. For details, please refer to its
# documentation.
# authentication provider. For details, please refer to the
# keycloak documentation. The settings here assume a certain
# configuration at keycloak.
#
# Keycloak can be configured to return the collective name for
# each user in the access token. It may also be configured to
@ -120,7 +134,7 @@ docspell.server {
provider-id = "keycloak",
client-id = "docspell",
client-secret = "example-secret-439e-bf06-911e4cdd56a6",
scope = "docspell",
scope = "docspell", # scope is required for OIDC
authorize-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/auth",
token-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/token",
#User URL is not used when signature key is set.
@ -136,22 +150,27 @@ docspell.server {
},
{ enabled = false,
# The name to render on the login link/button.
display = "Github"
# 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.
# Github doesn't have full OpenIdConnect, but supports the
# OAuth2 code flow (which is very similar). It mainly means,
# that there is no standardized token to validate and get
# information from. So the user-url must be used in this case.
provider = {
provider-id = "github",
client-id = "<your github client id>",
client-secret = "<your github client secret>",
scope = "",
scope = "", # scope is not needed for github
authorize-url = "https://github.com/login/oauth/authorize",
token-url = "https://github.com/login/oauth/access_token",
user-url = "https://api.github.com/user",
sign-key = ""
sign-key = "" # this must be set empty
sig-algo = "RS256" #unused but must be set to something
},