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

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

2020.1.9 / 2021.4.4 / 高橋桃花

はじめに

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

ver.10.5.0.16（backend/UI）

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

機能概要

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

SSO に必要な項目を設定できるテンプレートが用意されている（Azure AD 専用のテンプレート、カスタムテンプレートの 2 つ）
管理者は SSO ユーザーに条件に応じたグローバルロールを付与できる
認可サーバから発行され、ブラウザの Cookie に保存されるアクセストークンは JavaScript で取得できないため通常の Basic 認証に比べセキュア

表題	内容	備考
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 機能を利用する際の条件です。

Things Cloud と連携する認可サーバは OAuth2.0 の Authorization Code Grant フローをサポートしている
認可サーバが発行するアクセストークンの形式は JWT (Json Web Token) であり、“iss (issuer)"、“aud (audience)"、“exp (expiration time)” のフィールドを含んでいる

制約・注意点

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

SSO ユーザーには動的にインベントリロールを付与できない

SSO 設定画面からはインベントリロール付与の設定はできませんが、管理 > アカウント > ユーザーの画面からユーザー毎にインベントリロールを設定可能です。
SSO ユーザーは自身のグローバルロールを変更できない

SSO 設定画面で設定されているグローバルロールから異なるグローバルロールへの変更は自身では実施できません。
SSO 設定画面にアクセスするには、グローバルロールの「テナント管理」の「読み取り」と「管理者」にチェックが入っている admins 権限のユーザである必要があります。

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

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

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

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

3.1 Azure AD の設定

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 の値」を設定します。

https://login.microsoftonline.com/{テナント}/discovery/keys

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

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

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

4.1 Keycloak の設定

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

Realm の作成
新しく作成した Realm に所属するユーザーの作成
クライアントの登録

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 クライアントの登録で控えていたクライアントシークレットを追加し、以下の内容を設定します。

grant_type=authorization_code&code=${code}&redirect_uri=${redirectUri}&client_id=${clientId}&client_secret={自身のクライアントシークレット}

4.2.3 リクエストを更新

oauth_16

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

grant_type=refresh_token&refresh_token=${refreshToken}&client_id=${clientId}&client_secret={自身のクライアントシークレット}

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_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 テンプレートを利用する場合

Invalid issuer! というエラーが発生する場合

「トークン発行者」の設定内容に誤りがあります。エラー内容の「Issuer from token」の内容を参考に入力内容を修正してください。
Cannot load userId. Check JWT field in configuration and compare to corresponding token field. JWT field: XXX というエラーが発生する場合

「ユーザー ID」の「JWT フィールド」の設定内容に誤りがあります。エラー内容の「Token」を参考にし、適切な JWT クレームを指定してください。
Check discovery URL. というエラーが発生する場合

「署名の確認」の「公開鍵検出 URL」の設定内容に誤りがあります。3.2.4 署名の確認を参考にし、適切な公開鍵 URL を指定してください。

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

ログイン中に For security reasons you have been logged out, please log in again というエラーが発生する場合

「リクエストを更新」の設定内容に誤りがあります。3.2.2 リクエストを更新を参考にし、URLや本文、リクエストパラメーターの入力内容をご確認ください。
Invalid issuer! というエラーが発生する場合

「トークン発行者」の設定内容に誤りがあります。エラー内容の「Issuer from token」の欄を参考に入力内容を修正してください。
Invalid audience! というエラーが発生する場合

「基本」の「対象」の設定内容に誤りがあります。エラー内容の「Audience from token」の内容を参考に入力内容を修正してください。
Cannot load userId. Check JWT field in configuration and compare to corresponding token field. JWT field: XXX というエラーが発生する場合

「ユーザー ID」の「JWT フィールド」の設定内容に誤りがあります。エラー内容の「Token」を参考にし、適切な JWT クレームを指定してください。
com.cumulocity.authlib.exceptions.SingleSignOnConfigurationException: Wrong certificate というエラーが発生する場合

「署名の確認」の「公開鍵」の設定内容に誤りがあります。認可サーバの公開鍵情報を確認し、入力内容を修正してください。