library/satosa

SATOSA Docker镜像文档

镜像概述

SATOSA（Secure Attribute Token Service）是一款可配置的代理工具，核心功能是在不同的认证协议之间进行转换，如SAML2、OpenID Connect和OAuth2。该镜像提供了SATOSA的容器化部署方案，便于快速集成到身份认证架构中，支持多种操作系统基础镜像和硬件架构。

!https://raw.githubusercontent.com/docker-library/docs/8e1f8cd99d5ce31197d5452d6d04886f791ac9c7/satosa/logo.svg?sanitize=true

维护与支持

• 维护方：https://github.com/IdentityPython/satosa-docker
• 获取帮助：Identity Python邮件列表 或 Identity Python Slack工作区（邀请链接）
• 问题反馈：https://github.com/IdentityPython/satosa-docker/issues?q=

支持的标签及对应Dockerfile链接

简单标签（Simple Tags）

• https://github.com/IdentityPython/satosa-docker/blob/8420c19d43d36f132e015a981df54f30dc54980f/8.5/bookworm/Dockerfile
• https://github.com/IdentityPython/satosa-docker/blob/8420c19d43d36f132e015a981df54f30dc54980f/8.5/alpine3.22/Dockerfile

共享标签（Shared Tags）

• 8.5.1, 8.5, 8, latest:
  • 对应 https://github.com/IdentityPython/satosa-docker/blob/8420c19d43d36f132e015a981df54f30dc54980f/8.5/bookworm/Dockerfile

其他参考信息

• 支持的架构：https://hub.docker.com/r/amd64/satosa/, https://hub.docker.com/r/arm64v8/satosa/%EF%BC%88https://github.com/docker-library/official-images#architectures-other-than-amd64%EF%BC%89
• 镜像 artifact 详情：https://github.com/docker-library/repo-info/blob/master/repos/satosa%EF%BC%88https://github.com/docker-library/repo-info/commits/master/repos/satosa%EF%BC%89%EF%BC%88%E5%8C%85%E5%90%AB%E9%95%9C%E5%83%8F%E5%85%83%E6%95%B0%E6%8D%AE%E3%80%81%E4%BC%A0%E8%BE%93%E5%A4%A7%E5%B0%8F%E7%AD%89%EF%BC%89
• 镜像更新：https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Fsatosa%E3%80%81https://github.com/docker-library/official-images/blob/master/library/satosa%EF%BC%88https://github.com/docker-library/official-images/commits/master/library/satosa%EF%BC%89
• 本文档来源：https://github.com/docker-library/docs/tree/master/satosa%EF%BC%88https://github.com/docker-library/docs/commits/master/satosa%EF%BC%89

核心功能与特性

• 多协议转换：支持SAML2、OpenID Connect、OAuth2等主流认证协议之间的双向转换
• 可配置代理：通过灵活的配置文件定制认证流程和协议映射规则
• 加密状态跟踪：使用加密Cookie跟踪认证流程进度，确保安全性
• SAML联邦支持：集成SAML发现服务，支持身份提供商选择
• 密钥自动生成：默认自动生成RSA密钥对，简化初始部署流程

使用场景

• 企业身份系统整合：在现有SAML2身份提供商与基于OpenID Connect的应用之间建立桥梁
• 跨平台认证代理：为不同协议的应用提供统一的认证入口
• 身份联邦接入：作为服务提供者接入SAML联邦，或作为身份提供者对接依赖方

使用方法

基本运行

启动SATOSA实例的基本命令：

sh
docker run --name some-satosa -d satosa

端口映射

如需从主机访问实例（无需容器IP），使用端口映射：

sh
docker run --name some-satosa -p 80:8080 -d satosa

注意：入口脚本在启动时会将SAML2元数据输出到容器日志，元数据中包含实例的基础URL（如 https://example.com）。浏览器必须能通过HTTPS访问实例。

配置文件

SATOSA镜像的配置文件存储在 /etc/satosa 目录。为保证实例间配置一致性（尤其是SAML2实体ID及相关密钥材料），需通过卷、绑定挂载或自定义镜像持久化配置。

入口脚本

默认情况下，若第一个参数为命令行标志，入口脚本会运行Gunicorn。例如，使用绑定挂载提供X.509证书和私钥，并启用HTTPS运行Gunicorn：

sh
docker run --name some-satosa -p 443:8443 \
    -v /etc/letsencrypt/live/some-satosa/fullchain.pem:/etc/https.crt \
    -v /etc/letsencrypt/live/some-satosa/privkey.pem:/etc/https.key \
    -d satosa \
    -b0.0.0.0:8443 --certfile /etc/https.crt --keyfile /etc/https.key satosa.wsgi:app

若第一个参数为命令（非标志），入口脚本会运行该命令。例如，启动容器内的交互式非特权shell：

sh
docker run -it --name some-satosa satosa bash

环境变量

入口脚本使用环境变量生成初始配置，所有变量均为可选。变量值可通过Docker密钥读取：在变量名后添加 _FILE（如 STATE_ENCRYPTION_KEY_FILE），并将其值设为密钥文件路径（如 /run/secrets/state_encryption_key）。

BASE_URL

SATOSA必须托管在网站根目录。此变量指定网站基础URL，默认值为 http://example.com。若设置，基础URL必须包含协议和主机名，不含尾部斜杠或路径，例如 https://idproxy.example.com（不可为 https://idproxy.example.com/ 或 https://idproxy.example.com/satosa）。

STATE_ENCRYPTION_KEY

SATOSA使用加密Cookie跟踪认证流程进度。此变量可选设置状态Cookie的加密密钥，必须为字母数字值（如 12345SameAsMyLuggage）。若未指定，将自动生成32字符随机密钥。

SAML2_BACKEND_DISCO_SRV

在SAML信任联邦中，SATOSA通过SAML发现服务让用户选择身份提供商。此变量设置发现服务URL，默认值为SeamlessAccess。

SAML2_BACKEND_CERT 和 SAML2_BACKEND_KEY

SATOSA默认SAML后端微服务作为服务提供者（依赖方），向用户选择的身份提供商请求认证和属性。该微服务使用公钥加密技术签名认证请求并解密响应。这两个变量提供PEM格式的密钥材料，若未指定，将使用 BASE_URL 的主机名部分自动生成2048位RSA密钥对。

SAML2_FRONTEND_CERT 和 SAML2_FRONTEND_KEY

SATOSA默认SAML前端微服务作为身份提供商（凭证服务提供者），处理来自可信网站的认证请求并返回用户属性，使用公钥加密技术签名认证响应。这两个变量提供PEM格式的密钥材料，若未指定，将使用 BASE_URL 的主机名部分自动生成2048位RSA密钥对。

镜像变体

SATOSA镜像提供多种版本，适用于不同场景：

satosa:<version>（默认版本）

基于Debian系统（如bookworm），是通用镜像。若不确定需求，建议使用此版本。适合作为临时容器（挂载源码启动应用）或构建其他镜像的基础。标签中包含的 bookworm 等名称是Debian发行版的代号，指定基础系统版本，如需安装额外包，建议显式指定以减少版本变更带来的影响。

satosa:<version>-alpine

基于Alpine Linux（来自 https://hub.docker.com/_/alpine%EF%BC%89%EF%BC%8C%E4%BB%A5%E6%9E%81%E5%B0%8F%E7%9A%84%E9%95%9C%E5%83%8F%E4%BD%93%E7%A7%AF%E4%B8%BA%E4%B8%BB%E8%A6%81%E4%BC%98%E5%8A%BF%EF%BC%88%E5%9F%BA%E7%A1%80%E9%95%9C%E5%83%8F%E7%BA%A65MB%EF%BC%89%E3%80%82%E9%80%82%E5%90%88%E5%AF%B9%E9%95%9C%E5%83%8F%E5%A4%A7%E5%B0%8F%E6%9C%89%E4%B8%A5%E6%A0%BC%E8%A6%81%E6%B1%82%E7%9A%84%E5%9C%BA%E6%99%AF%E3%80%82%E6%B3%A8%E6%84%8F%EF%BC%9A%E8%AF%A5%E5%8F%98%E4%BD%93%E4%BD%BF%E7%94%A8musl libc而非glibc，部分依赖glibc的软件可能存在兼容性问题。此外，Alpine镜像通常不包含额外工具（如 git 或 bash），需在Dockerfile中自行安装（参考 https://hub.docker.com/_/alpine/ 了解包安装方法）。

许可信息

查看https://github.com/IdentityPython/SATOSA/blob/master/LICENSE%E3%80%82%E4%B8%8E%E6%89%80%E6%9C%89Docker%E9%95%9C%E5%83%8F%E4%B8%80%E6%A0%B7%EF%BC%8C%E6%9C%AC%E9%95%9C%E5%83%8F%E5%8F%AF%E8%83%BD%E5%8C%85%E5%90%AB%E5%85%B6%E4%BB%96%E8%BD%AF%E4%BB%B6%EF%BC%8C%E9%9C%80%E9%81%B5%E5%AE%88%E5%90%84%E8%87%AA%E8%AE%B8%E5%8F%AF%EF%BC%88%E5%A6%82%E5%9F%BA%E7%A1%80%E7%B3%BB%E7%BB%9F%E7%9A%84Bash%E7%AD%89%EF%BC%89%E3%80%82%E8%87%AA%E5%8A%A8%E6%A3%80%E6%B5%8B%E7%9A%84%E9%A2%9D%E5%A4%96%E8%AE%B8%E5%8F%AF%E4%BF%A1%E6%81%AF%E5%8F%AF%E5%9C%A8https://github.com/docker-library/repo-info/tree/master/repos/satosa%E4%B8%AD%E6%89%BE%E5%88%B0%E3%80%82%E4%BD%BF%E7%94%A8%E6%9C%AC%E9%95%9C%E5%83%8F%E6%97%B6%EF%BC%8C%E7%94%A8%E6%88%B7%E9%9C%80%E7%A1%AE%E4%BF%9D%E9%81%B5%E5%AE%88%E6%89%80%E6%9C%89%E5%8C%85%E5%90%AB%E8%BD%AF%E4%BB%B6%E7%9A%84%E7%9B%B8%E5%85%B3%E8%AE%B8%E5%8F%AF%E3%80%82===SHORT_DESC=== SATOSA是一款可配置的代理工具，用于在SAML2、OpenID Connect和OAuth2等不同认证协议之间进行转换。 ===FULL_DESC===# SATOSA Docker镜像文档

镜像概述

SATOSA（Secure Attribute Token Service）是一款可配置的代理工具，核心功能是在不同的认证协议之间进行转换，如SAML2、OpenID Connect、OAuth2等。该镜像提供容器化部署方案，便于快速集成到身份认证架构中，支持多种操作系统基础和硬件架构。

!https://raw.githubusercontent.com/docker-library/docs/8e1f8cd99d5ce31197d5452d6d04886f791ac9c7/satosa/logo.svg?sanitize=true

维护与支持

• 维护方：https://github.com/IdentityPython/satosa-docker
• 获取帮助：Identity Python邮件列表 或 Identity Python Slack工作区（邀请链接）
• 问题反馈：https://github.com/IdentityPython/satosa-docker/issues?q=

支持的标签及Dockerfile链接

简单标签（Simple Tags）

• https://github.com/IdentityPython/satosa-docker/blob/8420c19d43d36f132e015a981df54f30dc54980f/8.5/bookworm/Dockerfile
• https://github.com/IdentityPython/satosa-docker/blob/8420c19d43d36f132e015a981df54f30dc54980f/8.5/alpine3.22/Dockerfile

共享标签（Shared Tags）

• 8.5.1, 8.5, 8, latest:
  • 对应 https://github.com/IdentityPython/satosa-docker/blob/8420c19d43d36f132e015a981df54f30dc54980f/8.5/bookworm/Dockerfile

其他参考信息

• 支持架构：https://hub.docker.com/r/amd64/satosa/, https://hub.docker.com/r/arm64v8/satosa/%EF%BC%88https://github.com/docker-library/official-images#architectures-other-than-amd64%EF%BC%89
• 镜像详情：https://github.com/docker-library/repo-info/blob/master/repos/satosa%EF%BC%88https://github.com/docker-library/repo-info/commits/master/repos/satosa%EF%BC%89%EF%BC%88%E5%90%AB%E5%85%83%E6%95%B0%E6%8D%AE%E3%80%81%E4%BC%A0%E8%BE%93%E5%A4%A7%E5%B0%8F%E7%AD%89%EF%BC%89
• 镜像更新：https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Fsatosa%E3%80%81https://github.com/docker-library/official-images/blob/master/library/satosa%EF%BC%88https://github.com/docker-library/official-images/commits/master/library/satosa%EF%BC%89
• 文档来源：https://github.com/docker-library/docs/tree/master/satosa%EF%BC%88https://github.com/docker-library/docs/commits/master/satosa%EF%BC%89

核心功能与特性

• 多协议转换：支持SAML2、OpenID Connect、OAuth2等协议双向转换
• 可配置代理：通过配置文件定制认证流程和协议映射规则
• 安全状态跟踪：使用加密Cookie跟踪认证流程，保障数据安全
• SAML联邦支持：集成发现服务，支持身份提供商选择
• 密钥自动管理：默认自动生成RSA密钥对，简化部署

使用场景

• 企业身份系统整合：连接SAML2身份提供商与OpenID Connect应用
• 跨平台认证代理：为不同协议应用提供统一认证入口
• 身份联邦接入：作为服务提供者接入SAML联邦或作为身份提供者对接依赖方

使用方法

基本运行

sh
docker run --name some-satosa -d satosa

端口映射

如需从主机访问，映射容器端口（默认8080）：

sh
docker run --name some-satosa -p 80:8080 -d satosa

注意：启动时容器日志会输出SAML2元数据，元数据中的基础URL需确保浏览器可通过HTTPS访问。

配置文件

配置存储路径：/etc/satosa，需通过卷、绑定挂载或自定义镜像持久化，以保留SAML2实体ID及密钥材料。

入口脚本

默认运行Gunicorn（若参数为命令行标志），示例：启用HTTPS运行

sh
docker run --name some-satosa -p 443:8443 \
    -v /etc/letsencrypt/live/some-satosa/fullchain.pem:/etc/https.crt \
    -v /etc/letsencrypt/live/some-satosa/privkey.pem:/etc/https.key \
    -d satosa \
    -b0.0.0.0:8443 --certfile /etc/https.crt --keyfile /etc/https.key satosa.wsgi:app

若参数为命令，直接运行命令（如启动交互式shell）：

sh