authentik-nix

一个提供 authentik 软件包、NixOS 模块和基本 VM 测试的 Nix flake

重要说明

请注意，本项目与官方 authentik 项目没有直接关联。最重要的是，这意味着该打包和部署方式没有官方支持。因此，当遇到与此 flake 相关的问题时，请勿向官方项目提交 issue。欢迎在此处提交 issue。如有疑问，请先在此处提交 issue，以便我们确认该问题并非直接与此打包/部署方式相关，然后再向官方项目升级处理。

概述

flake.nix 此 flake 将软件包（server、worker、outposts 等）作为输出提供，并包含一个 NixOS 模块以及针对该模块的简单 VM 集成测试。
module.nix 该 NixOS 模块配置 authentik 服务以及（默认情况下）一个本地 postgres 实例。上游默认的 authentik 配置可以通过在 services.authentik.settings 下设置所需参数进行部分覆盖。
poetry2nix-python-overrides.nix 包含用于构建 python 环境的覆盖和修复
minimal-vmtest.nix 一个最小的 NixOS VM 测试。确认由模块配置的服务已启动，并手动执行初始设置流程。在测试执行期间会截取一些屏幕截图，以确认前端是否正确渲染。
components 一个可覆盖的作用域，包含各个 authentik 组件。override-scope.nix 中提供了创建自定义作用域的示例，该示例使用了 mkAuthentikScope。它与来自 NixOS stable 或 unstable 分支的软件包集合 pkgs 一起使用。属性 legacyPackages.${system}.authentikComponents 是一个快捷方式，用于作为此函数针对本仓库中固定的 pkgs 的实例化。

用法

配置示例：

{
  services.authentik = {
    enable = true;
    # The environmentFile needs to be on the target host!
    # Best use something like sops-nix or agenix to manage it
    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";
    };
  };
}

用于密钥的 EnvironmentFile

environmentFile 选项引用了一个 systemd EnvironmentFile，该文件需要放置在与 authentik 相同的主机上，并且应仅对 root 可访问。在此环境文件中指定密钥，可以避免它们被放置在所有用户可读的 /nix/store 中。请注意，pkgs.writeText 及类似工具也会导致密钥被放置在 /nix/store 中。

在为 authentik 生成密钥后，例如使用 openssl rand -base64 60，文件的内容应如下所示：

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

在 authentik 主机上手动管理环境文件的更优替代方案可能是 https://github.com/Mic92/sops-nix 或 https://github.com/ryantm/agenix ，具体取决于您的使用场景。

使用 flakes

将 authentik-nix 添加到您的 flake 中，导入模块并进行配置。flake 的相关部分：

# flake.nix
{
  inputs.authentik-nix = {
    url = "github:nix-community/authentik-nix";

    ## optional overrides. Note that using a different version of nixpkgs can cause issues, especially with python dependencies
    # inputs.nixpkgs.follows = "nixpkgs"
    # inputs.flake-parts.follows = "flake-parts"
  };

  outputs = inputs@{ ... }: {

    ## regular NixOS example
    #
    # nixosConfigurations = {
    #   authentik-host = inputs.nixpkgs.lib.nixosSystem {
    #     system = "x86_64-linux";
    #     modules = [
    #       inputs.authentik-nix.nixosModules.default
    #       {
    #         services.authentik = {
    #           # ... further configuration; see example configuration above
    #         };
    #       }
    #     ];
    #   };
    # };

    ## Colmena example
    #
    # colmena = {
    #   meta.specialArgs.inputs = { inherit (inputs) authentik-nix; };
    #
    #   authentik-host = { inputs, ... }: {
    #     imports = [ inputs.authentik-nix.nixosModules.default ];
    #
    #     services.authentik = {
    #       # ... further configuration; see example configuration above
    #     };
    #   };
    # };
  };
}

不使用 flakes

所有包、模块和测试均可通过 flake-compat 使用，并且可以在不使用 flakes 的情况下使用。这需要一些额外的工作，但以下 NixOS 配置示例可能有助于你入门：

# 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";
}

Nginx + Let's Encrypt

示例配置：

{
  services.authentik = {
    # other authentik options as in the example configuration at the top
    nginx = {
      enable = true;
      enableACME = true;
      host = "auth.example.com";
    };
  };
}

上述配置将 authentik 配置为自动发现 Let's Encrypt 证书和密钥。初始自动发现可能需要一些时间，因为 authentik 证书发现任务每小时运行一次。

测试

要运行主要集成测试，请执行以下命令之一：

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

二进制缓存

本项目使用了 nix-community 的 CI 基础设施。成功 CI 运行的构建产物应从相应的 Cachix 实例获取：

https://app.cachix.org/cache/nix-community

迁移

在将 authentik-nix 部署从一台机器迁移到另一台机器时，以下注意事项可能有所帮助。

将 /var/lib/authentik 复制到新机器，并注意它是一个符号链接。/media 最为重要。
锁定用于构建 authentik-nix 的修订版本，以免意外降级或升级，从而在需要时使调试更加困难。
根据上游文档转储数据库。
- 默认情况下，证书写入数据库，而非文件系统。通过恢复数据库来迁移证书是可行的。
authentik 在不同的域名或基础 URL 下运行正常，您可以先测试所有内容，然后再为生产部署调整 DNS 记录。

许可证

本项目根据 MIT 许可证的条款发布。请参阅 LICENSE。有关 authentik 许可的信息，请参阅上游项目。