Ltoken を使用した認証

リリース 2024.3 以降、安全なトークンは「credentials」ファイルに保存されますが、安全でないトークンや --insecure フラグが設定されている場合は引き続き既存の「ltoken」ファイルが使用されます。安全な認証トークンを参照してください。
リリース 2024.2 では、ltoken はコマンドラインツールにサインインするためのアプリケーショントークンに置き換えられました。リリース 2024.2 より前のスクリプトで ltokens を使用していた場合は、ltoken からアプリケーショントークンへの移行を参照してください。

認証トークンは kwauth と Klocwork クライアントアプリケーションによって、ユーザーのホームディレクトリ内の特別なファイルに保存されています。このトークンを使用してユーザーを認証し、kwbuildproject、kwcheck、Web API などのツールをユーザーが使用できるようにします。このファイルは次の場所にあります。

  • Windows: C:\ユーザー\<user_name>\.klocwork\credentials (安全なトークンの場合) または C:\ユーザー\<user_name>\.klocwork\ltoken (ltoken の場合)
  • Unix: ~/.klocwork/credentials (安全なトークンの場合) または ~/.klocwork/ltoken (ltoken の場合)

.klocwork ディレクトリに「credentials」ファイルまたは「ltoken」ファイルがない場合は、kwauth を実行して生成することができます。

安全な認証トークン

安全な認証トークンは、kwauth の実行時に生成される「credentials」ファイルに保存されます。バージョン 2024.3 以降では、--insecure フラグが使用されない限り、デフォルトで「credentials」ファイルが作成されます。--insecure フラグが使用されている場合は、「ltoken」ファイルが生成されます。

最初に「credentials」ファイルからのロードが優先され、次に「ltoken」のロードが試行されます。「credentials」ファイルが存在しない場合は、旧バージョンの安全なトークンが引き続き機能し、安全でないトークンを使用する古いツールとの下位互換性がそのまま維持されます。

Validate 2024.3 では、次の機能強化が行われました。

  • 資格情報の保存方法は、以下のようにして VALIDATE_SECURE_TOKEN_STORAGE 環境変数を使用して指定することができます。

    VALIDATE_SECURE_TOKEN_STORAGE 環境変数を設定しない場合は、JAVA_SECRET_STORAGE が使用されます。

    • JAVA_SECRET_STORAGE (新しいトークンのデフォルト): Java KeyStore による安全なストレージを使用して資格情報を保存します。デフォルトでは、安全な Java ストレージファイルは user/.klocwork/tokens.jks にあります。VALIDATE_TOKEN_KEYSTORE_FILE 環境変数を設定することにより、tokens.jks ファイルの場所を変更することができます。

    • OS_NATIVE: OS に依存する安全なストレージ (Windows の場合は Windows Credential Manager、Linux の場合は libsecret) を使用して、新しい資格情報を保存します。

    • DISABLED: 安全でないストレージを使用して、新しい資格情報を .ltoken ファイル内にプレーンテキストで保存します。2024.1 以前の Klocwork ツールを 2024.2 以降の Validate サーバーで使用している場合は、安全でないトークンストレージを使用する必要があります。

  • 安全なアプリケーショントークンの追加には、以下の新しい環境変数も含まれます。

    • VALIDATE_TOKEN_KEYSTORE_FILE (キーストアの場所)

    • VALIDATE_CREDENTIALS (「credentials」ファイルの場所)

    • VALIDATE_LTOKEN (「ltoken」ファイルの場所)

      以前の KLOCWORK_LTOKEN 環境変数は引き続き機能しますが、KLOCWORK_LTOKEN と VALIDATE_LTOKEN の両方が設定されている場合は VALIDATE_LTOKEN が優先されます。

コマンドラインツールへのサインインに使用する ltoken からアプリケーショントークンへの移行

2024.1 以前の Klocwork ツールを 2024.2 以降の Validate サーバーで使用している場合は、安全でないトークンストレージを使用する必要があります。安全でないストレージを認証コマンドで使用するには、VALIDATE_SECURE_TOKEN_STORAGE 環境変数を DISABLED に設定します。

Validate 2024.1 以前では、Validate サーバーによる認証が成功すると、ltoken が作成され、プレーンテキストファイルに保存されていました。ltoken は、対話型認証ができない状況 (スクリプト環境や Web API クエリなど) で使用できます。

Validate 2024.2 では、次の機能強化が行われました。

  • kwauth はデフォルトで、OS 依存の安全なストレージ (Windows の場合は Windows Credential Manager、Linux の場合は libsecret) に資格情報を保存します。
  • 管理者とユーザーは、トークンを取り消すことができます
  • 対話型認証ができない場合は、アプリケーショントークンを使用できます

  • アプリケーショントークンを使用して認証できますが、トークンは安全なストレージには保存されません。

Validate サーバーを移行した後も、以前に認証された ltoken (セッション) は引き続き機能します。

ある認証方法から別の認証方法に切り替えると (たとえば、基本から LDAP、または LDAP から OIDC)、既存の認証済み ltoken (セッション) は無効になります。ユーザーは再認証する必要があります。

ユーザーとロールの情報が失われないようにするには、認証方法を切り替える前に projects_root/permissions_data フォルダーをバックアップします。認証方法の切り替え中にユーザーとロールの情報が誤って削除された場合は、permissions_data (derby) データベースのバックアップから情報を復元することができます。
認証に ltoken を使用していたすべてのスクリプト環境は、アプリケーショントークンに切り替える必要があります。アプリケーショントークンを使用した認証を参照してください。

デフォルトの安全なトークンまたは ltoken の場所のオーバーライド

VALIDATE_CREDENTIALS または VALIDATE_LTOKEN 環境変数を設定することにより、安全なトークンと ltoken のそれぞれについてカスタムのファイルの場所を使用することができます。ファイルに保存するには、VALIDATE_CREDENTIALS または VALIDATE_LTOKEN を設定し、kwauth を使用して認証します。生成されたファイルは、デフォルトの場所ではなく、指定された場所に格納されます。

環境変数が設定されている場合、認証を必要とするツールは環境変数で指定されている場所を使います。設定されていない場合は、初期設定の場所を使います。

元のファイルは移動されたり、コピーされたりしないので、別のツールを使用できるようにするには、その前に kwauth によってユーザーを再認証する必要があります。

Linux での kwauth の実行例:
export VALIDATE_LTOKEN=/space/myltokenfile
kwauth
Login: jsmith
Password:
Windows での kwcheck の実行例:
set VALIDATE_CREDENTIALS=C:\space\mycredentialsfile
kwcheck run
...

環境変数を新しい値に設定した後に kwauth の再実行が必要になる場合があるので注意してください。再実行しない場合、ファイルが空になる可能性があります。

ホスト名が見つからない場合の認証の失敗

verifyCertificate オプションを true に設定することで、証明書の CN またはサブジェクトの別名でサーバーのホスト名が見つからなかった場合に、kwauth を認証に失敗させることができます。これを有効にすると、ホスト名が見つからない場合に次のエラーメッセージが表示されます。
<url> で SSL を使用した認証ができませんでした
この値を true に設定するには、{client_tools_install_folder}\config\ フォルダーに「client_config.xml」ファイルを作成します (まだ存在しない場合)。そのファイルには次が含まれている必要があります。
<?xml version="1.0" encoding="UTF-8"?>
   <params> 
     <host resolveHost="false" verifyCertificate="true"/>
   </params>

resolveHost="false" の設定は必須ではありませんが、サーバーはリモートサーバー URL で指定したホストを使用するので、Klocwork サーバーが間違った FQDN を解決するのを防ぐことができます。

Klocwork Web API で認証するには

アプリケーショントークンは、Web API での認証には使用できません。kwauth を使用して Validate サーバーに対して認証してから、kwauth --print-auth-info を使って ltoken を取得します。

Klocwork 2024.1 以前では、Klocwork Web API で認証するには、ltoken ファイルから ltoken をコピーしていました。

Klocwork 2024.2 以降では、kwauth を使用して Validate サーバーに対して認証を行ってから、kwauth --print-auth-info を使って ltoken を取得する必要があります。 Web API アクセス権を持つ管理者は、kwauth --print-auth-info を使って、指定されたサーバーの JSON 形式の認証トークンと、トークンの発行対象ユーザーを印刷します。これによって、Web API 要求に対してトークンを使用できるようになります。

kwauth のバージョン 2024.2 を、他のクライアントツールのバージョン 2024.1 以前とともに使用している場合、--insecure フラグを使用して kwauth を実行する必要があります。
正しい Validate サーバーで認証するためには、kwauth を実行する際に、必ず --url パラメーターを含めてください。

例 1: 安全な保管

Validate サーバーで認証する際に使用する ltoken を http://localhost:40000 で取得するには、次のコマンドを実行します。

kwauth --url http://localhost:40000 -i

次のような結果が返されます。

{"username":"Developer2","token":"dcd98fc056a91b1be44d367f076ce0ac9b51331ed7e62736edf3ec05189aa4a4"}

API 要求の書式にある説明に従って、Web API 認証にトークンを使用できます。

関連する概念