OIDC Pages

OIDC pages使用OIDC为身份验证和文档级别的授权（权限）提供静态HTML文档。

该软件设计用于与sphinx、doxygen或mdbook等工具生成的HTML结合使用，但也可以与任何静态HTML配合使用。

截图

功能

• 与Keycloak集成
• 尊重系统的深色/浅色设置
• 提供NixOS模块
• 支持动态上传的文档
• 默认安全

限制

• 可能与其他OIDC提供商不兼容
• 会话存储在内存中，重启时将被删除
• 不适用于提供不受信任的内容

适配其他OIDC提供商

有两个假设使此软件针对Keycloak。

1. OIDC规范没有定义访问令牌的类型，Keycloak使用JSON Web令牌，这是事实上的标准。
2. OIDC规范没有提供读取角色的标准方式。假设角色位于 resource_access -> <client_id> -> roles。

大多数OIDC提供商使用JWT作为访问令牌，所需的唯一修改应该是如何获取角色。

计划的功能

这些功能可能发生也可能不发生。

• 公开文档
• 持久化用户会话
• 刷新令牌
• 从S3提供服务页面
• 当axum#2479解决时，通过Unix域套接字监听
• 精美的错误页面
• 通过子域而不是路径提供服务页面
• 页面图像预览

安全

请向我的git提交者邮箱报告漏洞。

技术

• 语言: rust
• 异步运行时: tokio
• Web框架: axum
• 会话管理：tower-sessions
• 模板引擎：askama
• OpenID Connect 库：openidconnect-rs
• Favicon 由 Flowbite 提供

用法

此设计用于与 NixOS 一起使用，但应在任何带有 systemd 的 Linux 操作系统上正常工作。

您需要为 TLS 提供反向代理，我建议使用 nginx。

Keycloak 配置

• 在您的领域创建并启用一个 OpenID Connect 客户端
  • 根 URL：https://pages.company.com
  • 主页 URL：https://pages.company.com
  • 有效的重定向 URI：https://pages.company.com/callback
  • 客户端认证：开启
  • 授权：关闭
  • 认证流程：标准流程（其他所有选项已禁用）
• 为新建客户端创建角色
  • admin 角色可以查看所有页面
  • 所有其他角色允许用户访问具有相同名称的目录的页面
• 为新建客户端创建一个专门的受众映射器
  • 导航到 客户端 -> <client_id> -> 客户端作用域 -> <client_id>-dedicated -> 配置新的映射器 -> 受众
  • 名称：aud-mapper-<client_id>
  • 包含的客户端受众：<client_id>
  • 添加到 ID 令牌：开启
  • 添加到访问令牌：开启
  • 添加到轻量级访问令牌：关闭
  • 添加到令牌 introspection：开启

NixOS 配置

有关选项的完整列表，请参考 nixos/module.nix，以下是我的配置示例。

{
  oidc_pages,
  config,
  ...
}: let
  bindAddr = "127.0.0.1:38443";
  pagesDomain = "pages.company.com";
in {
  # import the module, this adds the "services.oidc_pages" options
  imports = [oidc_pages.nixosModules.default];

  # add the overlay, this puts "oidc_pages" into "pkgs"
  nixpkgs.overlays = [oidc_pages.overlays.default];

  # use nix-sops to manage secrets declaratively
  # https://github.com/Mic92/sops-nix
  sops.secrets.oidc_pages.mode = "0400";

  # reference module for descriptions of configuration
  services.oidc_pages = {
    enable = true;
    environmentFiles = [config.sops.secrets.oidc_pages.path];
    settings = {
      public_url = "https://${pagesDomain}";
      issuer_url = "https://sso.company.com/realms/company";
      client_id = "pages";
      pages_path = "/var/www/pages";
      log_level = "info";
      bind_addrs = [bindAddr];
    };
  };

  # use NGINX as a reverse proxy to provide a TLS (https) interface
  networking.firewall.allowedTCPPorts = [443];
  services.nginx = {
    enable = true;
    virtualHosts."${pagesDomain}" = {
      onlySSL = true;
      locations."/".proxyPass = "http://${bindAddr}";
    };
  };
}