基于 Terraform 实现 Authentik 与 SonarQube 的 SAML 单点登录集成
SonarQube 是一款广泛采用的自托管静态代码分析平台，它通过持续检查代码质量和安全性，帮助开发团队提升软件产品的可靠性。
准备工作
在开始配置之前，我们假设您已经部署了 Authentik 和 SonarQube 实例。本指南中将使用以下域名作为示例占位符：
sonarqube.company：代表您的 SonarQube 服务完整域名。authentik.company：代表您的 Authentik 身份提供者完整域名。
Terraform 提供者设置
为了通过基础设施即代码（IaC）的方式管理 Authentik 配置，我们将利用 Terraform 及其 Authentik 提供者。首先，确保您的系统上已安装 Terraform。以下是针对 Linux 和 macOS 的常见安装方法：
# 对于基于 Debian/Ubuntu 的系统
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
# 对于 macOS (使用 Homebrew)
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
配置 Authentik Terraform 提供者
在项目根目录创建 providers.tf 文件（或任意 .tf 文件），声明所需的 Authentik 提供者并进行基本配置：
terraform {
required_providers {
authentik = {
source = "goauthentik/authentik"
version = "~> 2025.10.0" # 请根据您的 Authentik 版本更新此约束
}
}
}
provider "authentik" {
# Authentik 实例的 URL 地址
authentik_url = "http://authentik.company"
# 用于 Terraform 认证的 API 令牌
api_token = "YOUR_AUTHENTIK_API_TOKEN_HERE" # 从 Authentik 后台生成
# 在生产环境中，建议设置为 false 以确保安全连接
insecure = false
}
获取 Authentik API Token：
- 登录到您的 Authentik 管理界面。
- 导航至左侧菜单：Directory → Tokens。
- 点击创建新令牌，并确保授予超级管理员权限。
- 复制生成的 API 令牌，替换上述 Terraform 配置中的
YOUR_AUTHENTIK_API_TOKEN_HERE。
定义 SAML 提供者和 Authentik 应用程序
创建一个名为 sonarqube_saml.tf（或任意名称）的文件，定义 SonarQube 所需的 SAML 提供者和 Authentik 应用程序：
# 引用默认授权流程，用于用户登录验证
data "authentik_flow" "default_auth_flow" {
slug = "default-provider-authorization-implicit-consent"
}
# 引用默认登出流程
data "authentik_flow" "default_invalidation_flow" {
slug = "default-invalidation-flow"
}
# 定义一个 SAML 2.0 身份提供者给 SonarQube
resource "authentik_provider_saml" "sonarqube_saml_provider" {
name = "SonarQube SAML IDP"
authorization_flow = data.authentik_flow.default_auth_flow.id
invalidation_flow = data.authentik_flow.default_invalidation_flow.id
# SonarQube 的断言消费者服务 (ACS) URL
acs_url = "http://sonarqube.company/oauth2/callback/saml"
# Authentik 作为 IdP 的实体 ID
issuer = "http://authentik.company"
# 指定 SAML 响应的绑定方式
sp_binding = "post"
# SonarQube 服务提供者 (SP) 的实体 ID
audience = "http://sonarqube.company/saml2/metadata"
# 重要提示：此处不配置 property_mappings，Authentik 将使用其默认属性映射，
# 这简化了配置，并通常满足 SonarQube 的需求。
}
# 在 Authentik 中创建一个代表 SonarQube 的应用程序
resource "authentik_application" "sonarqube_app" {
name = "SonarQube"
slug = "sonarqube"
protocol_provider = authentik_provider_saml.sonarqube_saml_provider.id
}
执行 Terraform 配置
完成上述配置文件后，在终端中导航到您的 Terraform 项目目录并执行以下命令：
# 1. 初始化 Terraform 工作目录，下载 Authentik 提供者插件
terraform init
# 2. 预览将要创建或修改的资源，确认操作计划
terraform plan
# 3. 应用配置，根据计划创建资源。系统会提示您输入 'yes' 确认。
terraform apply
调整属性映射（如果需要）
尽管我们未在 Terraform 中显式配置 property_mappings，Authentik 会提供一组默认映射。在某些情况下，您可能需要根据 SonarQube 的特定要求调整这些映射。
您可以通过 Authentik 管理界面导航到 Applications -> Providers，找到您创建的 SonarQube SAML 提供者，然后修改其"属性映射"。确保如以下截图所示，默认映射能够满足 SonarQube 对用户名、邮箱等属性的期望。
配置 SonarQube
现在，转向 SonarQube 端进行 SAML 认证配置：
- 登录 SonarQube 管理界面。
- 导航到 Administration > Configuration > General Settings > Authentication > SAML。
- 启用 SAML 认证。
- 按照以下值填写配置项：
- Application ID (应用程序 ID)：
http://sonarqube.company - Provider Name (提供者名称)：
authentik - Provider ID (提供者 ID)：
http://authentik.company - SAML Login URL (SAML 登录 URL)：
http://authentik.company/application/saml/sonarqube/sso/binding/redirect/ - Identity Provider Certificate (身份提供者证书)：从 Authentik 下载（在 Authentik 应用详情页中获取）
- SAML User Login Attribute (SAML 用户登录属性)：
http://schemas.goauthentik.io/2021/02/saml/username - SAML Username Attribute (SAML 用户名属性)：
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name - SAML User Email Attribute (SAML 用户电子邮件属性)：
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- Application ID (应用程序 ID)：
验证集成
完成 SonarQube 的 SAML 配置后，进行验证：
- 注销当前的 SonarQube 会话。
- 在 SonarQube 的登录页面，您应该会看到一个名为"使用 Authentik 登录"或类似描述的按钮。
- 点击此按钮，系统会将您重定向到 Authentik 进行身份验证。
- 成功通过 Authentik 认证后，您将被自动重定向回 SonarQube 并登录，这标志着 SAML 单点登录集成成功。
