add authentik oidc docs (#113)

docs/authentication/oidc/authentik.md

@@ -1,2 +1,190 @@
 # Authentik
 
+This guide shows how to setup {{ extra.project }} + [Authentik](https://goauthentik.io/) as OIDC identity provider.
+It was tested with Authentik 2023.10.7
+
+To follow this guide you need one {{ extra.project }} and one Authentik instance. For
+this guide we have:
+
+    http://authk.trusel.net:9000/ (Authentik instance)
+    http://demo.trusel.net:12000/ ({{extra.project}} instance)
+
+Of course for your specific deployment you'll want to serve both apps over
+https, with valid certificates and without featuring ports in URLs, but for
+our guide we will skip those parts.
+
+In first part of the guide we will add administrative user
+(superuser). Superuser has all permissions, in other words, superuser is the
+most privileged user in {{ extra.project }}. In second part of the guide we will add
+one non-superuser.
+
+
+## Administrative User (Superuser)
+
+### Step 1 - Create Application
+
+Create new application.
+Applications -> Create:
+
+    Name: Papermerge
+    Slug: papermerge
+    Policy engine mode: any
+
+Leave `Provider` field empty for this moment, we will fill it in later.
+
+### Step 2 - Create Provider
+
+Create OIDC provider.
+Applications -> Providers -> Create:
+
+    Choose OAuth2/OpenID Provider
+    Name: papermerge
+    Authentication flow: default-authentication-flow
+    Authorization flow: default-provider-authorization-explicit-consent
+    Client type: confidential
+    Subject mode (in Advanced protocol settings): Based on User's UUID
+    Scopes (in Advanced protocol settings): make sure email, openid, profile are selected
+
+Last point is very important as it will setup `sub` claim to contain user's UUID.
+
+![Authentik new provider](../../img/auth/oidc/authentik-new-provider.gif)
+
+
+### Step 3 - Associated Provider with Application
+
+Applications -> Papermerge -> Edit.
+Change `Provider` field to `papermerge`.
+Update.
+
+
+### Step 4 - Create User
+
+Let's create a user **in Authentik**.
+
+Directory -> Users -> Create.
+Create user with following details:
+
+    - username: bender
+    - email: [email protected]
+    - password: benderpass
+
+User "bender" will be administrative user in {{ extra.project }}.
+
+!!! Note
+
+    User is created in Authentik. User password is set in Authentik as well.
+
+
+
+### Step 5 - Start Papermerge
+
+Get all OIDC related settings from Authentik's Providers -> papermerge.
+There you will find client ID, client secret etc.
+
+Start {{ extra.project }} with OIDC enabled, with following docker compose:
+
+```yaml
+version: "3.9"
+
+x-backend: &common
+  image: papermerge/papermerge:{{extra.docker_image_version}}
+  environment:
+    PAPERMERGE__SECURITY__SECRET_KEY: super-secret-12345
+    PAPERMERGE__AUTH__USERNAME: bender
+    PAPERMERGE__AUTH__EMAIL: [email protected]
+    PAPERMERGE__AUTH__PASSWORD: 1234-not-relevant-but-still-needs-to-be-here
+    PAPERMERGE__AUTH__OIDC_CLIENT_SECRET: cBqWCID8xt0fjpTFJwup32K8gaF4zufuUYVmUPoAUY90FxVpnPqL1Krl74viDaKzpLyhzBNWgstKztITpstBdvjEfzlA6jr3g2HL6tqwGW6W5Ax93xGzkTD2xw0WsVTu
+    PAPERMERGE__AUTH__OIDC_CLIENT_ID: o2h90p8RuJe2GQT01LkNGlM3QuN8yxjQUdOE5Ylw
+    PAPERMERGE__AUTH__OIDC_AUTHORIZE_URL: http://authk.trusel.net:9000/application/o/authorize/
+    PAPERMERGE__AUTH__OIDC_ACCESS_TOKEN_URL: http://authk.trusel.net:9000/application/o/token/
+    PAPERMERGE__AUTH__OIDC_INTROSPECT_URL: http://authk.trusel.net:9000/application/o/introspect/
+    PAPERMERGE__AUTH__OIDC_USER_INFO_URL: http://authk.trusel.net:9000/application/o/userinfo/
+    PAPERMERGE__AUTH__OIDC_LOGOUT_URL: http://authk.trusel.net:9000/application/o/papermerge/end-session/
+    PAPERMERGE__AUTH__OIDC_SCOPE: "openid email profile"
+    PAPERMERGE__AUTH__OIDC_REDIRECT_URL: http://demo.trusel.net:12000/oidc/callback
+services:
+  web:
+    <<: *common
+    ports:
+     - "12000:80"
+  worker:
+    <<: *common
+    command: worker
+```
+
+Note that `PAPERMERGE__AUTH__OIDC_CLIENT_SECRET`, `PAPERMERGE__AUTH__OIDC_CLIENT_ID` should match
+their counterpart in "papermerge provider" created in Authentik.
+
+`PAPERMERGE__AUTH__USERNAME` and `PAPERMERGE__AUTH__EMAIL` should match the user we created in step 4. As it was
+mentioned, we will use "bender" as administrative user in {{extra.project}}.
+Note that you need to specify `PAPERMERGE__AUTH__PASSWORD`, but whatever you put there is completely irrelevant
+because administrative user will login with password managed in Authentik (in our example it is "benderpass").
+
+`PAPERMERGE__AUTH__OIDC_REDIRECT_URL` should match "Valid redirect URIs" from Step 3 and it should be of
+format: `[http|https]://<papermerge-instance-domain>/oidc/callback`.
+
+`PAPERMERGE__AUTH__OIDC_SCOPE` must include "profile", otherwise JWT token won't contain `preferred_username` and `groups` claims
+
+It may happen that not all OIDC endpoints are shown in Authentik UI.
+To get all OIDC endpoints, use "OpenID Configuration URL" directly in your browser:
+
+![All OIDC endpoints](../../img/auth/oidc/authentik-all-oidc-endpoints.gif)
+
+
+### Step 6 - Login as Superuser
+
+![Login as superuser](../../img/auth/oidc/authentik-login-as-bender.gif)
+
+!!! Warning
+
+    There is a known issue that after successful login - "sign in" view is still shown.
+    As workaround you need to hit browser's **refresh** button.
+
+
+## Groups / Permissions
+
+In this part we will add less privileged users. Users added in this part have
+limited permissions - they won't be able to add/view/delete other groups and
+users. User permissions are set via groups. Each group has a specific set of
+permissions; if user belongs to a group - he or she has all permissions
+assigned to respective group.
+
+For this part to work, make sure you've completed the "superuser" part of this guide.
+
+**All non-superusers (i.e. normal users) must belong to one or more groups.**
+
+In this part we will create one user "leela". "leela" will have all permissions
+but view/create/delete for users/groups.
+
+
+### Step 1 - Create Group in Papermerge
+
+First we need to create group, named "family", with desired set of
+permissions. You do this in {{ extra.project }} with user "bender".
+
+![Add family group](../../img/auth/oidc/add-family-group.gif)
+
+
+!!! Note
+
+    Group names in Authentik and in {{ extra.project }} should match.
+
+### Step 2 - Add User
+
+Create user "leela" in Authentik.
+Create "family" group in Authentik.
+Add user "leela" to group "family" (in Authentik).
+Of course you will set leela's password in Authentik as well.
+
+The outcome should look like:
+
+![User Leela in Family Group](../../img/auth/oidc/authentik-user-leela-in-family-group.gif)
+
+### Step 3 - Login as "leela"
+
+Login with as leela in {{ extra.project }}. Notice that "users" and "groups" tabs on
+the left side bar are not visible, as leela does not have permissions to
+to manage users and groups.
+
+
+![Login as Leela](../../img/auth/oidc/authentik-login-as-leela.gif)

docs/authentication/oidc/keycloak.md

@@ -121,12 +121,13 @@ assigned to respective group.
 
 For this part to work, make sure you've completed the "superuser" part from above.
 
-Any other user you will add need to belong to one or more groups.
+**All non-superuser (i.e. normal users) must belong to one or more groups.**
+
 In this part we will create one user "leela". "leela" will have all permissions
 but view/create/delete for users/groups.
 
 
-### Step 1 - Create Group
+### Step 1 - Create Group in Papermerge
 
 First we need to create group, named "family", with desired set of
 permissions. You do this in {{ extra.project }} with user "bender".
@@ -137,8 +138,6 @@ permissions. You do this in {{ extra.project }} with user "bender".
 !!! Note
 
     Group names in Keycloak and in {{ extra.project }} should match.
-    Group <-> Permissions association is created in {{ extra.project }}.
-    User <-> Groups association is created in Keycloak.
 
 
 ### Step 2 - Add User

docs/authentication/oidc/overview.md

@@ -1,5 +1,8 @@
 # Overview
 
+
+## Protocol
+
 OpenID Connect (OIDC) is an interoperable authentication protocol based on the OAuth
 2.0 framework of specifications.
 
@@ -106,5 +109,42 @@ In other words, there is nginx's "auth_request" for every incoming HTTP request
 depending on it's response's status code the request is allowed to pass or not.
 
 
-That's all with OIDC theory. Now it is time to jump into
-specific examples. First example is [Papermerge + Keycloak](keycloak.md) as identity provider.
+## Users
+
+When using OIDC provider, users are managed on OIDC provider side. You will
+create, update, delete users on OIDC provider side. This means also
+that you set users' passwords on provider side (Keycloak, Authentik).
+
+The only exception from this rule is very first superuser account of the {{ extra.project }}.
+Initial superuser account of {{ extra.project }} is created on both sides:
+in {{ extra.project }} via `PAPERMERGE__AUTH__USERNAME`, `PAPERMERGE__AUTH__EMAIL`
+`PAPERMERGE__AUTH__PASSWORD` environment variables and via OIDC provider.
+
+Note however that even though you must supply `PAPERMERGE__AUTH__PASSWORD`, its value is
+not used, as you will login using password configured in OIDC provider.
+
+## Groups
+
+Every user which will login into {{ extra.project }} via OIDC must belong to one
+or more groups. The only exception from this rule is initial superuser account.
+
+Groups must be created on both sides - on {{extra.project}} side and on OIDC
+provider side. Groups are matches by their names. This means, in order to
+match, on both sides group name must be same. Name matching is case
+sensitive, this means for examples that "Family" and "family" are distinct
+names.
+
+
+## Permissions
+
+When using OIDC provider, permissions are managed on {{ extra.project }} side only.
+Group can be regarded as a set of permissions.
+Group <-> Permissions association is accomplished on {{ extra.project }} side.
+
+On the OIDC provider side, users are assigned to groups. By matching group on
+the {{extra.project}} side, user gains all permissions of the groups they
+were assigned.
+
+Users, groups, permissions entities relations can be illustrated as in following picture:
+
+![Users Groups Permissions](../../img/auth/oidc/users-groups-permissions.svg)