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, you must first generate the JWT token and then use that token to execute the Qualys APIs.
The following samples illustrate generating a JWT token and using that JWT token to access the Qualys APIs.
Sample: Generate JWT Token for API AuthenticationSample: Generate JWT Token for API Authentication
The following sample illustrates generating JWT tokens required for accessing Qualys APIs.
API Request
curl --location '<<token generation url>>' JWT Token
--header 'Content-Type: application/x-www-form-urlencoded' JWT Token
--data-urlencode 'grant_type=password' JWT Token
--data-urlencode 'username=<<Qualys_okta_sandbox_user_id>>' JWT Token
--data-urlencode 'password=<<Qualys_okta_sandbox_password>>' \
--data-urlencode 'client_id=<<Qualys_okta_sandbox_application_client_id>>' \
--data-urlencode 'scope=openid profile'
The token generation URL may vary based on the IdP application you are using.The sample below illustrates the request and response for Okta.
API Response
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "<JWT token value",
"scope": "profile openid",
"id_token": "<JWT token value>"
}
Sample: OIDC Authentication for Cloud Platform APIsSample: OIDC Authentication for Cloud Platform APIs
The following sample illustrates using JWT tokens generated by OIDC authentication to access Cloud Platform APIs.
API Request
curl --location --request POST 'https:// <qualys_base_url>/api/2.0/fo/asset/ip/?action=add&enable_vm=1&ips=10.10.30.10&echo_request=1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer<JWT token value>\
--header 'X-Requested-With: curl Autodemo' \
--header 'Accept: */*' \--header 'Content-Length: 0'
API Response
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<REQUEST>
<DATETIME>2024-11-06T07:32:58Z</DATETIME>
<USER_LOGIN>john_doe</USER_LOGIN>
<RESOURCE>https://
<qualys_base_url>/api/2.0/fo/asset/ip/
</RESOURCE>
<PARAM_LIST>
<PARAM>
<KEY>action</KEY>
<VALUE>add</VALUE>
</PARAM>
<PARAM>
<KEY>enable_vm</KEY>
<VALUE>1</VALUE>
</PARAM>
<PARAM>
<KEY>ips</KEY>
<VALUE>10.11.11.11</VALUE>
</PARAM>
<PARAM>
<KEY>echo_request</KEY>
<VALUE>1</VALUE>
</PARAM>
</PARAM_LIST>
</REQUEST>
<RESPONSE>
<DATETIME>2024-11-06T07:33:05Z</DATETIME>
<TEXT>IPs successfully added to Vulnerability Management</TEXT>
</RESPONSE>
</SIMPLE_RETURN>
Sample: OIDC Authentication for Cloud Agent APIsSample: OIDC Authentication for Cloud Agent APIs
The following sample illustartes using JWT token genrated by OIDC authentication to access Cloud Agent APIs.
API Request
curl --location <qualys_base_url>/caui/v1/config-profiles/1790796' \
--data'
Set the authorization type to Bearer token and enter the JWT token value generated using the token generation API.
API Response
{
"id": 1234567,
"customerId": 7654321,
"basicDetails": {
"profileName": "Configuration profile with tag55",
"defaultProfSubscription": false,
"suspendDataCollection": false,
"inMemorySQLite": false,
"enableQgs": false,
"preventAutoUpdate": false,
"spf": {
"spfEnabled": false
}
},
"assignCloudAgent": {
"tagSet": {
"tagSetId": "12345a6b-7c8d-91e2-3456-7f8a9b1234c5",
"includeMatchType": "ANY",
"includedTags": [
{
"inScope": true,
"tagId": 3456789,
"name": "mmm"
}
]
}
},
"scanConfiguration": {
"vm": {
"dataCollectionInterval": 240,
"scanDelay": 0,
"scanRandomize": 0,
"scanOnStartup": false
},
"pc": {
"dataCollectionInterval": 720,
"scanDelay": 0,
"scanRandomize": 0
},
"sca": {
"dataCollectionInterval": 2160
}
},
.......
.......
.......
"performance": {
"isCustomized": false,
"performanceBasedOn": "LOW",
"customizedSettings": {
"agentStatusInterval": 900,
"deltaUploadInterval": 10,
"chunkSizeForFile": 1024,
"upgradeReattemptInterval": 64800,
"loggingLevelForAgent": "VERBOSE",
"priorityStatusUploadInterval": 60,
"cpuLimit": 2,
"cpuThrottle": 20
},
"securitySettings": {
"vmScanMode": "AGENTUSER"
}
}
}
Sample: OIDC Authentication for Container Security APIsSample: OIDC Authentication for Container Security APIs
The following sample illustrates using JWT token generated by OIDC authetication to access Container Security APIs.
API Request
curl -X GET
'<qualys_base_url>/csapi/v1.3/containers?pageNumber=1&pageSize=50&sort=created%3Adesc' \
--header 'Authorization: Bearer <access_token from above response>' \
--header 'Content-Type: application/json'
API Response
{
"data": [
"imageId": "b798104c002a",
"created": "1721713977000",
"updated": "1721714109665",
"sha":
"d838bcb622a003b767ace31039475f37a5d34f093f8de82a71536f3fcfcb839e",
"uuid": "051a684a-9bad-3cb1-bf28-91084ee6e024",
"name": "test-vul-propogation",
"host": null,
"state": "DELETED",
"imageUuid": "fbdc0a10-7186-3439-8712-2db20df179e6",
"containerId": "d838bcb622a0",
"stateChanged": "1721714102790",
"lastVmScanDate": null,
"isRoot": null,
"vulnerabilities": {
"severity5Count": null,
"severity3Count": null,
"severity4Count": null,
"severity1Count": null,
"severity2Count": null
},
"exceptions": null,
{
"riskScore": 258,
"riskScoreCalculatedDate": "1723567125904",
"formulaUsed": "MIN (1000 , 2 * ( 1.0 * 64.70 * Pow(10,0.01) + 0.6 * 60.04 * Pow(26,0.01) + 0.4 * 44.35 * Pow(147,0.01) + 0.2 * 36.20 *Pow(5,0.01) ))",
"maxQdsScore": 95,
"qdsSeverity": "CRITICAL",
}
"scanTypes": null,
"cluster":
{
"name": "kubernetes-admin",
"uid": "bdc0d232-38af-46f9-b188-06cb61c928af"
},
"criticality": 3,
"criticalityUpdated": "1717098843553",
"compliance": {
"failCount": 0,
"passCount": 0,
"errorCount": 0
},
"lastComplianceScanDate": null
},
],
"count": 1
}
Sample: OIDC Authentication for Certificate View APIsSample: OIDC Authentication for Certificate View APIs
The following sample illustartes accessing Certificate View (CertView) APIs using JWT token generated by OIDC authentication.
API Request
curl -X POST
"<qualys_base_url>/certview/v1/certificates"
-H "Accept: application/json"
-H "Content-Type: application/json"
-d "{ \"filter\" : \"subject.name:www.qualys.com\", \"pageNumber\": 0, \"pageSize\" : 1}"
-H "Authorization: Bearer <access_token from above response>"
API Response
{
"keySize": 2048,
"subject": {
"organization": "Qualys, Inc.",
"locality": "Foster City",
"name": "www.qualys.com",
"state": "California",
"country": "US",
"organizationUnit": []
},
"validFrom": 1676246400000,
"signatureAlgorithm": "SHA256withRSA",
"issuer": {
"organization": "DigiCert Inc",
"organizationUnit": [
"www.digicert.com"
],
"name": "DigiCert SHA2 Extended Validation Server CA",
"country": "US",
"state": "",
"certhash": "403e062a2653059113285baf80a0d4ae422c848c9f78fad01fc94bc5b87fef1a",
"locality": ""
},
"rootissuer": {
"organization": "DigiCert Inc",
"organizationUnit": [
"www.digicert.com"
],
"name": "DigiCert High Assurance EV Root CA",
"country": "US",
"state": "",
"certhash": "7431e5f4c3c1ce4690774f0b61e05440883ba9a01ed00ba6abd7806ed3b118cf",
"locality": ""
},
"instanceCount": 2,
"dn": "CN=www.qualys.com, O=\"Qualys, Inc.\", L=Foster
City, ST=California, C=US, serialNumber=3152140,
businessCategory=Private Organization, StateOrProvince=Delaware,
CountryName=US","certhash": "192a86240c5ec5d87dd108f17e2543e78439101f193c99c53193f60d115b885d",
"assets": [
{
"netbiosName": "",
"assetId": "99f29795-4c11-49e1-8898-82e9982b0710",
"name": "qualys.com",
"operatingSystem": "NetScaler",
"tags": [
{
"name": "Internet Facing Assets",
"uuid": "d2ba3be1-66a3-4d1f-89fadd534a2bccc1"
}
],
"primaryIp": "64.39.xx.xxx",
"hostInstances": [
{
"protocol": "tcp",
"sslProtocols": [
"TLSv1.2"
],
"port": 443,
"grade": "A",
"service": "http",
"vulnerabilities": [],
"vulnCount": 0
}
],
"created": 1680247510486,
"updated": 1680247131000,
"assetInterfaces": [
{
"hostname": "qualys.com",
"address": "64.39.xx.xxx"
}
],
"certificateCount": 0
},
{
"netbiosName": "",
"assetId": "646c7aa5-cfdc-4294-bea7-d43664ac03f4",
"name": "www.qualys.com",
"operatingSystem": "NetScaler",
"tags": [
{
"name": "Internet Facing Assets",
"uuid": "d2ba3be1-66a3-4d1f-89fadd534a2bccc1"
}
],
"primaryIp": "64.39.xx.xxx",
"hostInstances": [
{
"protocol": "tcp",
"sslProtocols": [
"TLSv1.2"
],
"port": 443,
"grade": "A",
"service": "http",
"vulnerabilities": [],
"vulnCount": 0
}
],
"created": 1675158036000,
"updated": 1680254412000,
"assetInterfaces": [
{
"hostname": "www.qualys.com",
"address": "64.39.xx.xxx"
}
],
"certificateCount": 0
}
],
"selfSigned": false,
"validTo": 1707868799000,
"issuerCategory": "DigiCert SHA2 Extended Validation Server
CA","subjectAlternativeNames": {
"DNS Name": [
"www.qualys.com",
"qualys.com",
"docs.qualys.com",
"qualys.dk",
"qualys.us",
"qualys.de",
"qualys.biz",
"nemeannetworks.com",
"qualys.fr",
"www.qualys.eu",
"qualys.io",
"qualysguard.tw",
"www.securityvibes.co.uk",
"qualys.es",
"qualysblog.net",
"qualys.nl",
"qualys.report",
"qualysinsight.com",
"qualysworks.net",
"qualysguard.eu",
"qualysguard.com",
"qualys.eu",
"www.qualysguard.eu"
],
"IP Address": null
},
"lastFound": 1680256864611,
"extendedValidation": true,
"sources": [
"VM",
"QAGENT"
]
}
]
Sample: OIDC Authentication for VMDR OT APIsSample: OIDC Authentication for VMDR OT APIs
The following sample illustartes using JWT token generated by OIDC authentication to access VMDR OT APIs.
API Request
curl --location '
<qualys_base_url>/ot/v1/host/list?filter=asset.assetUuid%3A%22af338503-ce5a-376b-b337-1ed9958abc8f%22'
--header 'Authorization: Bearer <access_token from above response>'
API Response
{
"assets": [
{
"name": "<asset_name>",
"address": "<IP_address>",
"hardware": {
"category2": <category2>,
"vendor": "<vendor_name>",
"model": "<model>",
"class": "Unknown"
},
"interfaces": [
{
"address": "<IP_address>",
"firstSeen": "2024-10-04T08:04:20.308Z",
"lastSeen": "2024-10-04T08:04:20.308Z"
}
],
"assetId": <Asset_id>,
"tags": [
{
"tagId": <tag_id>,
"name": "<tag_name>"
},
],
"lastUpdated": "2024-10-04T08:04:20.308Z",
"created": "2024-10-04T08:04:20.308Z",
"firmwareVersion": "<version>",
"purdueLevel": "Unknown",
"assetUuid": "<asset_uuid>",
"serialNumber": "<serial_number>",
"inventory": {
"fileHash": "<filehash>",
"fileName": "<file_name>",
"source": "Industrial OCA"
},
"operatingSystem": "<operating_system>",
"qAssetId": <qasset_id>
}
]
}
Sample: OIDC Authentication for EDR APIsSample: OIDC Authentication for EDR APIs
The following sample illustrates using a JWT Token generated by OIDC authentication to access the EDR APIs.
API Request
curl --location --request GET
"<qualys_base_url>/ioc/events/scroll?filter=type:MUTEX --header "
Authorization: <JWT_Token>"
API Response
{
"data": [
{
"dateTime": "2020-08-17T04:15:06.000+0000",
"process": {
"fullPath": "C:\\Program Files\\WindowsApps\\Microsoft.Windows.Photos_2022.30120.12007.0_x64__8wek
yb3d8bbwe\\Microsoft.Photos.exe",
"parentProcessName": "svchost.exe",
"processFile": {
"fullPath": "C:\\Program Files\\WindowsApps\\Microsoft.Windows.Photos_2022.30120.12007.0_x64__8wek
yb3d8bbwe\\Microsoft.Photos.exe",
"path": "C:\\Program Files\\WindowsApps\\Microsoft.Windows.Photos_2022.30120.12007.0_x64__8wek
yb3d8bbwe",
"sha256":"xa9xxx5a9aaxxxxx36e721exxx7d00aa2438xxd800xxxxx172axxx2f8xxx88a",
"size": 756736,
"moduleName": "Microsoft.Photos.exe",
"md5": "3d8bxxxea865fxxx6d755bxxxd67aaca"
},
"processEventId": "RTP_xxxx0e2f-4ea0-3xx2-xxx0-9cxxxx60e227_17-1-2023",
"processName": "Microsoft.Photos.exe",
"elevated": true,
"parentPid": 912,
"arguments": "-ServerName:App.AppXzst44mncqdg84v7sv6p7yznqwssy6f7f.mca",
"pid": 6008,
"parentEventId": "RTP_2xxxxxe0-xxx4-3xx7-8xxx-eaxxxxxfe0x4_11- 1-2023",
"userName": "DESKTOP-SF6JTIO\\Administrator",
"integrityLevel": "ML_LOW"
},
"eventProcessedTime": "2023-01-17T02:41:25.383+0000",
"eventSource": "EDR",
"mutex": {
"mutexName": "\\Sessions\\2\\AppContainerNamedObjects\\S-1-15-2-222XXXX697-XXXXX7180-2301XXX-42489XXXXX-2024719031-23XXXXX081- 291XXXXXX\\SessionImmersiveColorMutex"
},
"indicator2": [
{
"score": "0",
"sha256": "xa9xxx5a9aaxxxxx36e721exxx7d00aa2438xxd800xxxxx172axxx2f8xxx88a",
"verdict": "KNOWN",
"rowId": "4184411994868091297"
}
],
"type": "MUTEX",
"score": "0",
"md5": "3xxxxxxxxx5fad7xxxxxxxx6d67xxxx"
},
"processEventId": "RTP_xxxx0e2f-4ea0-3xx2-xxx0-9cxxxx60e227_17-1-2023",
"processName": "Microsoft.Photos.exe",
"elevated": true,
"parentPid": 912,
"arguments": "-ServerName:App.AppXzst4xxxcqdxxxxxyznqwsxxx7f.mca",
"pid": 6008,
"parentEventId": "RTP_2xxxxxe0-xxx4-3xx7-8xxx-eaxxxxxfe0x4_11-1-2023",
"userName": "xxxx-xxxxx\\Administrator",
"integrityLevel": "ML_LOW"
},
"eventProcessedTime": "2023-01-17T02:41:25.383+0000",
"eventSource": "EDR",
"mutex": {
"mutexName": "\\Sessions\\2\\AppContainerNamedObjects\\S-1-15-2-2226957697-3030467180-2301525-4248967783-2024719031-2325529081-2915787518\\SM0:6008:120:WilError_03"
},
"indicator2": [
{
"score": "0",
"sha256":"xa9xxx5a9aaxxxxx36e721exxx7d00aa2438xxd800xxxxx172axxx2f8xxx88a",
"verdict": "KNOWN",
"rowId": "-744512xxxxxxx98913"
}
],
"type": "MUTEX",
"score": "0",
"scoreSource": "REVERSING_LAB",
"action": "RUNNING",
"id": "RTM_bxxx1397-4xxx-3xxc-xxx9-xx2f0xxx8axx_17-1-2023",
"asset": {
"fullOSName": "Microsoft Windows 10 Enterprise 10.0.19044 Build 19044",
"hostName": "xxxx-xxxx",
"agentId": "xxxa98xx-xxx5-4xx8-8xx3-xxxd76xx02x",
"interfaces": [
{
"macAddress": "XX:XX:XX:XX:XX:XX",
"ipAddress": "XX.XXX.XXX.X",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection",
"gatewayAddress": "XX.XXX.XXX.X"
}
],
"netBiosName": "xxxx-xxxx",
"isQuarantineHost": false,
"customerId": "xxxcade1-6xx5-xxx1-8xxx-xx008f55xxx3",
"platform": "Windows",
"assetType": "HOST",
"tags": [
{
"name": "Cloud Agent",
"uuid": "xxx676fe-cxxx-4xxx-xx5f-xx48xxcxxx1b"
}
]
},
"uniqueId": "-xxxx1xx6xxx27xxxx1x"
}
]