使用 SAML
SAML 是一种基于 XML 的身份验证和授权标准。 GitHub Enterprise Server 可以作为您的内部 SAML 身份提供程序 (IdP) 的服务提供程序 (SP)。
如果要对未添加到身份提供程序的用户进行身份验证,您可以配置内置身份验证。更多信息请参阅“允许对身份提供程序覆盖范围以外的用户进行内置身份验证”。
本文内容:
- 支持的 SAML 服务
- 使用 SAML 时的用户名考量因素
- 双重身份验证
- SAML 元数据
- SAML 属性
- 配置 SAML 设置
- 撤销 您的 GitHub Enterprise Server 实例 的权限
- 响应消息的要求
- 错误消息
支持的 SAML 服务
我们为实施 SAML 2.0 标准的所有身份提供程序提供有限的支持。我们官方支持这些经过内部测试的身份提供程序:
- Active Directory Federation Services (AD FS)
- Azure Active Directory (Azure AD)
- Okta
- OneLogin
- PingOne
- Shibboleth
GitHub Enterprise 不支持 SAML 单点注销。要终止活动的 SAML 会话,用户应直接在 SAML 服务器上注销。
使用 SAML 时的用户名考量因素
每个 GitHub Enterprise Server 用户名都由 SAML 响应中的以下断言之一决定,这些断言按优先级从高到低排列的顺序为:
- 自定义用户名属性(如果定义且存在)
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
断言(如果存在)http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
断言(如果存在)NameID
元素
即使其他属性存在,也需要 NameID
元素。
将在 NameID
与 GitHub Enterprise Server 用户名之间创建映射,NameID
应持久、唯一,并且在用户生命周期内不会发生变化。
GitHub Enterprise Server 用户名只能包含字母数字和短划线 (-
)。 GitHub Enterprise Server 会将帐户用户名中的所有非字母数字字符标准化为短划线。 例如,用户名 gregory.st.john
将标准化为 gregory-st-john
。 请注意,标准化的用户名也不能以短划线开头或结尾。 它们还不能包含两个连续的短划线。
创建自电子邮件地址的用户名使用前置 @
字符的标准化字符创建。
如果多个帐户标准化为同一个 GitHub Enterprise Server 用户名,则只创建第一个用户帐户。 使用相同用户名的后续用户无法登录。
此表格举例说明 GitHub Enterprise Server 中如何标准化用户名:
用户名 | 标准化的用户名 | 结果 |
---|---|---|
Ms.Bubbles | ms-bubbles |
此用户名已成功创建。 |
!Ms.Bubbles | -ms-bubbles |
此用户名无法创建,因其以短划线开头。 |
Ms.Bubbles! | ms-bubbles- |
此用户名无法创建,因其以短划线结尾。 |
Ms!!Bubbles | ms--bubbles |
此用户名无法创建,因其包含两个连续的短划线。 |
Ms!Bubbles | ms-bubbles |
此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。 |
Ms.Bubbles@example.com | ms-bubbles |
此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。 |
双重身份验证
使用 SAML 或 CAS 时,双重身份验证在 GitHub Enterprise Server 设备上不受支持或无法管理,但受外部身份验证提供商的支持。 在组织上无法实施双重身份验证。 有关在组织上实施双重身份验证的更多信息,请参阅“您的组织中需要双重身份验证”。
SAML 元数据
您的 GitHub Enterprise Server 实例的服务提供程序元数据位于 http(s)://[hostname]/saml/metadata
下。
要手动配置您的身份提供程序,断言使用者服务 (ACS) URL 为 http(s)://[hostname]/saml/consume
。 它使用 urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
绑定。
SAML 属性
以下属性可用。 您可以在 Management Console 中更改属性名称,但 administrator
属性除外。
默认属性名称 | 类型 | 描述 |
---|---|---|
NameID |
必选 | 持久用户标识符。 可以使用任意持久名称标识符格式。 除非提供备用断言之一,否则将为 GitHub Enterprise Server 用户名使用 NameID 元素。 |
administrator |
可选 | 如果值为“true”,用户将被自动升级为管理员。 任何其他值或不存在的值会将用户降级为普通用户帐户。 |
用户名 |
可选 | GitHub Enterprise Server 用户名。 |
full_name |
可选 | 用户的个人资料页面上显示的姓名。 用户可以在配置后更改他们的姓名。 |
emails |
可选 | 用户的电子邮件地址。 可以指定多个。 |
public_keys |
可选 | 用户的 SSH 公钥。 可以指定多个。 |
gpg_keys |
可选 | 用户的 GPG 密钥。 可以指定多个。 |
配置 SAML 设置
-
In the upper-right corner of any page, click .
-
在左侧边栏中,单击 管理控制台。
-
In the left sidebar, click Authentication.
-
选择 SAML。
-
(可选)选择 Allow built-in authentication(允许内置身份验证)以邀请用户使用内置身份验证(如果他们不属于 您的 GitHub Enterprise Server 实例 的身份提供程序)。
-
或者,要启用非请求响应 SSO,请选择 IdP initiated SSO。 默认情况下,GitHub Enterprise Server 将向 IdP 发回
AuthnRequest
,回复非请求身份提供程序 (IdP) 发起的请求。注:我们建议保留此值处于未选择状态。 您只应在罕见的情况下启用此功能,即您的 SAML 实现不支持服务提供程序发起的 SSO,并且 GitHub Enterprise 支持 建议执行此操作。
-
Select Disable administrator demotion/promotion if you do not want your SAML provider to determine administrator rights for users on 您的 GitHub Enterprise Server 实例.
-
在 Single sign-on URL 字段中,为单点登录请求输入您的 IdP 上的 HTTP 或 HTTPS 端点。 此值由您的 IdP 配置提供。 如果主机只能在您的内部网络中使用,您需要先将 您的 GitHub Enterprise Server 实例 配置为使用内部域名服务器。
-
(可选)在 Issuer(签发者) 字段中,输入您的 SAML 签发者的姓名。 这将验证发送到 您的 GitHub Enterprise Server 实例 的消息的真实性。
-
In the Signature Method and Digest Method drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from 您的 GitHub Enterprise Server 实例. 使用 Name Identifier Format 下拉菜单指定格式。
-
Under Verification certificate, click Choose File and choose a certificate to validate SAML responses from the IdP.
-
如果需要,请修改 SAML 属性名称以匹配您的 IdP,或者接受默认名称。
撤销 您的 GitHub Enterprise Server 实例 的权限
如果您将某个用户从您的身份提供程序中移除,还必须手动挂起他们。 否则,他们仍可以继续使用访问令牌或 SSH 密钥进行身份验证。 更多信息请参阅“挂起和取消挂起用户”。
响应消息的要求
响应消息必须满足以下要求:
<Destination>
元素必须在根响应文档上提供 ,并匹配 ACS URL。- 如果
<Audience>
元素作为<AudienceRestriction>
元素的一部分提供,将根据 GitHub Enterprise Server 实体 Id 检查此元素。这是 GitHub Enterprise Server 实例的 URL,例如https://ghe.corp.example.com
。 - 响应中的每一个断言都必须由数字签名加以保护。 签署各个
<Assertion>
元素或签署<Response>
元素可以实现此操作。 <NameID>
元素必须作为<Subject>
元素的一部分提供。 可以使用任意持久名称标识符格式。Recipient
属性必须存在并设为 ACS URL。 例如:
<samlp:Response ...>
<saml:Assertion ...>
<saml:Subject>
<saml:NameID ...>...</saml:NameID>
<saml:SubjectConfirmation ...>
<saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/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>
错误消息
如果 Recipient
与 ACS URL 不匹配,身份验证日志中将显示以下错误消息:
Recipient in the SAML response was not valid.
如果 Recipient
不是响应消息的一部分,身份验证日志中将显示以下错误消息:
Recipient in the SAML response must not be blank.
如果 SAML 响应未签名,或者签名与内容不匹配,身份验证日志中将显示以下错误消息:
SAML Response is not signed or has been modified.