Using Authentication Tokens for XTAM REST APIs.
XTAM has always exposed APIs for every function it has, but the only way to access the API with the use of a username and password. This means that the application that calls XTAM should have this hard coded username and password to login to XTAM and ultimately call the API function like creating a new record. This is generally considered an undesirable approach because exposing the username and password like this also exposes other areas of the network that this user can access which may be completely unrelated to XTAM’s operations. Because of this and other reasons, we implemented the recommended practice of letting other applications login to XTAM using tokens.
What XTAM can do is generate tokens for a specific user where this token could be used to authenticate in XTAM on behalf of the user of which this token was generated. Then the external application that wants to communicate with XTAM should have access to XTAM by the XTAM-generated token that is saved to or hard coded into the application of function.
The advantages of using the authentication token as compared to a username and password is that the token is specific to XTAM as opposed to an actual user’s credentials. This allows the application to communicate with XTAM without hard coding a user’s password anywhere thus protecting any other areas of the network that this user can access (think of using their AD credentials which could expose any number of security issues).
XTAM provides the facilities to generate tokens for specified users, to maintain a current list of tokens and to enable (and disable) tokens invalidating them for subsequent use. XTAM also provides an option to create tokens with expiration making them invalid after a defined period of time.
Generate API Authentication Tokens
To Generate API Authentication Tokens:
XTAM requires the use of the Federated Sign-In Module in order to generate tokens. If you do not have this module deployed then the option to Generate Tokens will not be available.
- Login to XTAM as a System Administrator. Only System Administrator can manage Authentication Tokens.
- Navigate to Administration > Tokens
- Click the Generate Token button
- Populate the Generate Token dialog as described below:
In the Principal field, enter the username that the token will be generated for.
Note that only a single user (not multiple users or groups) can have a token generated at a time. Simply repeat this process to generate tokens for additional users or to generate another token for this same user.
In the Expiration (mins) field, enter an expiration time for the token in minutes. To generate a token that will not expire, leave this field empty.
Note that the expiration countdown begins when the token is generated not when it is first used.
In the Comment field, enter an optional comment related to this token.
The Token field is read-only and will display the token after it is generated.
When the Generate Token dialog is populated as needed, click the Generate button to generate the token for this user.
This token and its corresponding values will be displayed for reference in the Authentication Tokens list.
Only part of the Authentication Token is displayed in the Authentication Tokens list, so you will need to click the Copy to Clipboard ( XTAM API Authentication Tokens Copy to Clipboard ) button to access the full token.
Read further about how to use these tokens to call the XTAM APIs to retrieve secrets, create new records and more.
Perform the actions
After the token(s) is generated, you may perform the following actions:
- Sort the ordering of tokens by clicking on the desired column header.
- Use the Search box to locate specific tokens.
- Export the displayed list of tokens to a CSV or PDF file.
- Click the Copy to Clipboard button to easily share the full token with your user(s) or to paste it into external applications or functions.
- Immediately Enable or Disable use of the tokens by clicking the appropriate option.
The following information is provided as columns in the Authentication Tokens report:
- ID: Displays the internal XTAM ID that is associated with this token.
- Time: Displays the timestamp (MM/DD/YYYY HH:MM:SS) of when the token was generated.
- User: Displays the user that is associated to this token.
- Expiration: Displays the expiration time associated to this token. An empty field means that the token does not have an expiration time and a time with a strike though indicates that the token has expired.
- Token: Displays part of the token. Use the Copy to Clipboard button to access the full token. Disabled tokens will be shown with a strikethough.
- Comment: Displays the optional comment that was associated to this token.
- Actions Menu: Provides the following options:
Enable/Disable: Click Disable to disable an enabled token or click Enable to enable a disabled token.
Delete: Click Delete to delete a token.