12 KiB
Authentik
authentik is an open-source Identity Provider focused on flexibility and versatility. MASH can install authentik with the mother-of-all-self-hosting/ansible-role-authentik ansible role.
Warning: SSO is pretty complex and while this role will install authentik for you we only tested OIDC and OAUTH integration. There is a high probability that using outposts/LDAP would need further configuration efforts. Make sure you test before using this in production and feel free to provide feedback!
Dependencies
This service requires the following other services:
Configuration
To enable this service, add the following configuration to your vars.yml file and re-run the installation process:
########################################################################
# #
# authentik #
# #
########################################################################
authentik_enabled: true
authentik_hostname: authentik.example.com
authentik_secret_key: 'verysecret'
########################################################################
# #
# /authentik #
# #
########################################################################
Redis
As described on the Redis documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See Creating a Redis instance dedicated to authentik.
If you're only running authentik on this server and don't need to use Redis for anything else, you can use a single Redis instance.
Using the shared Redis instance for authentik
To install a single (non-dedicated) Redis instance (mash-redis) and hook authentik to it, add the following additional configuration:
########################################################################
# #
# redis #
# #
########################################################################
redis_enabled: true
########################################################################
# #
# /redis #
# #
########################################################################
########################################################################
# #
# authentik #
# #
########################################################################
# Base configuration as shown above
# Point authentik to the shared Redis instance
authentik_config_redis_hostname: "{{ redis_identifier }}"
# Make sure the authentik service (mash-authentik.service) starts after the shared Redis service (mash-redis.service)
authentik_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service"
# Make sure the authentik container is connected to the container network of the shared Redis service (mash-redis)
authentik_container_additional_networks_custom:
- "{{ redis_identifier }}"
########################################################################
# #
# /authentik #
# #
########################################################################
This will create a mash-redis Redis instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for Creating a Redis instance dedicated to authentik.
Creating a Redis instance dedicated to authentik
The following instructions are based on the Running multiple instances of the same service on the same host documentation.
Adjust your inventory/hosts file as described in Re-do your inventory to add supplementary hosts, adding a new supplementary host (e.g. if authentik.example.com is your main one, create authentik.example.com-deps).
Then, create a new vars.yml file for the
inventory/host_vars/authentik.example.com-deps/vars.yml:
---
########################################################################
# #
# Playbook #
# #
########################################################################
# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
# Various other secrets will be derived from this secret automatically.
mash_playbook_generic_secret_key: ''
# Override service names and directory path prefixes
mash_playbook_service_identifier_prefix: 'mash-authentik-'
mash_playbook_service_base_directory_name_prefix: 'authentik-'
########################################################################
# #
# /Playbook #
# #
########################################################################
########################################################################
# #
# redis #
# #
########################################################################
redis_enabled: true
########################################################################
# #
# /redis #
# #
########################################################################
This will create a mash-authentik-redis instance on this host with its data in /mash/authentik-redis.
Then, adjust your main inventory host's variables file (inventory/host_vars/authentik.example.com/vars.yml) like this:
########################################################################
# #
# authentik #
# #
########################################################################
# Base configuration as shown above
# Point authentik to its dedicated Redis instance
authentik_environment_variable_redis_host: mash-authentik-redis
authentik_environment_variable_redis_cache_host: mash-authentik-redis
# Make sure the authentik service (mash-authentik.service) starts after its dedicated Redis service (mash-authentik-redis.service)
authentik_systemd_required_services_list_custom:
- "mash-authentik-redis.service"
# Make sure the authentik container is connected to the container network of its dedicated Redis service (mash-authentik-redis)
authentik_container_additional_networks_custom:
- "mash-authentik-redis"
########################################################################
# #
# /authentik #
# #
########################################################################
Installation
If you've decided to install a dedicated Redis instance for authentik, make sure to first do installation for the supplementary inventory host (e.g. authentik.example.com-deps), before running installation for the main one (e.g. authentik.example.com).
Usage
After installation, you can go to the authentik URL, as defined in authentik_hostname. Set the admin password there and start adding applications and users! Refer to the official documentation to learn how to integrate services. Below are some tested examples
Grafana
To enable SSO for Grafana you should
- Create a new OAUTH provider in authentik called
grafana - Create an application also named
grafanain authentik using this provider - Add the following configuration to your
vars.ymlfile and re-run the installation process (make sure to adjustauthentik.example.com)
grafana_environment_variables_additional_variables: |
GF_AUTH_GENERIC_OAUTH_ENABLED=true
GF_AUTH_GENERIC_OAUTH_NAME=authentik
GF_AUTH_GENERIC_OAUTH_CLIENT_ID=COPIED-CLIENTID
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=COPIED-CLIENTSECRET
GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email
GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://authentik.example.com/application/o/authorize/
GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://authentik.example.com/application/o/token/
GF_AUTH_GENERIC_OAUTH_API_URL=https://authentik.example.com/application/o/userinfo/
GF_AUTH_SIGNOUT_REDIRECT_URL=https://authentik.example.com/application/o/grafana/end-session/
# Optionally enable auto-login (bypasses Grafana login screen)
#GF_AUTH_OAUTH_AUTO_LOGIN="true"
GF_AUTH_GENERIC_OAUTH_ALLOW_ASSIGN_GRAFANA_ADMIN=true
# Optionally map user groups to Grafana roles
GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH="contains(groups[*], 'Grafana Admins') && 'Admin' || contains(groups[*], 'Grafana Editors') && 'Editor' || 'Viewer'"
Nextcloud
The official documentation of authentik to connect nextcloud via SAML seems broken
MASH can connect Nextcloud with authentik via OIDC. The setup is quite straightforward, refer to this blogpost by Jack for a full explanation.
In short you shoudl
- Create a new provider in authentik and trimm the client secret to <64 characters
- Create an application in authentik using this provider
- Install the app
user_oidcin Nextcloud - Fill in the details from authentik in the app settings
Troubleshooting
If you encounter problems during login check (error message containes SHA1 mismatch) that
- Nextcloud users and authentik users do not have the same name -> if they do check
Use unique user IDin the OIDC App settings