ltoken を使って認証を行う

リリース 2024.2 では、ltokens はアプリケーショントークンに置き換えられています。リリース 2024.2 より前のスクリプトで ltokens を使用していた場合は、ltoken からアプリケーショントークンへの移行を参照してください。

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

  • Windows: C:\Users\<user_name>\.klocwork\ltoken
  • Unix:~/.klocwork/ltoken

.klocwork ディレクトリに ltoken ファイルがない場合は、kwauth を実行してこのファイルを生成してください。

デフォルトの ltoken の場所をオーバーライドする

'KLOCWORK_LTOKEN' 環境変数を設定することによりカスタムの ltoken ファイルの場所を使うことができます。ltoken ファイルに入力するには、「KLOCWORK_LTOKEN」を設定し、kwauth を使用して認証します。生成された ltoken は初期設定の場所ではなく、指定された場所に格納されます。

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

これは、元の ltoken ファイルを移動したり、コピーしたりすることがないため、別のツールを使用する前に、kwauth でユーザーを再認証する必要があります。

kwauth Linux の例:
1  > export KLOCWORK_LTOKEN=/space/myltokenfile
2  > kwauth
3  > Login: jsmith
4  > Password:
kwcheck Windows の例:
1  > set KLOCWORK_LTOKEN=C:\space\myltokenfile
2  > kwcheck run
3  ...

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

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 を解決するのを防ぐことができます。

ltoken からアプリケーショントークンへの移行

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

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

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

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

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

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 サーバーで認証する際に使用する認証トークンを http://localhost:40000 で取得するには、次のコマンドを実行します。

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

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

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

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

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