SAML 配置参考

关于 SAML 配置

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

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

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

SAML 元数据

GitHub Enterprise Cloud 的 SP 元数据可供启用了 SAML SSO 的组织或企业使用。 GitHub 使用 urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST 绑定。

如果使用 Enterprise Managed Users，则只能在企业级启用 SAML SSO。

组织

可以为企业中的单个组织配置 SAML SSO。如果您在 GitHub Enterprise Cloud 上使用的是个人组织，并且不使用企业账户，也可以为该组织配置 SAML 单点登录 (SSO)。有关详细信息，请参阅“管理组织的 SAML 单点登录”。

在 GitHub 上，某个组织的 SP 元数据可在 https://github.com/orgs/ORGANIZATION/saml/metadata 获取，其中 ORGANIZATION 是您的组织在 GitHub 上的名称。

值	其他名称	说明	示例
SP 实体 ID	SP URL、受众限制	您的组织在 GitHub.com 上的顶级 URL	`https://github.com/orgs/ORGANIZATION`
SP 断言使用者服务 (ACS) URL	回复、收件人或目标 URL	IdP 发送 SAML 响应的 URL	`https://github.com/orgs/ORGANIZATION/saml/consume`
SP 单点登录 (SSO) URL
IdP 开始 SSO 的 URL	`https://github.com/orgs/ORGANIZATION/sso`

企业

根据环境，企业 GitHub Enterprise Cloud 版的 SP 元数据可在以下任一位置获取：

https://github.com/enterprises/ENTERPRISE/saml/metadata，其中 ENTERPRISE 是企业的名称****
https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN/saml/metadata，其中 SUBDOMAIN 是企业的子域****

值	其他名称	说明	示例
SP 实体 ID	SP URL、受众限制	您的企业的顶级 URL GitHub.com	`https://github.com/enterprises/ENTERPRISE`
SP 断言使用者服务 (ACS) URL	回复、收件人或目标 URL	IdP 发送 SAML 响应的 URL	`https://github.com/enterprises/ENTERPRISE/saml/consume`
SP 单点登录 (SSO) URL
IdP 开始 SSO 的 URL	`https://github.com/enterprises/ENTERPRISE/sso`

SAML 属性

以下 SAML 属性可用于 GitHub。

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

[!NOTE] 请务必使用易于阅读的永久性标识符。使用暂时性标识符格式（如 urn:oasis:names:tc:SAML:2.0:nameid-format:transient）会导致每次登录时都重新链接帐户，这可能不利于授权管理。 | | SessionNotOnOrAfter | | GitHub 使关联会话失效的日期。无效后，该人员必须再次进行身份验证才能访问企业的资源。有关详细信息，请参阅会话持续时间和超时。 | | | | full_name | | 如果为企业配置 SAML SSO 并使用Enterprise Managed Users，则要在用户配置文件页上显示的用户的全名。 | | emails | | 用户的电子邮件地址。如果您在 GitHub Enterprise Server 和 GitHub Enterprise Cloud 之间同步许可证使用情况，GitHub Connect 会使用 emails 来识别跨产品的唯一用户。有关详细信息，请参阅“将许可证使用情况从 GitHub Enterprise Server 同步到云”。 | | public_keys | | 如果为企业配置 SAML SSO 并使用Enterprise Managed Users，则为用户配置公钥。你可以指定多个密钥。 | | gpg_keys | | 如果为企业配置 SAML SSO 并使用Enterprise Managed Users，则为用户配置 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匹配。
- 如果为组织配置 SAML，则此值为 https://github.com/orgs/ORGANIZATION。
- 如果为企业配置 SAML，则此 URL 为 https://github.com/enterprises/ENTERPRISE 或 https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN。
你的 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://github.com/enterprises/ENTERPRISE/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>

会话持续时间和超时

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

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

GitHub 如果 IdP 提供配置 SessionNotOnOrAfter 属性和值的命令为实例上的所有用户配置自定义 SAML 会话超时。

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

若要防止身份验证错误，建议至少会话持续时间为 4 小时。有关详细信息，请参阅“SAML 身份验证故障排除”。

注意

Microsoft Entra ID（以前称为 Azure AD）不支持 SessionNotOnOrAfter 属性。此外，Entra ID 颁发的 SAML 令牌的可配置的生存期策略GitHub。

在本文中