macadmins/crypt-server-saml

docker-crypt-server-saml 技术文档

1. 镜像概述和主要用途

docker-crypt-server-saml 是一个集成 SAML 认证的 Crypt Server Docker 容器，用于部署支持 SAML 单点登录（SSO）的 Crypt Server 服务。使用前需编辑 settings.py 配置文件，并提供 SAML 身份提供商（IdP）的 metadata.xml 文件。

2. 核心功能和特性

• 提供 Crypt Server 核心服务
• 集成 SAML 2.0 协议，支持单点登录（SSO）和单点登出（SLO）
• 通过配置文件自定义 SAML 属性映射与 IdP 连接信息
• 支持主流 SAML 身份提供商（如 OneLogin、Okta）
• 容器化部署，简化环境配置与依赖管理

3. 使用场景和适用范围

适用于需要部署 Crypt Server 并要求通过 SAML 协议实现身份认证的企业或组织环境，尤其适合已采用 OneLogin、Okta 等 SAML IdP 的场景，满足统一身份管理需求。

4. 使用方法和配置说明

4.1 配置文件准备

4.1.1 settings.py 必要修改

需修改以下关键配置项（值需根据实际 SAML 环境调整）：

• SAML_ATTRIBUTE_MAPPING
  SAML 属性与应用属性的映射关系，值来源于 LDAP、Active Directory 等用户存储。

• SAML_CONFIG
  SAML 服务提供商（SP）配置，包含：

  • entityid: SP 实体 ID，示例：https://crypt.example.com/saml2/metadata/
  • assertion_consumer_service: 断言消费者服务 URL，示例：https://crypt.example.com/saml2/acs/
  • single_logout_service: 单点登出服务 URL，示例：https://crypt.example.com/saml2/ls/ 和 https://crypt.example.com/saml2/post
  • required_attributes: 必需属性列表，需与 SAML_ATTRIBUTE_MAPPING 中的值匹配
  • idp: IdP 配置，包含：
    • root url: IdP 元数据 URL，示例：https://app.onelogin.com/saml/metadata/1234567890
    • single_sign_on_service: SSO 服务 URL，示例：https://apps.onelogin.com/trust/saml2/http-post/sso/1234567890
    • single_logout_service: SLO 服务 URL，示例：https://apps.onelogin.com/trust/saml2/http-redirect/slo/1234567890

4.2 Docker 部署示例

以下命令为基础模板（不完整，需补充实际路径），展示配置文件挂载方式：

bash
docker run -d --name="crypt" \
  -p 80:8000 \
  -v /本地路径/metadata.xml:/home/docker/crypt/fvserver/metadata.xml \
  -v /本地路径/settings.py:/home/docker/crypt/fvserver/settings.py \
  --restart="always" \
  macadmins/crypt-server-saml:2.2.0

参数说明：

• -p 80:8000: 端口映射（主机端口:容器端口）
• -v: 挂载本地 metadata.xml 和 settings.py 至容器内对应路径
• --restart="always": 容器退出后自动重启

4.3 SAML 提供商配置步骤

4.3.1 OneLogin 配置

1. 登录 OneLogin 管理后台，进入 Apps > Add Apps

2. 搜索并选择 SAML Test Connector (IdP)

3. 填写应用名称（可选上传图标），点击 Save

4. Configuration 标签页配置：

   • Recipient: https://crypt.example.com/saml2/acs/
   • ACS (Consumer) URL Validator: .*（点号+星号）
   • ACS (Consumer) URL: https://crypt.example.com/saml2/acs/

5. Parameters 标签页添加属性映射：
   点击 Add parameter，配置以下字段（需勾选 Include in SAML assertion）：

   FIELD_NAME	FIELD_VALUE
   urn:mace:dir:attribute-def:cn	First Name
   urn:mace:dir:attribute-def:sn	Last Name
   urn:mace:dir:attribute-def:mail	Email
   urn:mace:dir:attribute-def:uid	Email name part

6. SSO 标签页：

   • 下载 Issuer URL 对应的 metadata.xml 文件（用于容器挂载）
   • 记录 SAML 2.0 Endpoint 和 SLO Endpoint，填入 settings.py 的 idp 部分

7. 点击 Save 完成配置

4.3.2 Okta 配置

Okta 实现与 pysaml2/djangosaml2 存在兼容性差异，需按以下步骤配置：

1. 登录 Okta 管理后台，创建新应用：

   • Platform: Web
   • Sign on method: SAML 2.0

2. General Settings：填写应用名称（可选上传图标），配置可见性

3. Configure SAML：

   • General：

     • Single sign on URL: https://crypt.example.com/saml2/acs/
     • 勾选 Use this for Recipient URL and Destination URL
     • 取消勾选 Allow this app to request other SSO URLs（如存在）
     • Audience URI (SP Entity ID): https://crypt.example.com/saml2/metadata/
     • Default RelayState: 留空
     • Application username: Okta username

   • Attribute Statements：

     Name	Format	Value
     urn:mace:dir:attribute-def:cn	Basic	${user.firstName}
     urn:mace:dir:attribute-def:sn	Basic	${user.lastName}
     urn:mace:dir:attribute-def:mail	Basic	${user.email}
     urn:mace:dir:attribute-def:uid	Basic	${user.login}

   • Group Attribute Statements：暂不支持，留空

4. Feedback：

   • 选择 I'm an Okta customer adding an internal app
   • 选择 This is an internal app that we have created

5. 获取配置信息：

   • metadata.xml：从应用 Sign On > Settings > SAML 2.0 > Identity Provider metadata 下载
   • IdP URL：从 Sign On > Settings > SAML 2.0 > View Setup Instructions 获取，填入 settings.py 的 idp 部分

5. 参考与帮助

settings.py 配置细节可参考：https://github.com/knaperek/djangosaml2