Authentication using the ltoken

In release 2024.2, ltokens have been replaced by application tokens. 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, called the ltoken, 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\ltoken
  • Unix:~/.klocwork/ltoken

If there is no ltoken file in your .klocwork directory, run kwauth to generate the file.

Overriding the default ltoken location

You can use a custom ltoken file location by setting the 'KLOCWORK_LTOKEN' environment variable. To populate the ltoken file, set 'KLOCWORK_LTOKEN' and authenticate using kwauth. The generated ltoken is stored in the specified location instead of the default location.

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

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

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

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.

Transitioning from ltokens to application tokens

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 secure storage (OS-dependent)
  • Administrators and users can revoke tokens
  • Application tokens can be used when interactive authentication is not possible

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 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 authentication token 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.

To avoid losing user and role information, back up your projects_root/permissions_data folder before switching authentication methods.
All scripted environments that relied on ltokens for authentication must switch to application tokens. See Authentication using application tokens.
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.
Related concepts