Skip to main content

Using the Access Control (REST) API

Prerequisites

The following prerequisites are required in order to use the Access Control (REST) API:

Checkmarx Access Control (v1.5.0 and above) installed

OAuth 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.

General Points

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.

Format

The Access Control service supports json format.

Testing

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

Authentication

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:

  • Endpoint example: http://<server-name/ip>:<port>/cxrestapi/auth/identity/connect/token

    Notice

    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.

  • 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’

    • 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:

6436228209.png

This creates a login session and returns the requested access token response information, which will look similar to the following:

6436228212.png

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 3: 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>/cxrestapi/auth/AssignableUsers

  • Credentials example:

    • Authorization: Bearer <access token value>

    • Accept: application/json;v=1.0

The session request will look some similar to the following:

6436228215.png

Now, when you submit the request, this access token value is used for authentication, until the token expires.

Authentication Errors

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.

Token Expiration

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.