Using the Policy Management (REST) API

General Points

In this part of the documentation, we will use the words “Policy Management service” to refer to the base address of the REST service. For the Management and Orchestration platform, this URL can be found on the /cxarm/policymanager path, relative to the platform hostname (http://<host name>:<port>/cxarm/policymanager).

Unless stated otherwise, all addresses in the rest of this documentation are relative to the Policy Management service, apart from when requesting an access token for authentication.

Versioning and Media Type

Management and Orchestration is installed with the latest version (i.e. v=1.0) of the Policy Management API. In order to use another version of the Policy Management (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

Format

The Policy Management service supports json format.

Testing

We will use authentication and request submission in Postman for most of the Policy Management (REST) API testing examples.

Permissions

• Manage Policies (all admin roles) – Company Manager, SP Manager, Server Manager
• View Policies and Policy Violations – All Users

Authentication

An authenticated user can be granted access to restricted sets of data and benefit from extended quotas for API calls. The Policy Management (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 Management and Orchestration

We will use access token-based authentication in Postman for this example.

Step 1: 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:

• 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:
    • ‘cxarm_api’ for v8.8.0 and v8.9.0
    • ‘management_and_orchestration_api sast_api’ for v9.0.0 and up
  • client_id: Value must be set as:
    • ‘resource_owner_client’ for v8.8.0 and v8.9.0
      
    • ‘management_and_orchestration_server’ for v9.0.0 and up
  • client_secret: Value must be set as '014DF517-39D1-4453-B7B3-9930C563627C'

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.

An example successful access token response:

   {
     "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 example access token error response:

   {
     "error":"invalid_grant"
   }

This error means that the provided authorization grant is invalid, expired, revoked or issued to another client. For more examples of errors with responses, see the Error Responses.

Step 2: Using the access token in a request to the resource server

When you want to make a request to the resource server, you should send the access token (access_token) received during authentication.

To do this, just submit (GET) the access token value to the resource in the request header:

• Resource example: http://<server-name/ip>:<port>/cxarm/policymanager/policies
• Credentials example:
  • Authorization: Bearer <access token value>
  • Accept: application/json;v=1.0

The session request will look some similar to the following:

Now, when you submit the request, this access token value is used to authenticate you to Checkmarx, until the token expires.

Authentication Errors

The following errors may occur during authentication:

Token Expiration

If you have not used the Policy Management 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 Policy Management API.