The following prerequisites are required in order to use the Access Control (REST) API:
Checkmarx Access Control (v1.5.0 and above) installed
OAuth2 and SSO - If SSO is already configured on the system the Internet Information Services Manager (IIS) may need some additional configuration.
Go to Start > Search > IIS and open the Internet Information Services Manager.
From Sites > Default Web Site > CxRestAPI, select Authentication and enable Anonymous Authentication.
Confirm that these are the settings, if not, update them accordingly.
Configuration Keys – The following default value is provided in the CxComponentConfiguration database table in order to use the Access Control (REST) API:
IdentityAuthority – In case using HTTP (and not HTTPs) or the machine name is not used as the Checkmarx domain (for example, when using a load balancer), the IdentityAuthority should be changed.
In this part of the documentation, we will use the words “Access Control service” to refer to the base address of the REST service. For the Checkmarx Platform Services, this URL can be found on the /<server-name/ip>:<port>/cxrestapi/auth path, relative to the platform hostname (http://<host name>:<port>/cxrestapi/auth).
Unless stated otherwise, all addresses in the rest of this documentation are relative to the Access Control service, apart from when requesting an access token for authentication.
Versioning and Media Type
The Checkmarx platform service is installed with the latest version (i.e. v=1.0) of the Access Control (REST) API. In order to use another version of the Access Control (REST) API you will need to add ';v=<version>' to a media type header in the request. The media type header defined will depend on the request method used:
GET Request – Accept: application/json;v=1.0
POST, PUT, PATCH and DELETE Requests – Content-Type: application/json;v=1.0
Note: Not specifying the version automatically applies the latest default version and may cause your script/code to break.
The Access Control service supports json format.
We will use authentication and request submission in Postman for most of the Access Control (REST) API testing examples.
An authenticated user can be granted access to restricted sets of data and benefit from extended quotas for API calls. The Access Control (REST) API features an authentication mechanism for users to be granted their specific authorizations.
To complete the authentication procedure you need to know the following basic fundamentals:
The basics of using REST APIs, e.g. requests, responses, headers
The basics of using Checkmarx Platform Services
We will use access token-based authentication in Postman for this example.
Step 1: Creating a new OIDC client
Each user who wants to develop his or her own implementation should create a unique OIDC client with its own client secret. It is not possible to perform this task via Postman, because you first need to create a valid OIDC client in order to create an access token. We recommend that you do this using your swagger instance.
To do this you can use the POST /OIDCClients API via your swagger instance (http://<server-name/ip>:<port>/cxrestapi/auth/swagger/index.html). For more information about Creating a new OIDC client, refer to Create New OIDC Client - POST /OIDCClients.
Step 2: Requesting an access token for authentication
You need to receive an access token for authentication. The first thing you need to do is make a request to the authentication server by including the credentials received from the authorization server.
To do this, just submit (POST) the desired credentials to the token endpoint using the application/x-www-form-urlencoded format in the request body:
In order to retrieve additional information about the available endpoints and scopes, refer to: ‘http://<server-name/ip>:<port>/cxrestapi/auth/identity/.well-known/openid-configuration’ or click on the discovery document link in your swagger instance.
username: <Cx username>
password: <Cx password>
grant_type: Value must be set as 'password'
scope: Value must be set as 'access_control_api’
client_id: Value must be set as 'resource_owner_client'
client_secret: Default value is set as '014DF517-39D1-4453-B7B3-9930C563627C', unless you have created a new OIDC client, in Step 1.
The access token request will look some similar to the following:
This creates a login session and returns the requested access token response information, which will look similar to the following:
If the access token request is valid and authorized, the authorization server issues an access token response.
The session request will look some similar to the following:
Now, when you submit the request, this access token value is used for authentication, until the token expires.
In case of an error the authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following error with responses:
error – A single error code with one of the following:
invalid_request – The request is missing a required parameter, includes an unsupported parameter, repeats a parameter or includes multiple credentials
invalid_client – Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)
invalid_grant – The provided authorization grant is invalid, expired, revoked or was issued to another client
unauthorized_client – The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type – The authorization grant type is not supported by the authorization server
invalid_scope – The requested scope is invalid, unknown or malformed.
If you have not used the Access Control (REST) API for a while, you need to perform the authentication again because your token has expired. You will receive an error response. The response body will contain a message telling you that your token is invalid. At this point, you will need to re-authenticate using the access token request procedure in the Access Control (REST) API.