cgiacofei/TandoorRecipes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(authentication): Improve auth docs to match current allauth best practices and syntax

Browse Source
This commit is contained in:
Jinna Kiisuo 2024-02-26 13:55:53 +02:00
parent c15bd663cb
commit 4a7eb91e67
1 changed files with 16 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/features/authentication.md
View File

@ -3,7 +3,7 @@ methods of central account management and authentication.
## Allauth ## Allauth
[Django Allauth](https://django-allauth.readthedocs.io/en/latest/index.html) is an awesome project that [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. authentication providers.
They basically explain everything in their documentation, but the following is a short overview on how to get started. 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 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. 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 ```ini
SOCIAL_PROVIDERS=allauth.socialaccount.providers.github,allauth.socialaccount.providers.nextcloud SOCIAL_PROVIDERS=allauth.socialaccount.providers.openid_connect,allauth.socialaccount.providers.nextcloud
``` ```
!!! warning "Formatting" !!! warning "Formatting"
The exact formatting is important so make sure to follow the steps explained here! 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. 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 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 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 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. 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 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). (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. 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 ```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 ?" !!! success "Improvements ?"
There are most likely ways to achieve the same goal but with a cleaner or simpler system. 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. If you know such a way feel free to let me know.
After that, use your superuser account to configure your authentication backend. ### Configuration, via Django Admin
Open the admin page and do the following
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). 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. 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 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. 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" !!! info "WIP"
I do not have a ton of experience with using various single signon providers and also cannot test all of them. 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. You are now able to sign in using Keycloak after a restart of the service.
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.
### Linking accounts ### Linking accounts
To link an account to an already existing normal user go to the settings page of the user and link it. To link an account to an already existing normal user go to the settings page of the user and link it.