Strategy One

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. 保存をクリックしてください。

    初回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 設定ダイアログを開き、再度保存し、プロンプトが表示されたらLibrary serverを再起動してください。

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

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

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

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

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

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