SSO & SAML

SSO & SAML を通じて GitBook コンテンツを共有する方法

小規模なチームや、きめ細かな管理を望む人にとっては、組織メンバーを手動で管理する方法で問題ありませんが、場合によっては、より自動化された方法でアクセスを開放したいこともあります。GitBook では、基本的なメールドメイン SSO と、より複雑な SAML 統合という 2 つの方法でこれを設定できます。

メールドメイン経由のシングルサインオン

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

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

組織の SSO を設定します。

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

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

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

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

​GitBook で SSO を利用するための前提条件

• 会社の ID プロバイダー（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つ目は ラベル – これは任意の値で構いません。ログインページに表示されます

• 1 つの エンティティ ID

• 1つ目は シングルサインオン URL

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

​IdP での設定

ほとんどの SAML 2.0 準拠 ID プロバイダーでは、設定にあたってサービスプロバイダー（この場合は GitBook）に関する同じ情報が必要です。これらの値は GitBook 組織ごとに固有であり、SSO を有効にしたい GitBook 組織の Settings -> 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>"] }'