SAMLの利用

About SAML for GitHub Enterprise Server

SAML SSO allows people to authenticate and access your GitHub Enterprise Server instance through an external system for identity management.

SAML は認証と認可のための XML ベースの標準です。 When you configure SAML for your GitHub Enterprise Server instance, the external system for authentication is called an identity provider (IdP). Your instance acts as a SAML service provider (SP). For more information, see Security Assertion Markup Language on Wikipedia.

If you want to authenticate some users without adding them to your identity provider, you can configure built-in authentication in addition to SAML SSO. 詳細は「使用中のアイデンティティプロバイダ外のユーザのためにビルトイン認証を許可する」を参照してく� さい。

サポートされているSAMLサービス

GitHub Enterprise Server は、SAML2.0 標準を実装し IdP を使用した SAML SSO をサポートします。詳しい情� �については、OASIS Web サイトの SAML Wiki を参照してく� さい。

GitHub officially supports and internally tests the following IdPs.

Active Directory フェデレーションサービス (AD FS)
Azure Active Directory (Azure AD)
Okta
OneLogin
PingOne
Shibboleth

GitHub Enterprise ServerはSAMLシングルログアウトをサポートしていません。アクティブなSAMLセッションを終了させるには、ユーザーは直接SAML IdPでログアウトしなければなりません。

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 は永続的で一意でなければならず、ユーザのライフサイクルにおいて変更にさらされないようにする必要があります。

注釈: ユーザの NameID が IdP で変更された� �合、ユーザが GitHub Enterprise Server インスタンスにサインインしようとすると、エラーメッセージが表示されます。 To restore the user's access, you'll need to update the user account's NameID mapping. 詳しい情� �については、「ユーザの SAML NameID を更新する」を参照してく� さい。

GitHub Enterprise Serverのユーザ名に使えるのは、英数字とダッシュ（-）のみです。 GitHub Enterprise Serverは、アカウントのユーザ名に含まれている非英数字をダッシュに変換します。たとえばgregory.st.johnというユーザ名は、gregory-st-johnに変換されます。変換されたユーザ名の先� �及び末尾はダッシュであってはならないことに注意してく� さい。 2つの連続するダッシュを含めることもできません。

メールアドレスから作成されたユーザ名は、@以前の文字を変換して作成されます。

複数のアカウントが変換後に同じGitHub Enterprise Serverのユーザ名になる� �合、最初のユーザアカウント� けが作成されます。同じユーザ名のそれ以降のユーザは、サインインできません。

以下の表は、ユーザ名がGitHub Enterprise Serverでどのように変換されるかの例を示しています。

ユーザ名	変換されたユーザ名	結果
Ms.Bubbles	`ms-bubbles`	このユーザ名の作成は成功します。
!Ms.Bubbles	`-ms-bubbles`	このユーザ名はダッシュで始まるので作成されません。
Ms.Bubbles!	`ms-bubbles-`	このユーザ名はダッシュで終わるので作成されません。
Ms!!Bubbles	`ms--bubbles`	このユーザ名には連続する2つのダッシュが含まれるので作成されません。
Ms!Bubbles	`ms-bubbles`	このユーザ名は作成されません。変換されたユーザ名は正当ですが、すでに存在しています。
Ms.Bubbles@example.com	`ms-bubbles`	このユーザ名は作成されません。変換されたユーザ名は正当ですが、すでに存在しています。

2 要� 認証

SAMLあるいはCASを利用する� �合、GitHub Enterprise Server上では2要� 認証はサポートあるいは管理されませんが、外部の認証プロバイダではサポートされることがあります。 Organizationでの2要� 認証の強制はできません。 Organizationにおける2要� 認証の強制に関する詳しい情� �については「Organizationにおける2要� 認証の要求」を参照してく� さい。

SAMLのメタデータ

The service provider metadata for your GitHub Enterprise Server instance is available at http(s)://[hostname]/saml/metadata.

アイデンティティプロバイダを手動で設定するなら、Assertion Consumer Service (ACS) URLはhttp(s)://[hostname]/saml/consumeです。これはurn:oasis:names:tc:SAML:2.0:bindings:HTTP-POSTバインディングを利用します。

SAMLの属性

以下の属性が利用できます。 You can change the attribute names in the management console, with the exception of the administrator attribute.

デフォルトの属性名	種類	説明
`NameID`	必� �	永続ユーザ識別子。任意の名前識別子の形式を使用できます。どの代替アサーションも指定しない� �合、GitHub Enterprise Serverユーザ名には`NameID`要� が使用されます。
`administrator`	任意	この値が 'true' であれば、ユーザは自動的に管理者に昇� �します。他の値、あるいは値が存在しない� �合は、ユーザは通常のユーザアカウントに降� �します。
`ユーザ名`	任意	GitHub Enterprise Server のユーザ名
`full_name`	任意	ユーザのプロフィールページに表示されるユーザ名です。ユーザはプロビジョニング後に名前を変更できます。
`emails`	任意	ユーザのメールアドレス。複数指定することができます。
`public_keys`	任意	ユーザの公開 SSH キー。複数指定することができます。
`gpg_keys`	任意	ユーザの GPG キー。複数指定することができます。

To specify more than one value for an attribute, use multiple <saml2:AttributeValue> elements.

<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の設定

From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .
If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.
左のサイドバーでManagement Consoleをクリックしてく� さい。
左のサイドバーでAuthentication（認証）をクリックしてく� さい。
SAMLを選択してく� さい。
Optionally, to allow people to use built-in authentication if they don't have an account on your IdP, select Allow built-in authentication. 詳細は「使用中のアイデンティティプロバイダ外のユーザのためにビルトイン認証を許可する」を参照してく� さい。
オプションで、未承諾応答SSOを有効化する� �合は [IdP initiated SSO] を選択します。デフォルトでは、GitHub Enterprise Serverは未承認アイデンティティプロバイダ (IdP) 起点のリクエストに対して、IdPへのAuthnRequest返信で応答します。

Note: We recommend keeping this value unselected. You should enable this feature only in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by GitHub Enterprise Support.
your GitHub Enterprise Server instance 上のユーザの管理者権限を SAML プロバイダに決めさせたくない� �合、[Disable administrator demotion/promotion] を選択します。
Optionally, to allow your GitHub Enterprise Server instance to send and receive encrypted assertions to and from your SAML IdP, select Require encrypted assertions. For more information, see "Enabling encrypted assertions."
Warning: Incorrectly configuring encrypted assertions can cause all authentication to your GitHub Enterprise Server instance to fail.
- You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide your GitHub Enterprise Server instance's public certificate to your IdP. For more information, see "Enabling encrypted assertions."
- Before enabling encrypted assertions, GitHub recommends testing encrypted assertions in a staging environment, and confirming that SAML authentication functions as you expect. 詳しい情� �については "ステージングインスタンスのセットアップ"を参照してく� さい。
In the Single sign-on URL field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. この値はIdpの設定によって決まります。 If the host is only available from your internal network, you may need to configure your GitHub Enterprise Server instance to use internal nameservers.
Optionally, in the Issuer field, type your SAML issuer's name. This verifies the authenticity of messages sent to your GitHub Enterprise Server instance.
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 your GitHub Enterprise Server instance. Specify the format with the Name Identifier Format drop-down menu.
[Verification certificate] の下で、[Choose File] をクリックし、IdP からの SAML のレスポンスを検証するための証明書を選択してく� さい。
Modify the SAML attribute names to match your IdP if needed, or accept the default names.

Updating a user's SAML `NameID`

From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .
If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.
SAMLを選択してく� さい。
ユーザーのリストで、NameID マッピングを更新するユーザ名をクリックします。
ページ右上にある、 Security（セキュリティ） をクリックしてく� さい。
[Update SAML NameID] の右にある [Edit] アイコンをクリックします。
[NameID] フィールドに、ユーザの新しい NameID を入力します。
[Update NameID] をクリックします。

your GitHub Enterprise Server instanceへのアクセスの削除

アイデンティティプロバイダからユーザを削除したなら、そのユーザを手動でサスペンドもしなければなりません。そうしなければ、そのユーザはアクセストークンあるいはSSHキーを使って引き続き認証を受けることができてしまいます。詳しい情� �についてはユーザのサスペンドとサスペンドの解除を参照してく� さい。

レスポンスメッセージについての要求

レスポンスメッセージは以下の要求を満たさなければなりません。

<Destination>要� はルートレスポンスドキュメントで指定されていなければならず、ACS URLに一致する必要があります。た� し、これはルートレスポンスドキュメントに署名がある� �合のみです。アサーションに署名がある� �合は無視されます。
<AudienceRestriction>要� の一部として、<Audience>要� は常に指定する必要があります。 It must match the EntityId for GitHub Enterprise Server. これは、https://ghe.corp.example.comというような、GitHub Enterprise ServerインスタンスへのURLです。
Each assertion in the response must be protected by a digital signature. これは、個々の<Assertion>要� に署名するか、<Response>要� を署名するかすることによって行います。
<Subject>要� の一部として<NameID>要� を指定する必要があります。任意の名前識別子の形式を使用できます。
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>

SAML認証

GitHub Enterprise Server は、認証ログの /var/log/github/auth.log で失敗した SAML 認証のエラーメッセージをログに記録します。 SAML レスポンス要件の詳細については、「レスポンスメッセージの要件」を参照してく� さい。

エラー:「別のユーザがすでにアカウントを所有しています」

ユーザが SAML 認証を使用して初めて GitHub Enterprise Server にサインインすると、GitHub Enterprise Server はインスタンスにユーザアカウントを作成し、SAML NameID をアカウントにマップします。

ユーザが再度サインインすると、GitHub Enterprise Server はアカウントの NameID マッピングを IdP のレスポンスと比較します。 IdP のレスポンスの NameID が、GitHub Enterprise Server がユーザに対して想定している NameID とマッチしなくなると、サインインは失敗します。ユーザには次のメッセージが表示されます。

別のユーザが既にアカウントを所有しています。管理者に認証ログを確認するようご依� �く� さい。

このメッセージは通常、その人のユーザ名またはメールアドレスが IdP で変更されたということを示します。 Ensure that the NameID mapping for the user account on GitHub Enterprise Server matches the user's NameID on your IdP. 詳しい情� �については、「ユーザの SAML NameID の更新」を参照してく� さい。

SAMLレスポンスが署名されていなかった� �合、あるいは署名が内容とマッチしなかった� �合、authログに以下のエラーメッセージが残されます。

If the Recipient does not match the ACS URL for your GitHub Enterprise Server instance, one of the following two error messages will appear in the authentication log when a user attempts to authenticate.

Recipient in the SAML response must not be blank.

Recipient in the SAML response was not valid.

IdP の Recipient の値を、GitHub Enterprise Server インスタンスの完全な ACS URL に設定してく� さい。 For example, https://ghe.corp.example.com/saml/consume.

エラー:「SAML レスポンスが署名されていないか、変更されています」

IdP が SAML レスポンスに署名しない� �合、または署名が内容と一致しない� �合、次のエラーメッセージが認証ログに表示されます。

SAML Response is not signed or has been modified.

IdP で GitHub Enterprise Server アプリケーションの署名済みアサーションを設定していることを確認してく� さい。

エラー:「Audience が無効です」または「アサーションが見つかりません」

IdP のレスポンスに Audience の値がないか、または正しくない� �合、次のエラーメッセージが認証ログに表示されます。

Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL

IdP の Audience の値を、GitHub Enterprise Server インスタンスの EntityId に設定してく� さい。これは、GitHub Enterprise Server インスタンスへの完全な URL です。 For example, https://ghe.corp.example.com.