amd64/satosa

SATOSA Docker镜像文档

重要说明

本仓库是https://hub.docker.com/_/satosa%E7%9A%84%60amd64%60%E6%9E%B6%E6%9E%84%E6%9E%84%E5%BB%BA%E7%89%88%E6%9C%AC%E3%80%82%E6%9C%89%E5%85%B3%E6%9B%B4%E5%A4%9A%E4%BF%A1%E6%81%AF%EF%BC%8C%E8%AF%B7%E5%8F%82%E9%98%85%E5%AE%98%E6%96%B9%E9%95%9C%E5%83%8F%E6%96%87%E6%A1%A3%E4%B8%AD%E7%9A%84https://github.com/docker-library/official-images#architectures-other-than-amd64%E5%92%8C%E5%AE%98%E6%96%B9%E9%95%9C%E5%83%8FFAQ%E4%B8%AD%E7%9A%84https://github.com/docker-library/faq#an-images-source-changed-in-git-now-what%E3%80%82

快速参考

• 维护者：
  https://github.com/IdentityPython/satosa-docker

• 获取帮助：
  Identity Python邮件列表 或 Identity Python Slack工作区（邀请链接）

支持的标签及对应的Dockerfile链接

（请参阅FAQ中的https://github.com/docker-library/faq#whats-the-difference-between-shared-and-simple-tags%EF%BC%89

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://github.com/IdentityPython/satosa-docker/issues?q=

• 支持的架构：(https://github.com/docker-library/official-images#architectures-other-than-amd64)
  https://hub.docker.com/r/amd64/satosa/, https://hub.docker.com/r/arm64v8/satosa/

• 镜像制品详情：
  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
  （镜像元数据、传输大小等）

• 镜像更新：
  https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Fsatosa
  https://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

什么是SATOSA？

SATOSA是一个可配置的代理，用于在SAML2、OpenID Connect和OAuth2等不同身份验证协议之间进行转换。

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

使用本镜像

启动satosa实例的基本命令模式：

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

要从主机访问实例而不使用容器IP，请使用端口映射：

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

入口脚本在启动时会将SAML2元数据输出到容器日志中。此元数据引用实例的基础URL，例如https://example.com。浏览器必须能够通过HTTPS访问该实例。

配置文件

satosa镜像将其配置存储在/etc/satosa中。此配置必须在实例之间持久化，特别是SAML2实体ID（默认从代理的基础URL派生）和相关密钥材料。使用卷、绑定挂载或自定义镜像来维护此配置。

入口脚本

如果第一个参数看起来像命令行标志，satosa镜像的入口脚本默认运行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 amd64/satosa \
    -b0.0.0.0:8443 --certfile /etc/https.crt --keyfile /etc/https.key satosa.wsgi:app

如果第一个参数看起来像命令而不是标志，入口脚本将运行该命令而不是Gunicorn。例如，以下命令将在容器内启动一个交互式非特权shell：

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

环境变量

入口脚本使用环境变量生成初始配置，这需要自定义。所有环境变量均为可选。

环境变量的值可以从Docker secrets读取。在变量名后附加_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密钥对。

镜像变体

amd64/satosa镜像有多种版本，每种版本设计用于特定用例。

amd64/satosa:<version>

这是默认镜像。如果不确定自己的需求，可能需要使用此版本。它既可以用作临时容器（挂载源代码并启动容器以启动应用），也可以作为构建其他镜像的基础。

某些标签可能包含如bookworm之类的名称。这些是Debian发行版的代号，表示镜像所基于的发行版。如果镜像需要安装除自带软件之外的其他包，可能需要显式指定其中一个代号，以最大程度减少Debian新版本发布时的中断。

amd64/satosa:<version>-alpine

此镜像基于流行的Alpine Linux项目，可在https://hub.docker.com/_/alpine%E4%B8%AD%E8%8E%B7%E5%8F%96%E3%80%82Alpine Linux比大多数发行版基础镜像小得多（约5MB），因此通常会生成更精简的镜像。

当最终镜像大小尽可能小是主要关注点时，此变体非常有用。需要注意的是，它使用musl libc而不是glibc及相关库，因此软件可能会根据其libc要求/假设的深度而遇到问题。有关可能出现的问题以及使用基于Alpine的镜像的优缺点比较，请参阅此Hacker News评论线程。

为了最小化镜像大小，基于Alpine的镜像中通常不包含其他相关工具（如git或bash）。以该镜像为基础，可在自己的Dockerfile中添加所需内容（如果不熟悉如何安装包，请参阅https://hub.docker.com/_/alpine/%E4%B8%AD%E7%9A%84%E7%A4%BA%E4%BE%8B%EF%BC%89%E3%80%82

许可证

查看此镜像中包含的软件的https://github.com/IdentityPython/SATOSA/blob/master/LICENSE%E3%80%82

与所有Docker镜像一样，这些镜像可能还包含其他软件，这些软件可能采用其他许可证（例如基础发行版中的Bash等，以及包含的主要软件的任何直接或间接依赖项）。

可能能够自动检测到的一些其他许可证信息可以在https://github.com/docker-library/repo-info/tree/master/repos/satosa%E4%B8%AD%E6%89%BE%E5%88%B0%E3%80%82

对于任何预构建镜像的使用，镜像用户有责任确保对该镜像的任何使用都符合其中包含的所有软件的相关许可证。