SSOとSAML

SSOとSAMLを通じてGitBookコンテンツを共有する方法を学びます

組織メンバーを手動で管理するのは、小規模なチームや高度な制御を求める人々には適していますが、より自動化された方法で開放したい場合もあります。GitBook では、基本的なメールドメイン SSO と、より複雑な SAML 統合という 2 つの方法でこれを設定できます。

メールドメインによるシングルサインオン

組織を作成または管理する際に、GitBook 組織へのアクセスを許可したいメールドメインの一覧を追加できます。これは、設定した SSO ドメインに一致する確認済みメールアドレスを持つすべてのユーザーが、組織に参加できるようになることを意味します。

メールドメイン SSO は、 SSO 組織の 設定のセクションで有効にできます。SSO アクセスを許可したいメールドメインのカンマ区切りリストを入力すれば設定完了です。

組織用に SSO を設定します。

SSO メールドメイン経由で参加したユーザーには、デフォルトでゲストアクセスが付与されます。役割は、組織設定のメンバーセクションでいつでも変更できます。

SAML ベースのシングルサインオン （SSO）は、任意のアイデンティティプロバイダー（IdP）を通じてメンバーに GitBook へのアクセスを提供します。

GitBook は既存のアイデンティティプロバイダー（IdP）と簡単に統合できるため、他のサービスプロバイダーと同じ認証情報およびログイン体験を使用して、従業員に GitBook へのシングルサインオンを提供できます。

SSO を使用すると、従業員は GitBook のログインページではなく、使い慣れたアイデンティティプロバイダーのインターフェースを使用して GitBook にログインできるようになります。その後、従業員のブラウザーが GitBook に転送します。SSO が有効で GitBook 独自のログイン機構が無効化されている場合、IdP が GitBook へのアクセスを許可します。このようにして、認証セキュリティは IdP 側に移され、他のサービスプロバイダーと連携されます。

GitBook での SSO の前提条件

• 会社のアイデンティティプロバイダー（IdP）は、 SAML 2.0 標準をサポートしている必要があります。

• IdP に対する管理者権限を持っている必要があります。

• SAML を設定したい GitBook 組織の管理者である必要があります。

GitBook での設定

GitBook 組織で SSO を有効にするには、 組織管理者 である必要があります。

IdP で SSO を設定した後、メタデータを入力できるようになります。設定が成功すると、管理者には確認ダイアログが表示され、エンドユーザー向けの SSO ログイン URL が表示されます。 設定完了時に GitBook は通知メールを送信しません。会社の従業員に通知し（ログイン URL を伝えることも含めて）、SSO 経由で GitBook にアクセスできるようにするのは管理者の責任です。

組織管理者は引き続き SSO 以外の方法でサインインできるため、Google、GitHub、またはメールのボタンが表示される場合があります。これは、 SSO を強制 が有効でも想定どおりの動作です。

これにより、SSO の設定不備によって組織から締め出されることを防ぎます。管理者は常にサインインして、SSO 設定を削除または修正できます。

SAML プロバイダーを登録するには、IdP メタデータから次の情報が必要です：

• 1つの label – これは任意の内容で構いません。ログインページに表示されます

• 1 つの エンティティ ID

• 1つの シングルサインオン URL

• 1 つの X.509 証明書 – 証明書全体を必ずコピー＆ペーストしてください。

IdP での設定

ほとんどの SAML 2.0 準拠のアイデンティティプロバイダーでは、設定のためにサービスプロバイダー（この場合は GitBook）に関する同じ情報が必要です。これらの値は GitBook 組織ごとに固有であり、SSO を有効にしたい GitBook 組織の 設定 -> SSO タブで確認できます。

これらの値のほとんどは、SAML の設定を完了するためにそのまま IdP にコピーできます。

GitBook では、 NameID にユーザーのメールアドレスが含まれている必要があります。技術的には、次を探しています： urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress これを Name-ID 形式として使用します。多くのプロバイダー（Google など）では、次のような形式を設定できます EMAIL.

カスタム属性

GitBook は SAML アサート応答から次のカスタム属性を取得し、ユーザー作成時に使用します。

フィールド	説明
first_name	first_name 、 last_name これらのフィールドは結合され、GitBook 上でのユーザーの表示名が生成されます
last_name	first_name 、 last_name これらのフィールドは結合され、GitBook 上でのユーザーの表示名が生成されます

エンドユーザーアカウントの作成

メンバーを追加するには、IdP でそのユーザーのアカウントを作成します。新しいメンバーが初めて IdP 経由で GitBook にログインすると、自動 IdP プロビジョニングによって GitBook アカウントが作成されます。ユーザーは組織メンバーとして組織のリソースにアクセスできるようになります。

設定には小文字のメールアドレスが必要です。大文字小文字が混在したメールアドレスは使用しないでください。

アカウントの削除

IdP からメンバーを削除すると、ユーザーは対応する GitBook アカウントにサインインできなくなりますが、 アカウント自体は GitBook から削除されません。GitBook 組織からもそのアカウントを削除することをお勧めします。

アクセス制御

SAML SSO を設定すると、誰が GitBook アカウントにアクセスできるかを制御する責任は IdP 側にあります。

セキュリティに関する注意

Identity Provider から取得したものと同じメールアドレスで既存の GitBook アカウントがあり、かつサインインしようとしている組織のメンバーでない場合、セキュリティ上の理由により、SAML 設定ではその組織に自動的に追加することはできません。選択肢は 2 つあります：

1. 既存の GitBook アカウントを削除してから、SAML を使用して目的の組織にログインしてください。すると GitBook が新しいアカウントを作成し、組織に追加します

2. または、管理者に組織へ招待してもらってください：

組織で「SSO を強制」が有効になっていない場合、組織の管理者は組織設定の Members ページからユーザーを招待できます。

組織で「SSO を強制」が有効になっている場合、管理者は GitBook の 招待 API エンドポイントを使用してユーザーを組織に招待する必要があります。この API の呼び出しは次のようになります。

curl --request POST --header "Authorization: Bearer <your_access_token>" --url "https://api.gitbook.com/v1/orgs/<org_id>/invites" --header 'Content-Type: application/json' --data-raw '{ "sso": true, "role": "<role>", "emails":["<email>"] }'