Single Sign On セットアップマニュアル

投稿日 / 更新日 / 投稿者名

2020.1.9 / 2021.4.4 / 高橋 桃花

はじめに

本レポートは、Things Cloud の利用例をより知っていただくための実利用レポートとして作成したものです。
Things Cloud は極力後方互換性を持つよう開発されていますが、今後のリリースにより、一部画面やコマンド、手順などが変更となったり、利用できない可能性があることをあらかじめご了承ください。
なお、作成にあたり、以下バージョンを用いています。

1. Things Cloud における Single Sign On 機能

機能概要

本機能では、OAuth2.0 プロトコルをサポートしているサードパーティの認可サーバを使用した Things Cloud への Single Sign On(SSO)機能を提供します。代表的な認可サーバとして Microsoft 社が提供する Azure Active Directory(Azure AD)に対応しており、その他にも条件を満たした認可サーバであれば Things Cloud での SSO に対応しています。以下が本機能の特徴です。

表題 内容 備考
2. SSO 機能の利用において SSO 機能を利用する際の利用条件と制約・注意点について説明します。 SSO 設定画面を操作するためには admins 権限である必要があります。
3. Azure AD を用いて SSO 機能を利用する場合 Azure AD の設定と Things Cloud における SSO 設定を実施します。 Azure AD アカウントを所持している必要があります。
4. 任意の認可サーバを用いて SSO 機能を利用する場合 任意の認可サーバの設定と Things Cloud における SSO 設定を実施します。本文書では、任意の認可サーバとして Keycloak を使用し設定例を示します。 2. で示した条件を満たす認可サーバ・対象の認可サーバのアカウントを用意する必要があります。
5. SSO の実施 設定した内容に基づいて SSO 機能を利用してテナントにログインします。
6. トラブルシューティング うまく機能が動作しない場合の対処法や、エラー発生時の対処法について説明します。

2. SSO 機能の利用において

SSO 機能の利用条件

以下が Things Cloud での SSO 機能を利用する際の条件です。

制約・注意点

以下が SSO 機能を利用する上での制約・注意点です。

本文書に含まれる内容は以下のとおりです。併せて ユーザーガイド > 管理 > 設定の変更 もご覧ください。

3. Azure AD を用いて SSO 機能を利用する場合

本章では、Azure AD を用いて SSO 機能を利用する場合に必要な Azure AD の設定、Things Cloud の SSO 設定方法について説明します。

本マニュアルは 2020 年 1 月 9 日時点の情報を元に作成しています。最新の正確な情報は Azure AD 公式のウェブサイト をご覧ください。

3.1 Azure AD の設定

Azure AD で必要な設定は以下の通りです。

3.1.1 Azure AD テナントへのアプリケーション登録

Azure Portal へログインし、「Azure Active Directory」へアクセスします。左メニューから「アプリの登録」をクリックし、アプリケーションを新規登録します。

oauth_1

oauth-2

アプリケーション登録時に、以下の項目を設定し、「登録」をクリックします。

入力項目 内容 備考
名前 任意のアプリケーションの名前を入力
サポートされているアカウントの種類 「この組織ディレクトリのみに含まれるアカウント」を選択 Things Cloud でサポートしている Microsoft ID プラットフォームのエンドポイントは v1.0 です。v1.0 に対応するシングルテナントを選択してください。
リダイレクト URI https://{テナント名}.je1.thingscloud.ntt.com/tenant/oauth を入力 テナント名にはご自身の使用しているテナントの名前を入力してください。
3.1.2 アプリケーションのセットアップ

アプリケーション登録後、クライアントシークレットを作成します。左メニューの「証明書とシークレット」をクリックします。

oauth_3

「新しいクライアントシークレット」をクリックし、任意の説明と有効期限を設定して「追加」をクリックするとクライアントシークレットが発行されます。このクライアントシークレットは後ほど Things Cloud の SSO 設定画面で入力する必要があるので控えておいてください。

oauth_4

oauth_5

Azure AD で必要な設定は以上です。

3.2 Things Cloud での SSO 設定

Things Cloud の SSO 設定画面には、2 つの設定用テンプレートが用意されています。一方は Azure AD、もう一方はカスタム(任意の認可サーバ向け)です。ここでは、Azure AD テンプレートの設定例について説明します。

SSO 設定画面を操作するには、「テナント管理」の「読み取り」と「管理者」にチェックが入っている admins 権限のユーザーである必要があります。

Azure AD テンプレートの選択

まず、「管理」アプリ>「設定」>「認証」>「シングルサインオン」から SSO 設定画面へ移動し、テンプレートで「Azure AD」を選択します。

oauth_11

3.2.1 基本

SSO 機能に必要な基本事項を設定します。Azure AD テナントに作成したアプリケーションの画面から必要な値を取得してください。

入力項目 内容 備考
Azure AD のアドレス https://login.microsoftonline.com
テナント ディレクトリ(テナント)ID の値 Azure AD に登録したアプリケーションの「概要」から取得します。
アプリケーション ID アプリケーション(クライアント)ID の値 Azure AD に登録したアプリケーションの「概要」から取得します。
リダイレクト URI 埋め込み済みのため入力の必要は無し
クライアントシークレット Azure AD に登録したアプリケーションの「証明書とシークレット」>「クライアントシークレット」で作成した値 Azure AD に登録したアプリケーションから取得します。
ボタン名 ログイン時に表示されるテキスト 任意のテキストを設定可能です。
トークン発行者 https://sts.windows.net/{テナント}/ {テナント}はディレクトリ(テナント)ID の値
ログインページに表示 チェックを入れる
3.2.2 アクセスマッピング

アクセストークン(JWT)のクレームの内容に応じて、Things Cloud にログインする際のグローバルロールを設定できます。ここでは、upn というフィールドが「azuread-user@somedomain.com」である場合、admins 権限を付与するという設定をしています。より詳細な情報は シングルサインオン(SSO)の構成設定 をご覧ください。

oauth_12

3.2.3 ユーザー ID

Things Cloud にログインした際に使用されるユーザー ID です。JWT のクレームのいずれか、もしくは任意の文字列を指定できます。ここでは、upn を使用します。

3.2.4 署名の確認

アクセストークン検証に使用される公開鍵検出 URL を設定します。形式は以下のとおりです。テナントには Azure AD テナントに登録したアプリケーションの「ディレクトリ(テナント)ID の値」を設定します。

Azure AD を用いて SSO 機能を利用する場合の設定は以上です。

4. 任意の認可サーバを用いて SSO 機能を利用する場合

本章では、任意の認可サーバを用いて SSO 機能を利用する場合に必要な認可サーバの設定、Things Cloud の SSO 設定方法について説明します。本文書では、認可サーバとして Keycloak を例に挙げ設定例を説明します。

4.1 Keycloak の設定

Keycloak で必要な設定は以下のとおりです。

4.1.1 Realm の作成

管理者ユーザーで Keycloak にアクセスし、新しい Realm を作成します。左上の「Master」にカーソルを合わせると「Add realm」というボタンが表示されるためクリックし、必要事項を設定し保存します。

oauth_6

4.1.2 新しく作成した Realm に所属するユーザーの作成

「Users」から「Add user」をクリックし新しくユーザーを作成します。ここで作成するユーザーで Things Cloud にログインすることになります。

oauth_7

4.1.3 クライアントの登録

「Clients」から「Create」をクリックし新しいクライアントを登録します。

oauth_8

以下の項目を設定します。

入力項目 内容 備考
Client ID 任意の Client ID
Client Protocol openid-connect
Access Type confidential Client secret を発行するために 「confidential」を選択します。
Standard Flow Enabled ON
Valid Redirect URIs https://{テナント名}.je1.thingscloud.ntt.com/tenant/oauth テナント名にはご自身の使用しているテナントの名前を入力してください。

oauth_9

「Clients」の「Credentials」から Client secret を控えておきます。

oauth_10

Keycloak で必要な設定項目は以上です。

カスタムテンプレート

次に、カスタムテンプレート使用時の設定例について説明します。本文書では、連携する認可サーバの例として Keycloak を用います。「管理」アプリ>「設定」>「認証」>「シングルサインオン」から SSO 設定画面へ移動し、テンプレートで「カスタム」を選択します。

oauth_13

4.2.1 認証のリクエスト

oauth_14

Keycloak の認可エンドポイントと、リクエストパラメーターを設定します。response_type に code、client_id に ${clientId} を指定します。

4.2.2 トークンリクエスト

oauth_15

Keycloak のトークンエンドポイントを設定します。「本文」の末尾に 4.1.3 クライアントの登録 で控えていたクライアントシークレットを追加し、以下の内容を設定します。

4.2.3 リクエストを更新

oauth_16

リフレッシュトークン発行のための設定をここで行います。URL には Keycloak のトークンエンドポイントを登録し、「本文」の末尾にクライアントシークレットを追加します。「本文」の内容は以下のとおりです。

4.2.4 基本

SSO 機能に必要な基本事項を設定します。Keycloak で登録したクライアントの情報を適宜参照してください。

oauth_17

4.2.5 アクセスマッピング

oauth_18

アクセスマッピングとユーザー ID の設定をします。ここでは、preferred_username が keycloak-user の場合、business 権限を付与します。また、ユーザー ID には定数値を指定しています。

4.2.6 署名の確認

「検証」のタブから「カスタム」を選択し、以下の項目を入力します。ここでは JWT の署名検証用に複数枚の証明書を登録できます。これにより、いずれかの証明書が期限切れになった場合でもその他に有効な証明書が登録されていることでユーザがログインできなくなることを防ぎます。

参考: 証明書 ID を入力すると「証明書を追加」のボタンが表示され、複数証明書を登録できるようになります。 oauth_20

oauth_19

入力項目 内容
証明書 IDフィールド 証明書が複数枚存在する場合は、証明書ごとに異なる値を持つ任意の JWT クレーム
を入力してください(例えば kid など)。証明書が一枚の場合は入力不要です。
証明書IDの値 証明書が複数枚存在する場合は、証明書 ID で指定した JWT クレームの
値を入力してください。証明書が一枚の場合は入力不要です。
タイプ 認可サーバが採用している形式に応じて選択してください。ここでは RSA public key を選択します。
PEM形式のパブリックキー 認可サーバの公開鍵情報を入力します。
有効期限 有効期限を入力します。

任意の認可サーバを用いて SSO 機能を利用する場合の設定は以上です。

5. SSO の実施

前述のステップで設定した内容で正しく SSO が機能するかを確認します。ここでは、Azure AD を利用した場合の SSO を実施します。一度現在のユーザーからログアウトし、ログアウト時の画面に SSO 用のボタンが表示されていることを確認します。

oauth_20

「 Login with Azure AD」と表示されているボタンを押すと、認証情報入力画面にリダイレクトされるため、自身の Azure AD アカウントの情報を入力してください。

oauth_21

Azure AD アカウントの認証に成功すると、Things Cloud にリダイレクトされ、ログインした状態になっています。

oauth_22

以上で SSO 機能のセットアップは完了です。

6. トラブルシューティング

以降では、エラー発生時のトラブルシューティングについて説明します。

Azure AD テンプレートを利用する場合

カスタムテンプレートを利用する場合