Strategy One

Library ServerでのJWT認証の設定

Strategy One（2025年11月）以降、Library serverでJWT認証を設定する際にセキュリティフィルターを作成できます。この追加により、設定されたクレームに従ってユーザーセキュリティフィルターを定義できます。

Strategy One（2025年9月）では、Library サーバーにJSON Web Token（JWT）認証のサポートが追加されました。署名されたJWTを使用してLibrary login APIを送信できます。その後、Library サーバーはこの情報を使用して有効なユーザーセッションを作成します。

前提条件

  • Library JWT 認証をカスタム ログイン ワークフローに統合してください。ワークフローは、ユーザー情報を含む署名されたJWTを生成し、Library login API リクエストを送信する必要があります。

  • 管理者アカウントには、以下のServer - Intelligence権限が必要です：

    • Configure server basic

    • Configure security settings

    • Configure governing

    • Administer environment

    • Use Workstation

JWT 認証の設定

  1. Workstation ウィンドウを開き、環境に接続してください。

  2. 環境を右クリックし、Configure Enterprise SecurityとConfigure JWTを選択してください。

  3. 1. General Settingsで、JWTのIssuerとAudienceを入力してください。

    これらの値は、受信JWTのissとaudプロパティと正確に一致する必要があります。 Strategyは、1つのiss / audペアの検証のみをサポートしています。

  4. 2. Key Configurationでは、受信JWTの検証に使用されるキーを指定します。Strategy は3つのキーソースをサポートしています：

    • Issuer：このオプションは、OpenID Provider Issuer Discovery プロセスを使用してjwksUriを決定します。 Strategy は、OpenIDプロバイダーメタデータから公開キーをリモートで取得します。このオプションには、多くの場合OpenIDプロバイダーからの発行者サポートが必要で、issは発行者のベースURLと一致する必要があります。

    • JWKS URI：このオプションでは、管理者がJWT 検証用のJWKSを取得するためにjwksUriを提供する必要があります。

    • Static Key：管理者がJWT認証用のキーとアルゴリズムを提供します。

      • Signature Algorithm：JWTヘッダーのalg。キー値の形式は選択されたアルゴリズムによって異なります。

      • 対称キー（HS256 / HS384 / HS512）：共有シークレットはUTF-8文字列である必要があります。長さの要件はアルゴリズムによって異なります：

        • HS256：32バイト以上

        • HS384：48バイト以上

        • HS512：64バイト以上

      • 非対称キー（RS、PS、ESで始まるアルゴリズム）は、base64エンコードされたPEM 形式の公開キーのみを受け入れます。これには、汎用PEM ヘッダー/フッター(-----BEGIN PUBLIC KEY-----\n ,,, \n-----END PUBLIC KEY-----)が含まれます。公開キーは指定されたアルゴリズムと一致し、セキュリティ要件を満たしている必要があります。独自の公開キーを使用するか、公開/秘密キーペアを生成してJWT 生成に秘密キーを使用できます。

      Strategyは、SPKI 形式のPEM ファイルのみをサポートしています。Public Key（PEM）に入力する前に、他の形式をSPKI PEMに変換してください。以下の形式は変換が必要です：

      • PKCS 形式のPEM ファイル（多くの場合-----BEGIN RSA PUBLIC KEY-----で始まる）

      • EC固有の形式（-----BEGIN EC PUBLIC KEY-----で始まる）

      • JKSなどの非PEM形式

  5. 3. User Claim Mappingで、JWT クレームをIntelligence serverユーザー属性として設定してください。

    User IDマッピングは必須です。これは、指定されたクレームを信頼できる認証IDにマップします。ネストされたクレームマッピングはサポートされていません。

  6. 4. System Promptで、ユーザーシステムプロンプトとJWT クレーム間のマッピングルールを設定してください。

    利用可能なSSOシステムプロンプトには、15のテキスト、15の数値、10の日付プロンプトが含まれます。ネストされたクレームマッピングはサポートされていません。

  7. Strategy One（2025年11月）以降、5. Security Filter Templateで、Projectの隣にあるAddをクリックしてください。

    1. Security Filter Templateダイアログが表示されます。

    2. New Qualificationをクリックしてください。

    3. 左ペインでオブジェクトを見つけてBased Onにドラッグアンドドロップするか、Based Onでオブジェクトを検索してください。

    4. Qualify Onドロップダウンリストを展開してフォームを選択してください。

    5. Operatorドロップダウンリストを展開してフィルターする演算子を選択してください。

    6. JWTクレームを追加するには、Valueの隣にあるClaimをクリックしてください。

      クレームはIdentity Provider（IDP）にも存在する必要があります。資格内のクレーム名がIDPに存在しない場合は、ステップkで説明されているように、資格のOmit if Unsetを有効にしてください。

    7. New Claimで、Name、Multi Value（利用可能な場合）、Delimiter（利用可能な場合）を入力してください。

    8. OKをクリックしてください。

    9. さらに資格を追加するには、ステップbからhを繰り返してください。

    10. 値が満たされていない場合に条件を適用するように設定するには、More OptionsをクリックしてNOTの隣のチェックボックスを選択してください。

    11. 設定されていない場合に条件を除外するには、More OptionsをクリックしてOmit if unsetの隣のチェックボックスを選択してください。

      資格にOmit if unsetが選択されている場合、パネルにはOPTIONALとして表示され、クレーム値が設定されていない場合は最終的なセキュリティフィルターから除外されます。

    12. 条件を削除するには、Deleteをクリックしてください。

    13. Saveをクリックしてください。

      JWT認証を完了すると、セキュリティフィルターテンプレートが選択されたプロジェクトの各ユーザーに追加されます。セキュリティフィルターの表示の詳細については、ユーザーのセキュリティ フィルターを管理を参照してください。

  9. 保存をクリックしてください。

    初回JWT設定を適用するために、WorkstationからLibrary serverの再起動を求められる場合があります。

JWT ログインの実行

ログインワークフローは、Workstation が公開キーまたは共有シークレットで検証できる署名されたJSON Web Tokenを生成する必要があります。JWTは以下の要件を満たす必要があります：

  • expクレームが存在する必要があります。 Strategyは、有効期限のないJWTをサポートしていません。

  • JWT には、User IDにマップされたクレームが含まれている必要があります。

JWT ログインにはLibrary authentication APIを使用してください。

コピー 
POST /api/auth/login

            {
            "loginMode": 67108864,
            "password": "<jwt string>",
            "maxSearch": 3,
            "workingSet": 10,
            "metadataLocale": "en_us",
            "warehouseDataLocale": "en_us",
            "displayLocale": "en_us",
            "messagesLocale": "en_us",
            "numberLocale": "en_us",
            "timeZone": "UTC",
            "applicationType": 35
            }

リクエストJSON ペイロードのほとんどのプロパティは、以下を除いて他のログインモードと同じです：

  • loginMode：67108864に設定

  • username：必須ではありません。このプロパティは定義しないでください。

  • password：JWT文字列をこのフィールドに割り当ててください。

正しいJWTを提供すると、WebセッションとレスポンスヘッダーのX-MSTR-AuthTokenでログインが成功します。

トラブルシューティング

JWT認証の失敗

JWT認証は、設定ミスや生成されたJWTとの不一致により失敗する場合があります。トラブルシューティングには以下のチェックリストを使用してください：

  • JWT認証モードが有効になっているか、信頼関係が設定されているかを確認してください。解決するには、JWT設定ダイアログを開き、再度保存し、プロンプトが表示されたらLibrary serverを再起動してください。

  • JWTツールを使用して生成されたJWTを調べ、正しいことを確認してください。以下を確認してください：

    • JWT署名とalgは、Workstation設定と一致する必要があります。

    • issとaudの値は、Workstation設定と一致する必要があります。

    • expは将来の時刻である必要があります。Library serverがこの値を評価するため、Library serverマシンの時刻が正しいか、APIクライアントの時刻と同期されていることを確認してください。

    • User IDのマップされたクレームが存在することを確認してください。他の属性とシステムプロンプトのクレームが存在することを確認してください。

  • サーバー側エラーについてはLibraryログを確認してください。

JWTセキュリティフィルター認証の失敗

JWTペイロードからの情報の欠落や不正なセキュリティフィルター設定により、JWT認証が失敗する可能性があります。セキュリティフィルターの設定時にエラーが発生した場合は、次のチェックリストを使用してトラブルシューティングを行ってください：

  • セキュリティフィルターテンプレートで使用される各クレームについて、JWTログインに含まれているか、関連するフィルター述語がOPTIONALに設定されていることを確認してください。

  • セキュリティフィルター述語で使用される属性フォームには、さまざまなデータ型があります。JWTクレームと比較する場合、クレーム値が属性フォームタイプと一致することを確認してください。

  • JWT認証エラーについてはLibraryログを確認してください。