Configuring bearer token authentication

Overview

Bearer tokens offer a secure alternative to basic authentication (username/password) because they allow for automated tasks without exposing primary credentials. These follow the industry-standard bearer token scheme (RFC 6750).

Prerequisites and Permissions

Below is a list of relevant prerequisites and permissions required to use this feature:

Administrative Oversight: A token for an operator can only be created by that operator; Master Operators can edit or delete existing tokens of any operator via REST API; Non-Master Operators can only manage their own.
Privileges: To authenticate using a token, you must be a Master Operator or a Non-Master Operator with "Can use REST API" login privilege.
Inheritance: Authentication via token benefits from the same permissions that the operator has when using basic authentication.

Enabling or Disabling the Feature

To issue and validate authentication tokens, BigFix needs to use a dedicated secret key, which is absent by default. To enable the bearer token authentication feature, you must first create this key.

You can create, rotate, or revoke the token secret key using the BigFix Administration Tool.

Creating the token key: Use the createtokenkey service of the BigFix Administration Tool to create the token key and enable the feature.
Rotating the token key: Use the rotatetokenkey service of the BigFix Administration Tool to rotate the existing token key. Please note that this operation permanently invalidates all existing tokens for all operators, so you will need to create new ones to continue using the feature.
Revoking the token key: Use the revoketokenkey service of the BigFix Administration Tool to revoke the existing token key. Please note that in addition to disabling the feature, this operation permanently invalidates all existing tokens for all operators, so if the feature is later re-enabled, you will need to create new ones to use it.

For more information about using these commands, see BESAdmin Windows Command Line and BESAdmin Linux Command Line.

Creating a Token

Important Security Note: BigFix does not store tokens in clear text anywhere.

Using the BigFix Console:

From the Tools menu, navigate to the Manage Tokens... window.
Click Add New....
Enter a Name (this will be known and visible only to the operator who creates the token).
Set the Duration in days. Check "Non-expiring token" for long-term tokens.
Click OK. A pop-up will display your token. Copy and store it securely. Important Note: The token can only be viewed and copied at this time. If you lose it, you will need to create a new one.

For more details, see Manage Tokens.

Using the BigFix Server REST APIs:

Endpoint: POST api/token
Parameters: name (string), duration (integer indicating the token validity in days; 0 for non-expiring tokens; default is 30 days if parameter is not specified).

For more details, see Token REST API.

Modifying and Deleting Tokens

You can view token metadata (Id, Name, Expiration, User) but never the token string itself after creation.


Action	Console Method	REST API Method
List	Open the "Manage Tokens..." window from the "Tools" menu.	GET api/tokens; GET api/token/name/{token_name}; GET api/token/id/{token_id}; GET api/tokens/user/{operatorID}
Edit	On the "Manage Tokens..." window, click "Edit..." on a specific token row.	PUT api/token/{token_id}
Delete	On the "Manage Tokens..." window, click "Delete" on a specific token row.	DELETE api/token/{token_id}

Using Tokens

Once you have created a token, use it across the following interfaces:

BigFix Server REST APIs and BigFix Explorer REST APIs

Include the token in your HTTP request header using the Bearer authentication scheme:

Authorization: Bearer <your_token_here>

For more details, see Token REST API and Administering the BigFix Explorer.

IEM Command Line (IEM CLI)

Log in using the --token parameter:

./iem login --server={ServerName}:{ServerPort} --token={your_token_here}

For more details, see Token Authentication.