User Level Access Control in Integrations and APIs

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.

Why It Is Needed

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:

  1. Go to the WhiteSource GUI and open the Integrate.
  2. In the Integrate page, select the checkbox Enforce user level access.
  3. 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.

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:

  1. Go to the WhiteSource GUI and open the User Profile.
  2. Click on the Generate User Key.
  3. 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.

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:

AttributeTypeDescriptionMandatory
userKeyString

Unique identifier of user.

Required if WhiteSource administrator has selected the Enforce user level access option.

Example of a userKey attribute entered in 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:

ParameterTypeDescriptionMandatory
-userKeyStringUnique 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.

The argument is entered in the following fashion:

"userKey":"user_key",

The following is an example of a “getProjectVulnerabilityReport” API request that includes the userKey argument:

{

"requestType" : "getProjectVulnerabilityReport",

"userKey":"5c5c5b1dc14b44faa71d4bc443de",

"projectToken" : "438629e2da934b4ca68220c"

}

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.