Overview
User-level access control in integrations and APIs is provided by user keys. The user key is a unique identifier that is mapped to a WhiteSource user.
WhiteSource supports the option of creating and using a unique identifier for each user who utilizes its services. The support for using user-level access control in integrations enhances auditing and optimizes accountability insights for the WhiteSource administrator.
It allows to enforce segregation of administrative actions between different products and projects (i.e., a user who is not a product administrator cannot delete it). It also enables the administrator to view details on the activities of each user in relevant reports. Once the WhiteSource administrator enforces the use of user-level access control in integrations, all requests must include a user key.
Applicability
All WhiteSource agents support adding an attribute in the agent’s configuration file and/or a parameter in the command line.
All HTTP API methods support adding a user key argument to the API request.
Configuring the User Level Token
The WhiteSource administrator configures the user level access control in integrations by following these steps:
Go to the WhiteSource GUI and open the Integrate.
In the Integrate page, select the checkbox Enforce user level access.
The use of the user level access control in integrations has been enforced and all requests must include a user key. Any request which will not include a user key will fail.
Once the Enforce user level access is enabled, running scans will require providing the user key as well as the organization token.
Generating User Keys
User keys are generated by the user who will then be required to add it in all of his/her WhiteSource requests. The steps for generating a user key are the following:
Go to the WhiteSource GUI and open the User Profile.
Click on the Generate User Key.
A unique user key is displayed in the User Keys table for the user to add in the various agents and APIs. The user key is mapped to the user profile name.
A user key can also be generated when the Enforce user level access option has not been selected by the WhiteSource administrator. The user has the option to generate more than one user key (up to 10 user keys) for situations that include the use of unique user keys for various integrations (e.g., one user key for the Jenkins Plugin, one user key for the Unified Agent, and one user key for the API).
Configuring Agents
The user key is configured in the agent configuration file and the agent command line.
Agent Configuration File
The user adds the user key by entering it in the relevant WhiteSource plugin configuration file (e.g., "WhiteSource-fs-agent.config” for Unified Agent). This is done by adding the following attribute:
Attribute | Type | Description | Mandatory |
|---|---|---|---|
userKey | String | Unique identifier of user. | Required if WhiteSource administrator has selected the Enforce user level access option. |
Example of a userKey attribute entered in the configuration file:
Agent Command Line
The user can also configure the user key by entering it in the command line. The following user level parameter has been added for the agent command line:
Parameter | Type | Description | Mandatory |
|---|---|---|---|
-userKey | String | Unique identifier of user. | Required if WhiteSource administrator has selected the Enforce user level access option. |
Configuration in HTTP API
A userKey argument has been added to the HTTP API, and it must be added to all HTTP API requests when the Enforce user level access option has been enabled.
Only WhiteSource users with administrator privileges (organization or product level) and Product Integrators are allowed to use the APIs in case the Enforce user level access option has been enabled.
The argument is entered in the following fashion:
|
|---|
The following is an example of a “getProjectVulnerabilityReport” API request that includes the userKey argument:
|
|---|
Reports
With the support of the User level access control in integrations, the WhiteSource administrator has the option to view and analyze reports that provide data on the usage of WhiteSource requests per user. Reports display the users’ profile names, which are linked to their respective user keys.
Plugin Request History Report
This report provides data on plugin requests per user.
Plugin Policy Violation History Report
This report provides Plugin Policy Violation History per user.