CxSAST (OData) API Authentication
Authentication and Permissions
An authenticated user can be granted access to restricted sets of data and benefit from extended quotas for API calls. Starting from this version (v9.0.0), the CxSAST (Odata) API features an authentication mechanism for users to be granted their specific authorizations.
To complete the authentication procedure you need to know the following fundamentals:
The basics of using Odata APIs, e.g., requests, responses, etc.
The basics of using Checkmarx Access Control and CxSAST
We will use access token-based authentication in Postman for this example.
Permissions
To perform the authentication procedure and implement Odata API functionality you also require the following permission:
Run Odata Queries
Step 1: Requesting an access token for authentication
In order to complete the authentication procedure, you first 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 following application/x-www-form-urlencoded format in the request body:
Endpoint example: http://<server-name/ip>:<port>/cxrestapi/auth/identity/connect/token.
Credentials example:
username: <Cx username>
password: <Cx password>
grant_type: Value must be set as 'password'
scope: Value must be set as 'access_control_api sast_api'
client_id: Value must be set as 'resource_owner_sast_client'
client_secret: Default value is set as '014DF517-39D1-4453-B7B3-9930C563627C'
The access token request will contain the following Postman format:
The POST request described above creates a login session and returns the requested access token response information, which will look similar to the following Postman example:
If the access token request is valid and authorized, the authorization server issues an access token response.
A successful response takes the following format:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGtr0hoV4Vj8GNkyk2A…………..",
"expires in": 3600,
"token_type": "Bearer"
}
If the request failed client authentication or is invalid, the authentication server returns an access token error response.
An error response takes the following format:
{
"error":"invalid_grant"
}
This error could mean that the provided authorization grant is invalid, expired, revoked or issued to another client.
Step 2: Using the access token in a request to the resource server
To make a request to the resource server, send the access token (access_token) received during authentication.
To do this, submit (GET) the access token value to the resource in the request header:
Resource example: http://<rver-name/ip>:<port>/Cxwebinterface/odata/v1/Scans(<scan_Id>)
Credentials example:
Authorization: Bearer <access token value>
The session request will contain the following Postman format:
When you submit the request, this access token value is used for authentication until such a time that the token expires.
Token Expiration
A token automatically expires, if not used for a predefined amount of time (i.e., expires in = 3600 secs). You will receive an error response letting you know that your token is invalid. In this case, you will need to re-authenticate using the access token request for authentication procedure in Step 1.