User Tokens

User tokens are internal and disposable credentials generated by IQ Server for use in Lifecycle Integrations without exposing the user's login credentials coming from the organization's identity provider. This is useful for accessing IQ Server integrations when identity providers, such as SAML, do not typically rely on usernames and passwords.

Using Tokens is highly recommended for IDEs and service accounts used in CI build scans as these temporary credentials can easily be reset to avoid credential leaks.

A user token is composed of a user code and a passcode. When one of these users successfully submits their user token credentials, then they will be authenticated and authorized as if they had submitted their original credentials.

Note
User tokens are not supported with reverse proxy authentication.

Where to use Tokens?

Here are common examples where user tokens are recommended:

• IDEs and CI build scans
• For scripts using the REST API
• Service accounts and build automation where credential leak is possible

Managing a User Token

User token credentials are only available upon creation and cannot be retrieved. You may delete your previous token and create a new one. A user can only have one user token.

You can create and delete your user token via the User Token REST API or through the IQ Server UI.

SAML Users
We recommend you create and delete your user token initially via the UI.

SAML users may use the User Token REST API, however, they can only do so after initially logging into the UI. IQ Server SAML identification uses the web browser SSO profile where IQ Server interacts with the SAML identity provider to create a session.

Using a User Token

Once created, you can use your user token userCode and passCode to log in to access the IQ Server, API, and integrations.

curl -u [userCode]:[passCode] http://localhost:8070/api/v2/organizations

System Administrators

You can query and delete user tokens via API. This includes an endpoint to purge obsolete user tokens for LDAP users that no longer exist.

See the User Token REST API for more details.

User Token from the server UI

Users can generate their user tokens from within the IQ UI.

How to Access

The UI for managing the user token can be accessed from the User Menu by clicking on the Manage User Token option.

Generating a User Token

Generate a new user token by clicking the Generate User Token button within the Manage User Token modal.

The resulting User Code and Passcode will be displayed along buttons that allow for them to be copied to the clipboard and used elsewhere.

Deleting a User Token

Re-visiting the modal will show a warning informing the user that a user token already exists and that it would need to be deleted in order to generate a new one.

Clicking on Delete User Token will delete the existing token thus allowing for the creation of a new one.

User Token Expiration

The user token expiration feature allows System Administrators to configure an expiration period (in days) for user tokens. When enabled, IQ Server validates the age of each user token during authentication and treats tokens older than the configured period as expired.

User token expiration is disabled by default. When enabled, the default expiration period is 30 days, and the value can be set between 1 and 365 days.

Expiration applies to existing and newly created user tokens and is based on the token’s creation time. When the expiration setting is enabled or updated, IQ Server immediately evaluates all user tokens using the configured threshold. Increasing the expiration period may cause previously expired tokens to become valid again; decreasing the period causes any token exceeding the new threshold to be considered expired on the next use.

Configuring User Token Expiration

User token expiration is configured at the system level:

1. Go to System Preferences and select User Token Configuration.

2. Enable the Enable User Token Expiration option.

3. Specify the number of days before user tokens expire.

4. Save your changes.

To remove expiration for all user tokens, disable the Enable User Token Expiration option. This stops enforcing expiration for both existing and new tokens.

Only users with the System Administrator role can view and modify the user token expiration settings.

User Token Expiration Status

To view the expiration status of your user token:

• Open the User Menu and select Manage User Token.

If a user token exists and an expiration configuration is enabled, the Manage User Token modal displays the date and time when the token will expire.

If the user token is expired, the modal indicates that the token has expired. You must delete the expired token and generate a new token before it can be used.

When an expired user token is used for authentication, IQ Server returns HTTP 401 Unauthorized with the message "User token has expired. Please generate a new token".

If an expiration configuration is not enabled, the Manage User Token modal does not display an expiration date.