# SSOとSAML

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

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

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

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

<figure><img src="https://4217681718-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FF860Y1oqJmnsPKOjZ1n2%2Faccount-settings-sso.svg?alt=media&#x26;token=c63d515a-a261-4f6e-b3aa-c39f3d03f0b4" alt="A GitBook screenshot showing how to configure SSO"><figcaption><p>組織用に SSO を設定します。</p></figcaption></figure>

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

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

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

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

## GitBook での SSO の前提条件 <a href="#prerequisites-for-sso-with-gitbook" id="prerequisites-for-sso-with-gitbook"></a>

* 会社のアイデンティティプロバイダー（IdP）は、 **SAML 2.0** 標準をサポートしている必要があります。
* IdP に対する管理者権限を持っている必要があります。
* SAML を設定したい GitBook 組織の管理者である必要があります。

### GitBook での設定 <a href="#setup-on-gitbook" id="setup-on-gitbook"></a>

GitBook 組織で SSO を有効にするには、 [組織管理者](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/member-management/roles#admin) である必要があります。

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

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

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

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

* 1つの **label** – これは任意の内容で構いません。ログインページに表示されます
* 1 つの **エンティティ ID**
* 1つの **シングルサインオン URL**
* 1 つの **X.509 証明書** – 証明書全体を必ずコピー＆ペーストしてください。

### IdP での設定 <a href="#setup-on-the-idp" id="setup-on-the-idp"></a>

ほとんどの 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 上でのユーザーの表示名が生成されます |

## エンドユーザーアカウントの作成 <a href="#creating-end-user-account" id="creating-end-user-account"></a>

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

{% hint style="danger" %}
設定には小文字のメールアドレスが必要です。大文字小文字が混在したメールアドレスは使用しないでください。
{% endhint %}

## アカウントの削除 <a href="#removing-end-user-accounts" id="removing-end-user-accounts"></a>

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

## アクセス制御

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

## セキュリティに関する注意 <a href="#security-notice" id="security-notice"></a>

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>"] }'
```