API Authentication
Authentication with the Qualys Cloud Platform is required before you try the APIs.
TotalCloud offers three methods of authentication.
Basic Authentication
You can click Authorize, enter the <qualys_base_url> and password, and then use the APIs.
curl -k -X POST -u <username>:<password> "https: //<QualysBaseURL>/cloudview-api/rest/v1/report/assessment/create"
API Request
curl -k -X POST -u <username>:<password> "https: //<QualysBaseURL>/cloudview-api/rest/v1/report/assessment/create"Response
{
"reportName": "AWS Assessment Report",
"description": "",
"cloudType": "AWS",
"query": "",
"startDate": "2024-12-03T00:12:53Z",
"endDate": "2024-12-10T18:53:s53Z",
"executionType": "RUN_TIME",
"policyIds": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
],
"tagIds": [
],
"connectorIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
],
"format": "csv",
"iacResourceResults": [ ]
}
Qualys Gateway Service Token-based Authentication
The Qualys API Gateway service provides enhanced security with temporary access tokens. You can include the limited-time Bearer token when making your API call.
curl --location 'https://gateway.<platform_url>.qualys.com/cloudview-api/rest/v1/aws/connectors?pageNo=0&pageSize=50' \
--header 'accept: */*' \
--header 'Authorization: Bearer <Bearer Token>' \
--data ''
API Request
curl--location '<qualys_gateway_url>/cloudview-api/rest/v2/report/assessment/create'
--header 'Authorization: Bearer <access_token from above response>'
Response
{
"reportName": "AWS Assessment Report",
"description": "",
"cloudType": "AWS",
"query": "",
"startDate": "2024-12-03T00:12:53Z",
"endDate": "2024-12-10T18:53:s53Z",
"executionType": "RUN_TIME",
"policyIds": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
],
"tagIds": [
],
"connectorIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
],
"format": "csv",
"iacResourceResults": [ ]
}
OIDC Authentication
If you have enabled Open ID Connect Authentication for your account, you can authenticate by generating a JWT token. This eliminates the need to provide the <qualys_base_url> and password for API calls.
This feature is not enabled by default. Contact Qualys support to enable it for your subscription. You must follow the onboarding process. This feature requires IdP.
Prerequisites
Public signing certificates for verifying the authenticity of SAML responses. Up to 3 certificates can be provided. The certificate must be in X.509 format (usuallyin .pem or .cer files).
- IdP Name
The name of the Identity Provider (IdP) being configured. This can be a customname or provided by the customer.
Example: "TestNameforIDP Qualys Internal" - Entity ID
The unique identifier for the customer’s IdP. Typically, this is a URN or URL that serves as the IdP’s primary identifier during OIDC communications.
Example: "https://example.com/idp" - Single Sign-On (SSO) URL
The URL where authentication requests will be sent. This is the endpoint where users are redirected to authenticate with the customer’s IdP.
Example: "https://example.com/login" - Single Logout (SLO) URL (if applicable)
The URL for handling logout requests. If you support Single Logout, this endpoint manages session termination at both the IdP and in Qualys.
Example: "https://example.com/logout" - SSO Exit URL (optional)
The URL where users will be redirected after successful authentication.
- Certificates
Public signing certificates for verifying the authenticity of SAML responses. Upto 3 certificates can be provided. The certificate must be in X.509 format (usuallyin .pem or .cer files).
Onboarding Process
To start using OpenID Connect API authentication, the following onboarding process must be completed.
- Contact Qualys Support (www.qualys.com/support) to request OpenID Connect API authentication activation for your subscription. A CRM ticket is automatically created and is used as a reference and tracking for all discussions concerning the activation.
- Qualys Support replies to the ticket to share and request the required technical information used to enable OIDC. See the Prerequisites for the details.
- Upon receipt of the response, Qualys enables OpenID Connect API authentication support. This process takes approximately one week to complete.
Use OpenID Connect API Authentication
Once the onboarding process is complete and the OpenID Connect API authentication is enabled, you can begin using it. To start using it, generate a JWT token and use it to execute the Qualys APIs. The following subsections provide API request and response samples for generating a JWT token and executing APIs using this token.
The token generation URL may vary depending on the IdP application you are using. The following sample illustrates the request and response for Okta.
API Request
curl --location '
https://qualys.oktapreview.com/oauth2/aus27sviwo8jbrP4T0h8/v1/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'grant_type=password'
--data-urlencode '[email protected]'
--data-urlencode 'password= '
--data-urlencode 'client_id=0oa27l586h672nMy90h8'
--data-urlencode 'scope=openid profile'
Response
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": " ",
"scope": "openid profile",
"id_token": " "
}
API Request
curl--location '<qualys_gateway_url>/cloudview-api/rest/v2/report/assessment/create'
--header 'Authorization: Bearer <access_token from above response>'
Response
{
"reportName": "AWS Assessment Report",
"description": "",
"cloudType": "AWS",
"query": "",
"startDate": "2024-12-03T00:12:53Z",
"endDate": "2024-12-10T18:53:s53Z",
"executionType": "RUN_TIME",
"policyIds": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
],
"tagIds": [
],
"connectorIds": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
],
"format": "csv",
"iacResourceResults": [ ]
}