DOCSEARCHbyAlgolia
Submit Docs

authentik-nix

repository·main·Indexed 41 days ago

https://github.com/nix-community/authentik-nix

A Nix flake providing packaging and a NixOS module for the authentik identity provider. It simplifies the deployment of authentik services—including the server, worker, and outposts—and its required PostgreSQL database on NixOS. The module includes support for Nginx and Let's Encrypt certificate management, and provides guidance on managing secrets via systemd EnvironmentFiles to keep sensitive data out of the /nix/store.

Tokens
1.6K
Snippets
6
Records
7
Agent score
2%

What's inside authentik-nix

  1. Migrate authentik-nix to a new machine

    main

    When migrating an authentik-nix deployment, follow these steps:

    1. Data Migration: Copy /var/lib/authentik to the new machine. Be aware that this directory contains symlinks; the /media directory is particularly important.
    2. Database: Dump the database according to upstream documentation. Since certificates are stored in the database by default, restoring the database will migrate your certificates.
    3. Version Pinning: Lock the specific revision of authentik-nix used in your build to prevent accidental upgrades or downgrades during the migration process.
    4. Domain Testing: Authentik can run on different domains or base URLs. You can test the deployment on a temporary domain before updating your production DNS records.

  2. Install authentik-nix without Flakes

    main

    If you are not using Flakes, you can fetch the source via builtins.fetchTarball and import it directly into your configuration.

    # configuration.nix
{
  let
    authentik-version = "2024.2.3";
    authentik-nix-src = builtins.fetchTarball {
      url = "https://github.com/nix-community/authentik-nix/archive/version/${authentik-version}.tar.gz";
      sha256 = "15b9a2csd2m3vwhj3xc24nrqnj1hal60jrd69splln0ynbnd9ki4";
    };
    authentik-nix = import authentik-nix-src;
  in
  {
    imports = [ authentik-nix.nixosModules.default ];
    services.authentik = { /* ... */ };
    system.stateVersion = "23.11";
  }
}

  3. Manage secrets using an EnvironmentFile

    main

    To keep secrets out of the /nix/store, create a systemd EnvironmentFile on your host machine that is accessible only by root. This file should contain your sensitive authentik credentials.

    Example content for the file (after generating a key with openssl rand -base64 60):

    AUTHENTIK_SECRET_KEY=<generated secret key>
AUTHENTIK_EMAIL__PASSWORD=<smtp password>

  4. Install authentik-nix using Flakes

    main

    To use authentik-nix with Flakes, add the input to your flake.nix and import the module.

    Note on Overrides: If you use a different version of nixpkgs than the one used by the flake, you may encounter issues with Python dependencies. You can use follows to align versions:

    • inputs.nixpkgs.follows = "nixpkgs"
    • inputs.flake-parts.follows = "flake-parts"
    # flake.nix
{
  inputs.authentik-nix = {
    url = "github:nix-community/authentik-nix";
    # Optional: align nixpkgs versions to avoid python dependency issues
    # inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = inputs@{ ... }: {
    nixosConfigurations = {
      authentik-host = inputs.nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          inputs.authentik-nix.nixosModules.default
          { 
            services.authentik = { 
              # configuration here 
            };
          }
        ];
      };
    };
  };
}

  5. Configure Nginx and Let's Encrypt for authentik

    main

    You can enable Nginx and automatic Let's Encrypt certificate management within the authentik module. This configuration allows authentik to auto-discover the certificate and key. Note that initial discovery may take up to an hour as the discovery task runs periodically.

    services.authentik = {
  nginx = {
    enable = true;
    enableACME = true;
    host = "auth.example.com";
  };
};

  6. Configure the authentik NixOS module

    main

    The services.authentik NixOS module enables authentik services and, by default, configures a local PostgreSQL instance. You can customize the upstream authentik configuration by providing values under services.authentik.settings.

    Important Security Note: Sensitive information like secret keys and passwords should not be placed directly in your Nix configuration (as they would end up in the world-readable /nix/store). Instead, use the environmentFile option to point to a systemd EnvironmentFile located on the target host. It is recommended to manage this file using tools like sops-nix or agenix.

    services.authentik = {
  enable = true;
  # Path to a systemd EnvironmentFile on the target host
  environmentFile = "/run/secrets/authentik/authentik-env";
  settings = {
    email = {
      host = "smtp.example.com";
      port = 587;
      username = "authentik@example.com";
      use_tls = true;
      use_ssl = false;
      from = "authentik@example.com";
    };
    disable_startup_analytics = true;
    avatars = "initials";
  };
};

  7. Run authentik-nix integration tests

    main

    To verify the module configuration and ensure services start and pass the initial setup flow, run the integration tests using nix build.

    nix build .#checks.x86_64-linux.default --print-build-logs
# OR
nix build .#checks.aarch64-linux.default --print-build-logs