From 4a7eb91e674f5fcb895a67c3fdc064445a9acd38 Mon Sep 17 00:00:00 2001 From: Jinna Kiisuo Date: Mon, 26 Feb 2024 13:55:53 +0200 Subject: [PATCH] docs(authentication): Improve auth docs to match current allauth best practices and syntax --- docs/features/authentication.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/features/authentication.md b/docs/features/authentication.md index 84df9fca78..34a7970fb3 100644 --- a/docs/features/authentication.md +++ b/docs/features/authentication.md @@ -3,7 +3,7 @@ methods of central account management and authentication. ## Allauth [Django Allauth](https://django-allauth.readthedocs.io/en/latest/index.html) is an awesome project that -allows you to use a [huge number](https://django-allauth.readthedocs.io/en/latest/providers.html) of different +allows you to use a [huge number](https://docs.allauth.org/en/latest/socialaccount/providers/index.html) of different authentication providers. They basically explain everything in their documentation, but the following is a short overview on how to get started. @@ -17,42 +17,50 @@ They basically explain everything in their documentation, but the following is a Choose a provider from the [list](https://docs.allauth.org/en/latest/socialaccount/providers/index.html) and install it using the environment variable `SOCIAL_PROVIDERS` as shown in the example below. -When at least one social provider is set up, the social login sign in buttons should appear on the login page. +When at least one social provider is set up, the social login sign in buttons should appear on the login page. The example below enables Nextcloud and the generic OpenID Connect providers. ```ini -SOCIAL_PROVIDERS=allauth.socialaccount.providers.github,allauth.socialaccount.providers.nextcloud +SOCIAL_PROVIDERS=allauth.socialaccount.providers.openid_connect,allauth.socialaccount.providers.nextcloud ``` !!! warning "Formatting" The exact formatting is important so make sure to follow the steps explained here! +### Configuration, via environment + Depending on your authentication provider you **might need** to configure it. This needs to be done through the settings system. To make the system flexible (allow multiple providers) and to not require another file to be mounted into the container the configuration ins done through a single environment variable. The downside of this approach is that the configuration needs to be put into a single line as environment files loaded by docker compose don't support multiple lines for a single variable. +The line data needs to either be in json or as Python dictionary syntax. + Take the example configuration from the allauth docs, fill in your settings and then inline the whole object (you can use a service like [www.freeformatter.com](https://www.freeformatter.com/json-formatter.html) for formatting). Assign it to the additional `SOCIALACCOUNT_PROVIDERS` variable. + +The example below is for a generic OIDC provider with PKCE enabled. Most values need to be customized for your specifics! ```ini -SOCIALACCOUNT_PROVIDERS={"nextcloud":{"SERVER":"https://nextcloud.example.org"}} +SOCIALACCOUNT_PROVIDERS = "{ 'openid_connect': { 'OAUTH_PKCE_ENABLED': True, 'APPS': [ { 'provider_id': 'oidc', 'name': 'My-IDM', 'client_id': 'my_client_id', 'secret': 'my_client_secret', 'settings': { 'server_url': 'https://idm.example.com/oidc/recipes' } } ] } }" ``` !!! success "Improvements ?" There are most likely ways to achieve the same goal but with a cleaner or simpler system. If you know such a way feel free to let me know. -After that, use your superuser account to configure your authentication backend. -Open the admin page and do the following +### Configuration, via Django Admin + +Instead of defining `SOCIALACCOUNT_PROVIDERS` in your environment, most configuration options can be done via the Admin interface. PKCE for `openid_connect` cannot currently be enabled this way. +Use your superuser account to configure your authentication backend by opening the admin page and do the following 1. Select `Sites` and edit the default site with the URL of your installation (or create a new). 2. Create a new `Social Application` with the required information as stated in the provider documentation of allauth. 3. Make sure to add your site to the list of available sites Now the provider is configured and you should be able to sign up and sign in using the provider. -Use the superuser account to grant permissions to the newly created users. +Use the superuser account to grant permissions to the newly created users, or enable default access via `SOCIAL_DEFAULT_ACCESS` & `SOCIAL_DEFAULT_GROUP`. !!! info "WIP" I do not have a ton of experience with using various single signon providers and also cannot test all of them. @@ -70,13 +78,7 @@ SOCIALACCOUNT_PROVIDERS='{"openid_connect":{"APPS":[{"provider_id":"keycloak","n ' ``` -1. Restart the service, login as superuser and open the `Admin` page. -2. Make sure that the correct `Domain Name` is defined at `Sites`. -3. Select `Social Application` and chose `Keycloak` from the provider list. -4. Provide an arbitrary name for your authentication provider, and enter the `Client-ID` and `Secret Key` values obtained from Keycloak earlier. -5. Make sure to add your `Site` to the list of available sites and save the new `Social Application`. - -You are now able to sign in using Keycloak. +You are now able to sign in using Keycloak after a restart of the service. ### Linking accounts To link an account to an already existing normal user go to the settings page of the user and link it.