Authentication using ltokens

Starting with release 2024.3, secure tokens are stored in a 'credentials' file, while the existing 'ltoken' file will still be used for insecure tokens or when the --insecure flag is set. See Secure authentication tokens.
In release 2024.2, ltokens have been replaced by application tokens for signing in to command line tools. If you relied on ltokens for scripting before release 2024.2, see Transitioning from ltokens to application tokens.

Authentication tokens are stored by kwauth and by Klocwork client applications in a special file in the user's home directory. This token is used to authenticate users with tools such as kwbuildproject, kwcheck and the Web API. You can find this file as follows:

  • Windows: C:\Users\<user_name>\.klocwork\credentials (for secure tokens) or C:\Users\<user_name>\.klocwork\ltoken (for ltokens)
  • Unix: ~/.klocwork/credentials (for secure tokens) or ~/.klocwork/ltoken (for ltokens)

If there is no 'credentials' or 'ltoken' file in your .klocwork directory, you can run kwauth to generate one.

Secure authentication tokens

Secure authentication tokens are stored in a 'credentials' file, which is generated when you run kwauth. Starting with version 2024.3, the default is to create a 'credentials' file, unless the --insecure flag is used, in which case an 'ltoken' file will be generated.

The system will prioritize loading from the 'credentials' file first, then fall back to 'ltoken'. Secure tokens from earlier versions will still work if no 'credentials' file is present, and backward compatibility for older tools using insecure tokens remains intact.

In Validate 2024.3, the following enhancements were made:

  • You can specify how credentials are stored using the VALIDATE_SECURE_TOKEN_STORAGE environment variable:

    If you do not set the VALIDATE_SECURE_TOKEN_STORAGE environment variable, JAVA_SECRET_STORAGE will be used.

    • JAVA_SECRET_STORAGE (default for new tokens): Stores credentials using secure storage with Java KeyStore. By default, the secure java storage file is located in user/.klocwork/tokens.jks. You can change the tokens.jks file location by setting the VALIDATE_TOKEN_KEYSTORE_FILE environment variable.

    • OS_NATIVE: Stores new credentials using OS-dependent secure storage (Windows Credential Manager for Windows and libsecret for Linux).

    • DISABLED: Stores new credentials using insecure storage in plain text within the .ltoken file. If you’re using 2024.1 or earlier Klocwork tools with a 2024.2 or newer Validate server, you must use insecure token storage.

  • The addition of secure application tokens also includes the following new environment variables:

    • VALIDATE_TOKEN_KEYSTORE_FILE for the keystore location

    • VALIDATE_CREDENTIALS for the 'credentials' file location

    • VALIDATE_LTOKEN for the 'ltoken' file location

      The previous KLOCWORK_LTOKEN environment variable will still function, but if both KLOCWORK_LTOKEN and VALIDATE_LTOKEN are set, VALIDATE_LTOKEN takes precedence.

Transitioning from ltokens to application tokens for signing in to command line tools

if you’re using 2024.1 or earlier Klocwork tools with a 2024.2 or newer Validate server, you must use insecure token storage. To use insecure storage with any authentication command, set the VALIDATE_SECURE_TOKEN_STORAGE environment variable to DISABLED.

In Validate 2024.1 and earlier, an ltoken was created and stored in a plain text file after successful authentication with a Validate server. The ltoken could be used in situations where interactive authentication was not possible (for example, scripted environments or Web API queries).

In Validate 2024.2, the following enhancements were made:

  • kwauth defaults to storing credentials in OS-dependent secure storage (Windows Credential Manager for Windows and libsecret for Linux)
  • Administrators and users can revoke tokens
  • Application tokens can be used when interactive authentication is not possible

  • You can use an application token to authenticate, but it is not stored in the secure storage

After you migrate your Validate server, your previously authenticated ltokens (sessions) will continue to work.

When you switch from one authentication method to another (for example, from Basic to LDAP or from LDAP to OIDC), your existing authenticated ltokens (sessions) will become invalid. Your users must reauthenticate.

To avoid losing user and role information, back up your projects_root/permissions_data folder before switching authentication methods. If user and role information was accidentally deleted while switching authentication methods, you can restore the information from the backup of your permissions_data (derby) database.
All scripted environments that relied on ltokens for authentication must switch to application tokens. See Authentication using application tokens.

Overriding the default secure token or ltoken location

You can use a custom secure token or ltoken file location by setting the VALIDATE_CREDENTIALS or VALIDATE_LTOKEN environment variable, respectively. To populate the file, set VALIDATE_CREDENTIALS or VALIDATE_LTOKEN and authenticate using kwauth. The generated file is stored in the specified location instead of the default location.

Tools requiring authentication use the location specified in the environment variable, if set. Otherwise, it uses the default location.

This does not move or copy the original file, so you must re-authorize users with kwauth before other tools can be used.

Example for kwauth on Linux:
export VALIDATE_LTOKEN=/space/myltokenfile
kwauth
Login: jsmith
Password:
Example for kwcheck on Windows:
set VALIDATE_CREDENTIALS=C:\space\mycredentialsfile
kwcheck run
...

Note that after setting the environment variable to a new value, you might need to run kwauth again, otherwise the file might be empty.

Failing authentication if host name is not found

You can enable kwauth to fail authentication in the case where the server host name was not found in the certificate CN or Subject Alternative Name by setting the verifyCertificate option to true. Enabling this results in the following error message if the host name cannot be found:
Unable to authenticate using SSL with <url>
To set this value to true, create a 'client_config.xml' file in your {client_tools_install_folder}\config\ folder (if it does not already exist). The file must contain the following:
<?xml version="1.0" encoding="UTF-8"?>
   <params> 
     <host resolveHost="false" verifyCertificate="true"/>
   </params>

Note that setting resolveHost="false" is not mandatory, but doing so can prevent the Klocwork Server from resolving the wrong FQDN as the Server will use whatever host you specify in a remote server URL.

To authenticate with the Klocwork Web API

Application tokens cannot be used to authenticate with the Web API. Use kwauth to authenticate to your Validate server, then use kwauth --print-auth-info to obtain the ltoken.

In Klocwork 2024.1 and earlier, you would copy your ltoken from the ltoken file to authenticate with the Klocwork Web API.

Starting in Klocwork 2024.2, you must use kwauth to authenticate to your Validate server, then use kwauth --print-auth-info to obtain the ltoken. Administrators with Web API access can use kwauth --print-auth-info to print the authentication token and the user it was issued to for the specified server in JSON format, which allows the token to be used for Web API requests.

If you are using version 2024.2 of kwauth with version 2024.1 or earlier of other client tools, you must run kwauth using the --insecure flag.
To make sure you authenticate with the correct Validate server, always include the --url parameter when you run kwauth.

Example 1: Secure storage

To obtain the ltoken that you'll use to authenticate with the Validate server at http://localhost:40000, run the following command:

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

This returns the following:

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

You can use the token for Web API authentication by following the instructions in Formatting requests to the API.

Related concepts