概要
Yellowfin 9.5では、シングルサインオン（SSO）セッションの開始時に、JWTトークンを使用できるオプションを導入しました。
YellowfinはJWTトークンを受け入れ、その内容を使用して新しいセッションをプロビジョニングします。JWTトークンの内容、またはグローバル構成を使用して、以下を指定することができます。
- ログインするユーザーID
- ユーザーのロール
- プロビジョニングのためのユーザーの姓名
- プロビジョニングのためのユーザーの電子メールアドレス
- ユーザーのデフォルトダッシュボード
- Yellowfinログイン後のランディングページ
ユーザーが存在しない場合は、JWTエントリーポイントを使用してユーザーをプロビジョニングすることもできます。
JWTシングルサインオンの有効化
JWT SSOは、Yellowfinのシステム構成ページで有効化します。
- レフトサイドナビゲーションから、管理＞システム構成を選択します。
- 認証をクリックして、認証方法項目を展開します。
- JWTシングルサインオンのトグルを有効にします。
新しくJWT設定項目が表示されます。こちらから、JWT SSOに関連するすべての設定を行います。
- JWT設定項目を展開します。各オプションの詳細は、以下の表に示します。
JWT SSO データベースオプションの設定
YellowfinのJWT設定項目には、JWT SSOを実装するための様々な設定が含まれており、最大限の柔軟性を提供します。次の表および手順に示すように、必要最小限の情報を含めるか、必要に応じてトークンをカスタマイズし、追加の詳細情報を含めるかを選択できます。
JWT設定項目を展開します。各オプションの詳細は、以下の表に示します。
| パラメーター名 | パラメーターの説明 | 必須項目かどうか | デフォルト設定 |
| JWTトークンの配信方法 | JWTトークンの配信方法を、URLパラメーター、またはCookieから選択します。 Cookieを選択した場合、JWTトークンは、JWT Cookie名項目のCookie名から取得されます。 | No | URLパラメーター |
| JWT Cookie名 | この項目は、JWTトークンの配信方法で、Cookieを選択すると表示されます。このパラメーターは、使用されるCookie名を定義します。 | No | なし |
| JWT検証キー | JWTトークンの署名を検証するための検証キーを入力します。これはプレーンテキストです。バイナリキーは、Base 64でエンコードすることで渡すことができます。この場合、バイナリ検証キー項目はプレーンテキストに設定する必要があります。 これを使用する場合は、検証キーを入力した後でパスワードを更新ボタンをクリックしてください。 | Yes | なし |
| バイナリ検証キー | デフォルトでは、このパラメーターはプレーンテキストに設定されています。セキュリティを強化するには、Base64エンコードを選択します。 | No | プレーンテキスト |
| JWTの署名アルゴリズム | デフォルトでは、HMAC256に設定されています。その他のオプションは以下の通りです HMAC512 , RSA256, RSA384, RSA512, ECD256, ECD384, ECD512 | No | HMAC256 |
| JWT発行者 | このパラメーターは、JWTトークン内の発行者属性を検証します。これを設定した場合、この項目の値は、JWTトークンの発行者項目と比較され、一致しない場合は、トークン検証が失敗します。 | No | なし |
| JWT User Id Attribute | このパラメーターは、Yellowfin UserIdを提供します。 | Yes | なし |
| JWTクライアント参照ID Attribute | このパラメーターは、ユーザーが属するクライアント組織のクライアント参照IDの場所を提供します。通常、関連するクライアント組織を持たないYellowfin インスタンスの場合は、「1」に設定されます。 | No | なし |
| SSOエントリーオプション | このパラメータは、JWT SSOプロセスで作成されたセッションに渡されるコンマ区切りのWebサービスセッションパラメータ値を保持するJWT属性を取ります。 より詳細な情報は、カスタムパラメーターおよびパラメーターを使用したデータのカスタマイズ項目を参照してください。 | No | なし |
| SSOカスタムセッション変数Attribute | このパラメーターを使用すると、SSO web サービス呼び出しのパラメーターをオプションを介して渡すことができるオプションを、JWT SSOプロセスにより作成されたセッションに渡すことができます。 これは属性ベースなので、個別のユーザーに適用できます。 より詳細な情報は、カスタムパラメーターおよびパラメーターを使用したデータのカスタマイズ項目を参照してください。 | No | なし |
| JWTオンボーディング | このトグルを有効にすると、新規ユーザーが存在しない場合に、最初のログイン試行時にそのユーザーをプロビジョニングできます。 | No | Off |
JWTオンボーディングのデータベースオプション
JWTオンボーディングトグルを有効にした場合、新規ユーザーを最初のログイン試行時に自動的にプロビジョニングすることができます。
| パラメーター名 | パラメーターの説明 | 必須項目かどうか | デフォルト設定 |
| First Name Attribute | このパラメーターは、新規ユーザーの名を取得するためのJWT属性の名前を定義します。 新規ユーザーの最初のログイン試行時に自動的にプロビジョニングをするには、これをFirstに設定します。 | Yes | なし |
| Surname Attribute | このパラメーターは、新規ユーザーの姓を取得するためのJWT属性の名前を定義します。 新規ユーザーの最初のログイン試行時に自動的にプロビジョニングをするには、これをLastに設定します。 | Yes | なし |
| Email Attribute | このパラメーターは、新規ユーザーの電子メールアドレスを取得するためのJWT属性の名前を定義します。これは、Yellowfinログイン時に、ユーザー名として使用されます。 新規ユーザーの最初のログイン試行時に自動的にプロビジョニングをするには、これをUserIdに設定します。 | Yes | なし |
| Language Attribute | このパラメーターは、新規ユーザーの言語コードを取得するためのJWT属性の名前を定義します。 | No | システムのデフォルト |
| Password Attribute | このパラメーターは、新規ユーザーのパスワードを取得するためのJWT属性の名前を定義します。 | No | ランダムのパスワード（32の英数字文字列） |
| Role Attribute | このパラメーターは、新規ユーザーのロールを取得するためのJWT属性の名前を定義します。これを省略した場合は、新規ユーザーにデフォルトのロールが割り当てられます。 | No | デフォルトに設定してあるロール（詳細は、こちらを参照してください） |
| 予備のロール | このドロップダウンリストでは、Role Attribute項目に入力したロールが、新規ユーザーのプロビジョニングに使用できない場合の予備のロールを選択できます。 | No | デフォルトに設定してあるロール（詳細は、こちらを参照してください） |
Yellowfinで使用するJWTトークンの作成
JWTトークンの作成は、サードパーティ製ソフトウェアを介して行われるため、次の手順は、前述のオプションを独自のJWTトークンに統合する方法の例を紹介しています。これらの手順は、基本的なガイドとしてのみご利用ください。
既存のYellowfin ユーザーのためのJWTトークンを作成
- お好みのJWT トークンクリエイターへ移動します（今回の例では、 https://jwt.io/を使用しています）
- 最低限として、右側のPayload項目にユーザー名を追加します。
これは、YellowfinのJWT User Id Attribute項目に追加した内容と一致しなくてはいけません。
- JWT検証キー項目で検証キーを使用している場合は、右下のsignature項目内のテキスト項目に同じキーを入力します。
参考として、左側のカラーコーディングは、JWTトークンがどのように作成されるかを示しています。 - 左側のエンコードされたトークンをコピーします。
- Yellowfin URLの最後に、JWTトークンログインおよびクエリー文字列を追加します。
JWTLogin.i4?jwtToken= - クエリー文字列の最後に、エンコードされたトークンを貼り付けます。
JWT payloadで指定したユーザーが、自動的にログインします。
新規Yellowfin ユーザーのためにJWTトークンを作成
- お好みのJWT トークンクリエイターへ移動します（今回の例では、 https://jwt.io/を使用しています）
- 最低限として、右側のPayload項目にユーザー名、姓、名を追加します。
これは、それぞれ対応するYellowfinの項目に追加した内容と一致しなくてはいけません。
- JWT検証キー項目で検証キーを使用している場合は、右下のsignature項目内のテキスト項目に同じキーを入力します。
参考として、左側のカラーコーディングは、JWTトークンがどのように作成されるかを示しています。 - 左側のエンコードされたトークンをコピーします。
- Yellowfin URLの最後に、JWTトークンログインおよびクエリー文字列を追加します。
JWTLogin.i4?jwtToken= - クエリー文字列の最後に、エンコードされたトークンを貼り付けます。
JWT payloadで指定した新規ユーザーが、自動的にログインします。クライアント組織が複数設定されている場合は、所属する組織を選択するように促されます。
JWTトークンを含むCookieの作成
セキュリティを強化するために、JWTトークンをCookieに格納するオプションもあります。これにより、クロスサイトリクエストフォージェリのリスクをさらに軽減することができます。
- JWT設定項目を展開し、JWTトークンの配信方法でCookieを選択します。
新しい項目として、JWT Cookie名が表示されます。 - JWT Cookie名項目に、Cookie名を入力します。
- ブラウザで開発者ツールコンソールを開き、ツールを使用して既存のCookieを表示します。
- ブラウザの開発者ツールを使用して、新しいCookieを追加します。以下を確認してください。
・YellowfinのJWT Cookie名項目と名前が一致していること
・トークン作成に使用したツールからエンコードされたJWTトークンをコピーし、新しいCookieの値カラム（列）に貼り付けます。
- Yellowfinのインスタンスにアクセスするために、JWT ログインURLを入力します（例： http://localhost:8080/JWTLogin.i4）
カスタムパラメーターおよびパラメーターを使用したデータのカスタマイズ
SSO web サービスの呼び出しで、カスタムパラメーターおよびパラメーターオプションを既に利用している場合は、SSOエントリーオプションおよびSSOカスタムセッション変数Attribute項目を使用して、これらをJWTトークンに追加することもできます。
SSOエントリーオプション属性
SSOエントリーオプション属性を使用することで、SSO web サービスのカスタムパラメーターオプションを介して渡すことができるユーザーごとのカスタムデータを、JWT SSOプロセスにより作成されたセッションに渡すことができます。これは属性ベースではないため、すべてのユーザーに適用されます。
SSOエントリーオプションの属性フィールドでは、JWTシングルサインオンを使用する際に、カスタムセッション変数をセッションごとに設定することができます。この属性には、JWT SSOプロセスで作成されたセッションに適用されるWebサービスのSSOセッションオプションを含めることができます。
例えば、ログイン時にすべてのユーザーがお気に入りに登録したレポートやダッシュボード、ストーリーなどを表示できるようにする場合は、TIMELINEおよびDISABLEHEADERパラメーター（または、ログインセッションオプションの定義に記載されているその他のパラメーター）を使用できます。以下の例では、これらを使用します。
- YellowfinのJWT設定を展開し、SSOエントリーオプション属性項目を表示します。
- 使用するパラメーターをカンマ区切りで入力します。
JWT属性の名前を入力します。
- 設定を保存し、変更内容を保存します。
JWTトークンを使用してログインし、指定したログインオプションが表示されることを確認することで、変更が機能していることをテストできます。
SSOカスタムセッション変数Attribute
SSOカスタムセッション変数Attribute項目を使用することで、SSO web サービス呼び出しのパラメーターをオプションを介して渡すことができるオプションを、JWT SSOプロセスにより作成されたセッションに渡すことができます。これは属性ベースなので、個別のユーザーに適用できます。
この項目を使用するためには、独自のJavaプラグインを記述しなくてはいけません。Yellowfin セッションには任意の数の変数を渡すことができるため、カスタム要件に対して柔軟性を高めることができます。
例えば、一般的なYellowfinヘッダーを置き換えるカスタムヘッダーを実装する場合は、この項目にヘッダーの情報を抽出してページの上部に表示できるJSON配列を配置できます。これには、ユーザーのロールやプロフィール写真、作業した最新の3つのレポートへのリンクなど、ユーザー固有の詳細情報も含めることもできます。
Yellowfinでの唯一の要件は、SSOカスタムセッション変数Attribute項目に、これらの詳細を追加することです。