Authentication using ltokens
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 theVALIDATE_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 inuser/.klocwork/tokens.jks
. You can change the tokens.jks file location by setting theVALIDATE_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 locationThe previousKLOCWORK_LTOKEN
environment variable will still function, but if bothKLOCWORK_LTOKEN
andVALIDATE_LTOKEN
are set,VALIDATE_LTOKEN
takes precedence.
-
Transitioning from ltokens to application tokens for signing in to command line tools
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.
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.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.
export VALIDATE_LTOKEN=/space/myltokenfile kwauth Login: jsmith Password:
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
Unable to authenticate using SSL with <url>
<?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
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.
kwauth
with version 2024.1 or earlier of other client tools, you must run kwauth
using the --insecure
flag. --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.