SAML 配置参考

关于 SAML 配置

若要使用 SAML 单点登录（SSO）对 GitHub 进行身份验证，您必须同时配置外部 SAML 身份提供商（IdP）以及在 你的 GitHub Enterprise Server 实例 上的企业或组织 。 在 SAML 配置中， GitHub 充当 SAML 服务提供商（SP）。 有关企业身份验证的详细信息，请参阅“标识和访问管理基础知识”。

GitHub 根据 SAML 2.0 规范提供集成。 有关详细信息，请参阅 OASIS 网站上的 SAML Wiki。

为 GitHub 配置 SAML SSO 时，您必须输入来自您的 SAML IdP 的唯一值，还必须在您的 IdP 中输入来自 GitHub 的唯一值。

SAML 元数据

你的 GitHub Enterprise Server 实例 的 SP 元数据可在 http(s)://HOSTNAME/saml/metadata 处获取，其中 HOSTNAME 是您的实例的主机名。 GitHub Enterprise Server 使用 urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST 绑定。

值	其他名称	说明	示例
SP 实体 ID	SP URL、受众限制
你的 GitHub Enterprise Server 实例 的顶级 URL	http(s)://HOSTNAME
SP 断言使用者服务 (ACS) URL	回复、收件人或目标 URL	IdP 发送 SAML 响应的 URL	http(s)://HOSTNAME/saml/consume
SP 单点登录 (SSO) URL
IdP 开始 SSO 的 URL	http(s)://HOSTNAME/sso

SAML 属性

以下 SAML 属性可用于 GitHub。 您可以更改 管理控制台 中的属性名称，但 administrator 属性除外。 有关详细信息，请参阅 从 Web UI 管理实例。

名称	必需	说明
NameID		持久用户标识符。 可以使用任意持久名称标识符格式。
GitHub将把 NameID 元素规范化为用户名，除非提供了其中一个替代断言。 有关详细信息，请参阅“外部身份验证的用户名注意事项”。

[!NOTE] 请务必使用易于阅读的永久性标识符。 使用暂时性标识符格式（如 urn:oasis:names:tc:SAML:2.0:nameid-format:transient）会导致每次登录时都重新链接帐户，这可能不利于授权管理。 | | SessionNotOnOrAfter | | GitHub 使关联会话失效的日期。 无效后，该人员必须再次进行身份验证才能访问你的 GitHub Enterprise Server 实例。 有关详细信息，请参阅会话持续时间和超时。 | | | | administrator | | 如果值为此值 true， GitHub 将自动将用户提升为站点管理员。 将此属性设置为除 true 以外的任何值都将导致降级，只要该值不为空。 省略此属性或将值保留为空白不会更改用户的角色。 | | username | | 你的 GitHub Enterprise Server 实例 的用户名。 | | | | full_name | | 则要在用户配置文件页上显示的用户的全名。 | | emails | | 用户的电子邮件地址。 可以指定多个地址。 如果您在 GitHub Enterprise Server 和 GitHub Enterprise Cloud 之间同步许可证使用情况，GitHub Connect 会使用 emails 来识别跨产品的唯一用户。 有关详细信息，请参阅“将许可证使用情况从 GitHub Enterprise Server 同步到云”。 | | public_keys | | 为用户配置公钥。 你可以指定多个密钥。 | | gpg_keys | | 为用户配置 GPG 密钥。 你可以指定多个密钥。 |

若要为属性指定多个值，请使用多个 <saml2:AttributeValue> 元素。

<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
    <saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
</saml2:Attribute>

SAML 响应要求

GitHub 要求来自 IdP 的响应消息满足以下要求。

• 你的 IdP 必须在根响应文档上提供 <Destination> 元素，并且仅在根响应文档已签名时才与 ACS URL 匹配。 如果 IdP 对断言进行签名， GitHub 将忽略断言。

• IdP 必须始终将 <Audience> 元素作为 <AudienceRestriction> 元素的一部分提供。 该值必须与你的 EntityId 值 GitHub匹配。 此值是访问 GitHub的 URL，例如 http(s)://HOSTNAME。

• 你的 IdP 必须在响应中提供带数字签名的单个断言。 可以通过对 <Assertion> 元素或 <Response> 元素进行签名来完成此操作。

• IdP 必须提供 <NameID> 元素作为 <Subject> 元素的一部分。 可以使用任意持久名称标识符格式。

• IdP 必须包含 Recipient 属性，该属性必须设置为 ACS URL。 下面的示例演示了该属性。

  <samlp:Response ...>
    <saml:Assertion ...>
      <saml:Subject>
        <saml:NameID ...>...</saml:NameID>
        <saml:SubjectConfirmation ...>
          <saml:SubjectConfirmationData Recipient="https://HOSTNAME/saml/consume" .../>
        </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:AttributeStatement>
        <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
          <saml:AttributeValue>monalisa</saml:AttributeValue>
        </saml:Attribute>
      </saml:AttributeStatement>
    </saml:Assertion>
  </samlp:Response>
  

用于 AuthnRequests 的 SAML 签名证书

首次设置 GitHub Enterprise Server 和启动实例时，将生成自签名 SAML 签名证书，与 IdP 的 SAML 证书分开。 此证书用于对发送到 IdP 的 SAML AuthnRequests 进行签名，有效期为十年。 它存储在 /data/user/common/saml-sp.p12，你可以在 http(s)://HOSTNAME/saml/metadata 查看 base64 编码格式的详细信息。

如果 IdP 验证了 SAML 签名证书，或者 SAML 加密断言已启用，则当证书过期时，用户可能会面临身份验证问题。 若要检查到期日期， GitHub Enterprise Server 管理员可以通过 SSH 连接到服务器并运行以下命令。 请参阅通过 SSH 连接到管理 shell。

sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate

若要重新生成此 SAML SP 签名证书（如果证书已过期且 IdP 或加密断言需要该证书）， GitHub Enterprise Server 管理员可以在 SSH 会话中 GitHub Enterprise Server 运行以下命令。

# Backup the old certificate
sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S)

saml_tempdir=$(sudo mktemp -d)
sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt
sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12
sudo rm -rf $saml_tempdir

sudo nomad stop github-unicorn
sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl

会话持续时间和超时

为防止某人通过您的 IdP 进行身份验证后无限期保持授权状态，GitHub 会定期使每个有权访问 你的 GitHub Enterprise Server 实例 的用户账户会话失效。 使之失效后，该用户必须再次向 IdP 进行身份验证。

默认情况下，如果您的 IdP 未为 SessionNotOnOrAfter 属性声明值，GitHub 会在通过您的 IdP 成功完成身份验证后的 一周 使会话失效。

GitHub 如果 IdP 提供配置 SessionNotOnOrAfter 属性和值的选项，并且此属性包含在 SAML 响应中，则支持自定义会话持续时间。 如果 IdP 不允许属性 SessionNotOnOrAfter ，则站点管理员可以使用 ghe-config saml.default-session-expiration [seconds] 管理程序中的命令为实例上的所有用户配置自定义 SAML 会话超时。

如果定义小于 24 小时的自定义会话持续时间值，则每次GitHub启动重定向时，GitHub都可能会提示用户进行身份验证。

不管实例上使用的身份验证方法如何，GitHub Enterprise Server 将在非活动状态连续两周后终止用户会话。