Mustafa ERBAY

Posted on Aug 1 • Originally published at mustafaerbay.com.tr

Single Sign-On for Self-Hosted Services with Authentik

#selfhosting #guide #software

Managing multiple self-hosted services often leads to wasted time and increased security vulnerabilities by requiring separate usernames and passwords for each. Single Sign-On (SSO) solutions eliminate this problem by allowing users to access multiple applications with a single authentication process. Authentik, as an open-source and flexible Identity Provider (IdP) supporting standards like OpenID Connect (OIDC) and SAML, is an ideal SSO solution for self-hosted environments.

In this guide, we will cover step-by-step all processes from Authentik's installation to its integration with your self-hosted services, from security configurations to maintenance tips. Our goal is to provide a more secure and practical experience for your users and for you in your self-hosted environment. Authentik stands out, especially for its ease of deployment with Docker Compose and its wide range of integration options.

Why Single Sign-On (SSO) and Authentik Are Necessary

In modern system architectures and personal self-hosting projects, different services often have their own authentication mechanisms. Logging into each application separately, such as a file storage solution, a note-taking app, a media server, or a project management tool, negatively impacts user experience and leads to password fatigue. This situation paves the way for weak or reused passwords, increasing security risks.

SSO eliminates this fragmentation by allowing users to authenticate through a single central system and, upon successful verification, granting automatic access to all other integrated services. Authentik takes on this central Identity Provider role. Its open-source nature, flexibility, and support for modern authentication protocols (OIDC, SAML, LDAP) make it usable across a wide spectrum, from small personal projects to large enterprise infrastructures. Simplifying the user management complexity I've encountered in a production ERP or my own side projects with a solution like Authentik significantly increases operational efficiency while also strengthening the security posture.

💡 Pragmatic Approach

Using a centralized SSO solution instead of individual user management for each service not only improves user experience but also removes a significant burden from IT operations. When you add a new user or remove a user from the system, managing this process from a single location is much more practical.

Authentik offers various methods for authenticating users. Features like Multi-Factor Authentication (MFA) support, password policies, and user groups enhance the security level. Furthermore, its flexible connection mechanisms between applications and providers allow you to easily integrate your existing services with Authentik. This way, you gain the ability to manage all authentication and authorization processes through a central control point.

Authentik Installation Fundamentals

The most practical way to install Authentik in a self-hosted environment is by using Docker Compose. This method allows you to bring up all dependencies (PostgreSQL database, Redis, and Authentik services) with a single command. Before starting, ensure you have Docker and Docker Compose installed on your server. Additionally, it is highly recommended to obtain a domain name and an SSL certificate for accessing Authentik. A reverse proxy like Nginx will handle SSL termination and routing incoming requests to Authentik services.

For a basic Authentik installation, you can use the following docker-compose.yml file. This file includes the PostgreSQL database, Redis cache, and Authentik services. It is critical to replace values like POSTGRES_PASSWORD and AUTHENTIK_SECRET_KEY with strong, random values for security and data persistence. Furthermore, defining persistent volumes for the database and Authentik data files prevents data loss when containers are restarted or updated.

version: '3.8'

services:
  authentik:
    image: ghcr.io/goauthentik/authentik:2026.5 # Use the latest stable version
    restart: unless-stopped
    command: server
    environment:
      AUTHENTIK_SECRET_KEY: "your-super-secret-key-here" # MUST CHANGE
      AUTHENTIK_POSTGRESQL__HOST: postgres
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: "your-postgres-password-here" # MUST CHANGE
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_REDIS__PORT: 6379
      AUTHENTIK_REDIS__PASSWORD: "" # Add password here if required for Redis
    volumes:
      - authentik_data:/data # Directory /data is used from Authentik 2025.12 onwards.
    ports:
      - "9000:9000" # Web interface
      - "9443:9443" # HTTPS port for proxy (optional)

  worker:
    image: ghcr.io/goauthentik/authentik:2026.5 # Latest stable version, same as server
    restart: unless-stopped
    command: worker
    environment:
      AUTHENTIK_SECRET_KEY: "your-super-secret-key-here"
      AUTHENTIK_POSTGRESQL__HOST: postgres
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: "your-postgres-password-here"
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_REDIS__PORT: 6379
      AUTHENTIK_REDIS__PASSWORD: ""
    volumes:
      - authentik_data:/data # Directory /data is used from Authentik 2025.12 onwards.
    depends_on:
      - authentik

  postgres:
    image: postgres:16-alpine # Use the latest stable PostgreSQL version
    restart: unless-stopped
    environment:
      POSTGRES_DB: authentik
      POSTGRES_USER: authentik
      POSTGRES_PASSWORD: "your-postgres-password-here" # MUST CHANGE
    volumes:
      - authentik_postgres:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    # password: "your-redis-password-here" # Optional, if using a password

volumes:
  authentik_data: # A single volume for Authentik's media and static files
  authentik_postgres:

Save this docker-compose.yml file in a directory like authentik-sso and run docker compose up -d in the same directory to start Authentik. The first time it runs, Authentik will prompt you to create an administrator account. Create this account by accessing the Authentik interface in your browser (usually http://localhost:9000 or the domain you configured via Nginx). A point to note during setup is that sensitive information like AUTHENTIK_SECRET_KEY should not be left directly in the docker-compose.yml file. Instead, more secure methods like .env files or Docker Swarm/Kubernetes secret management should be preferred. For automated setup, you can use the AUTHENTIK_BOOTSTRAP_PASSWORD_HASH environment variable.

Provider and Application Configuration in Authentik

At the heart of Authentik lie the concepts of "Provider" and "Application." A Provider defines Authentik's authentication mechanism (e.g., OpenID Connect or SAML). An Application represents your self-hosted service that will use this Provider for authentication. To integrate a self-hosted service with Authentik, you first need to create a Provider and an associated Application in the Authentik interface.

Since most modern web applications support the OpenID Connect (OIDC) protocol, let's start by creating an OIDC Provider. In the Authentik Admin Interface, navigate to Applications > Applications and click the New Provider button to create both the application and the provider together. Alternatively, navigate to Applications > Providers, click Create, and select the OpenID Connect Provider option. Here, you will need to fill in the following fields:

Name: Give the Provider a descriptive name (e.g., "Web App OIDC").
Authorization flow: Usually, "Authorization Code flow" or "Authorization Code flow with PKCE" is selected. "Authorization Code flow with PKCE" is a more secure option for browser-based applications.
Client ID: A unique identifier automatically generated by Authentik. This will be used in the application you integrate.
Client Secret: Another secret key generated by Authentik. It ensures secure communication between the application and Authentik. Do not share this key with anyone.
Redirect URIs: These are the URLs your application will be redirected to by Authentik after authentication. For example, https://your-app.com/oauth2/callback. You can add multiple URIs, but each one must be exact and correct.

After creating the Provider, it's time to create the Application. Navigate to Applications > Applications and click Create (if you didn't create it along with the New Provider). Here, enter the following information:

Name: The name of your application (e.g., "My Personal Notes App").
Slug: A unique identifier to be used in URLs (e.g., notes-app).
Provider: Select the OIDC Provider you just created.

With these steps, Authentik becomes an authentication point for your application. Now, you will use the Client ID, Client Secret, and Redirect URIs provided by Authentik to configure the OIDC integration in your application.

The diagram above illustrates the basic steps of the OIDC Authorization Code Flow. When a user tries to access the application, the application redirects them to Authentik. After Authentik verifies the user's identity, it redirects them back to the application with an authorization code. The application then uses this code and the Client Secret to request an Access Token and ID Token from Authentik. These tokens prove the user's identity and authorization.

Integrating Self-Hosted Services with Authentik

After installing Authentik and defining a Provider and Application, it's time to integrate your self-hosted services into this SSO solution. The integration method depends on whether your application supports OIDC or SAML. Most modern web applications directly support OIDC. For applications that do not, Authentik Outpost can be used.

1. Applications with Direct OIDC Support:
If your application natively supports OIDC, you simply need to enter the Client ID, Client Secret, Redirect URI, and Authentik's OIDC endpoint URLs (Issuer URL, Authorization URL, Token URL, Userinfo URL) obtained from Authentik into your application's authentication settings. You can find these URLs in your Authentik Provider configuration.

For example, for a popular Git server or a project management tool, you would typically enter information like:

Client ID: Authentik's Client ID
Client Secret: Authentik's Client Secret
Issuer URL: The base URL of your Authentik instance (e.g., https://auth.domain.com/application/o/web-app-oidc/)
Authorization URL: Authentik's authorization endpoint
Token URL: Authentik's token endpoint
Userinfo URL: Authentik's user info endpoint
Scopes: Requested user information like openid profile email

After correctly entering this information, your application will start authenticating via Authentik. When users access your application, they will be automatically redirected to the Authentik login page and redirected back to your application upon successful login.

2. Integration with Nginx Reverse Proxy (Using Authentik Outpost):
For some older applications or those without OIDC/SAML support, Authentik Outpost acts as a proxy. Outpost sits between Authentik and your application, managing the authentication process on behalf of Authentik. In this scenario, your application doesn't need to know about OIDC directly. Outpost is typically placed behind a reverse proxy like Nginx.

As an example scenario, let's protect an internal web application with SSO using Nginx and Authentik Outpost. First, you need to add an Outpost service to your docker-compose.yml file:

  authentik_proxy:
    image: ghcr.io/goauthentik/proxy:2026.5 # Use the latest stable version
    restart: unless-stopped
    environment:
      AUTHENTIK_HOST: http://authentik:9000 # Internal URL of the Authentik service
      AUTHENTIK_TOKEN: "your-authentik-token-for-outpost" # Token to be generated from Authentik interface
      AUTHENTIK_SERVER_ADDRESS: https://your-app.com # The publicly accessible URL of your application
    ports:
      - "8080:9000" # Port Outpost will listen on
    depends_on:
      - authentik

Then, you need to create a proxy outpost in the Authentik interface under Applications > Outposts and obtain the AUTHENTIK_TOKEN value mentioned above. You must associate this outpost with an Authentik Application.

In your Nginx configuration, you need to direct incoming requests to the Outpost:

server {
    listen 80;
    server_name your-app.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-app.com;

    ssl_certificate /etc/nginx/ssl/your-app.com.crt;
    ssl_certificate_key /etc/nginx/ssl/your-app.com.key;

    location / {
        proxy_pass http://authentik_proxy:8080; # Port Outpost is listening on
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

With this configuration, all requests to your-app.com are forwarded by Nginx to the Outpost. The Outpost redirects the user to Authentik before they can access pages requiring authentication. After successful authentication, the Outpost forwards the request to your application. This method allows you to bring even older applications under the SSO umbrella.

Security and Advanced Customizations

Beyond basic SSO functionality, Authentik offers a range of advanced features to enhance the security of your self-hosted environments and customize the user experience. Correctly configuring these features is critical, especially in enterprise environments or for applications handling sensitive data.

1. Multi-Factor Authentication (MFA):
MFA adds an extra layer of verification to username and password authentication, significantly improving security. Authentik supports various MFA methods:

TOTP (Time-based One-Time Password): Time-based codes used with applications like Google Authenticator, Authy.
WebAuthn/FIDO2: Stronger authentication with hardware keys (like YubiKey) or biometric readers.
SMS/Email: Codes sent to a phone number or email address.

You can enable MFA stages by navigating to Admin Interface > Flows & Stages > Authentication in the admin interface. Once a user sets up MFA, they will be prompted to verify with MFA each time they log into Authentik or after a certain period. As I saw in a bank's internal platform, MFA usage creates a significant barrier against cyberattacks.

2. Access Policies:
Authentik provides flexible policy engines that allow you to define who can access applications or resources under what conditions. Policies can make access decisions based on user group memberships, IP addresses, device types, or the time of day. For example, you can create an IP-based policy that restricts access to a specific application to only users within the company network.

You can create new policies in Admin Interface > Customization > Policies.
You can enforce policies by binding them to an application, provider, flow, or stage.
You can combine multiple policies to provide conditional access (e.g., "Grant access if user is in group X AND comes from the company IP range").

3. Rate Limiting and Security Monitoring:
It is important to use Authentik's built-in rate-limiting features against DDoS attacks or brute-force attempts. Authentik can limit the number of failed login attempts from a specific IP address or user. Furthermore, regularly reviewing Authentik's audit logs is a critical step in detecting potential security breaches.

By integrating Authentik's logs with external tools like fail2ban, you can automatically block IP addresses that make too many failed login attempts within a certain period. Additionally, monitoring file access and system calls of Authentik services using system monitoring tools like auditd at the operating system level can be beneficial for in-depth security analysis. Such proactive security measures make your self-hosted environments more resilient.

Maintenance, Updates, and Troubleshooting Tips

The continuous and secure operation of a central identity provider like Authentik is vital for all integrated services. Therefore, regular maintenance, planned updates, and effective troubleshooting strategies are inevitable.

1. Database Maintenance and Backup:
Authentik stores user data, application configurations, and logs in the PostgreSQL database. Regularly backing up this database provides a recovery point in case of a disaster. Both physical (e.g., file system copy or pg_basebackup) and logical (pg_dump) backup methods should be considered. It is important to regularly run VACUUM operations or optimize autovacuum settings to prevent WAL bloat issues in PostgreSQL. I recall a customer project where the system experienced severe performance degradation due to PostgreSQL filling up the disk; this illustrates how important regular database maintenance and disk space monitoring are.

# Logical backup example
docker compose exec postgres pg_dump -U authentik -d authentik > authentik_backup_$(date +%Y%m%d%H%M%S).sql

⚠️ Backup Warning

This command only creates a logical backup of the database. For a full disaster recovery plan, it is also important to back up Authentik's media files (if not using external storage) and your Docker Compose files.

2. Updating Authentik and Dependencies:
Authentik and its dependencies like Redis and PostgreSQL regularly receive security patches and new features. Keeping track of these updates and applying them in a planned manner is essential to maintain your system's security and performance. Always remember to take a backup before updating. You can perform the update by changing the image tags in the docker-compose.yml file to the updated version and running docker compose pull followed by docker compose up -d.

⚠️ Pre-Update Testing and Sequencing

Before performing a major update in a production environment, testing the update in a staging environment allows you to detect potential compatibility issues or unexpected behaviors in advance. Carefully read Authentik's release notes. Important: Authentik upgrades must be performed sequentially between major versions; direct jumps from an old major version to the latest are not supported. After upgrading to the latest minor version within each major release, proceed to the next major version.

3. Troubleshooting Tips:
When you encounter an issue with Authentik or its integrated services, the following steps usually help diagnose the problem:

Check Logs: Examine the Docker logs of Authentik services (server and worker) (docker compose logs authentik and docker compose logs worker). Similarly, checking the logs of Nginx and the applications you've integrated is critical to understanding the source of the error. Monitoring system logs with journald can also provide information about overall system health.
Network Connectivity: Verify network connectivity between Authentik and the integrated services. Incorrect firewall rules, misconfigurations in DNS, or MTU/MSS mismatches can disrupt the authentication flow.
Configuration Check: Ensure that Client IDs, Client Secrets, Redirect URIs, and OIDC endpoint URLs match exactly in both Authentik and the integrated application. Even a small typo can break the entire flow.
Certificate Issues: Make sure SSL/TLS certificates are valid and correctly configured. Invalid or expired certificates will lead to security warnings in browsers and authentication errors.

These maintenance and troubleshooting approaches provide a roadmap for ensuring your self-hosted SSO solution operates smoothly and without interruption. Regular audits and proactive measures prevent major issues and guarantee operational continuity.

Conclusion

Adding single sign-on (SSO) capability to your self-hosted services with Authentik offers significant benefits in terms of both security and user experience. In this guide, we covered a broad spectrum, from Authentik's installation to OpenID Connect (OIDC) provider and application configuration, integration methods with self-hosted services, advanced security features, and maintenance tips. By establishing a centralized identity management system, you eliminate the hassle of users logging into each service separately, while simultaneously making authentication processes more secure and manageable.

Authentik's flexible structure and support for modern protocols make it a powerful tool capable of meeting diverse needs, from personal projects to enterprise solutions. Remember that, like any system, Authentik requires regular maintenance, updates, and security monitoring for its long-term stability. By following these steps, you can create a secure and seamless SSO experience in your self-hosted environment. Your next step should be to experience Authentik in your own environment and practice integration with your various services.