User Tokens
What is a User Token?
In general
A user token is a form of credentials for the user it belongs to, which are usually completely different and separate from their original credentials.
In IQ Server
A user token is composed of a userCode and a passCode.
User tokens are supported for:
- Internal and LDAP users in release 76+
NEW IN RELEASE 136
- Crowd and SAML users in release 136+
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.
User tokens are not supported with reverse proxy authentication.
Why use a User Token?
There are two main benefits to using a user token.
Firstly, the user does not have to expose their original credentials (e.g. in REST API requests), which may be in-use elsewhere.
Secondly, user tokens can be easily created and deleted, which is useful should security policies require credential updates, or if credentials are lost accidentally or otherwise.
Managing a User Token
Regardless of how you generate and use user token, it's important to note that:
- Your user token credentials are only available upon creation. If you forget or lose your user token credentials, you must delete your user token and create a new one.
- A user can only have one user token.
Internal, LDAP, or Crowd Users
You can create and delete your user token via the user token REST API or the UI.
SAML Users
We recommend you create and delete your user token via the UI.
Technically SAML users may use the user token REST API, but can only do so using a session that has already been created through the UI. This is because IQ Server SAML identification uses the Web Browser SSO profile where the UI is needed to interact with the SAML identity provider to create a session.
Using a User Token
Once created, you can use your user token userCode and passCode code to log in to IQ Server through the UI and to issue REST API requests, i.e.
curl -u [userCode]:[passCode] ...
e.g.
curl -u TfPLVkV2:Hb5WZsYrvswl1wwRgxaaDVthlOVw7zSdaf1wWOrnlEU3 http://localhost:8070/api/v2/organizations
System Administrators
You can query and delete user tokens via the user token REST API. This includes an endpoint to purge obsolete user tokens for LDAP users that no longer exist.
User Token UI
Users can now generate their user token from within the IQ UI. This provides an easy way to achieve the same capabilities provided by the User Token API.
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
From the Manage User Token modal a new user token can be generated by clicking on the Generate User Token button.
The resulting User Code and Passcode will be displayed along buttons that allow for them to be copied to the clipboard and used elsewhere.
Reviewing User Token
It is important to note that for security reasons this will be the only available time to view the User Code and Passcode. Subsequent visits to this modal will NOT display these values.
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.