Onboarding IdP-based Authentication

Prerequisites

To enable OpenID Connect API authentication support, you need to contact Qualys Support. Provide the following information to Qualys Support to get onboarded with IdP-based API authentication:

• Certificates/JWKS URL: You can provide the certificates or JWKS URL in one of the following ways:
  
  Share the Certificates Directly — You can directly share the KIDs and corresponding public signing certificates to be used. The certificates must be in X.509 format (typically .pem or .cer files). You can add up to 5 certificates/public keys for OIDC configuration.
  
  OR
  
  Share the JWKS URL — Confirm if your organization plans to rotate certificates, public keys, or key IDs (KIDs) on a regular basis. If so, provide the JWKS (JSON Web Key Set) URL.

  This URL hosts an organization’s current set of certificates/public keys along with their KIDs. It is usually managed by the IT or Identity team. We will configure this URL in our setup to support IdP-based authentication.

  Once configured, Qualys periodically retrieves the latest keys from the JWKS endpoint, helping maintain up-to-date authentication credentials without requiring manual updates.

• Audience and Issuer Values or JWT Token: The audience and issuer values are important to set up the IdP-based authentication. You can, 
  
  - provide the audience and issuer values directly,
  OR
  - Share a JWT token with us, from which we can extract these values and use them to configure certificates for IdP-based authentication.
• External ID:  The External ID represents the unique identifier assigned to the user by the customer’s IdP. This identifier could be an alphanumeric value, an email address, or any unique ID generated by the IdP. This External ID is stored in the Qualys user management system and is mandatory for mapping the JWT token to the correct user, with the correct permissions. 

  The External ID can be used for Custom Claim support. Refer to Custom Claim for Token-based Authentication to learn more.

Onboarding Steps

To onboard IdP-based API authentication, complete the following onboarding process:

1. Contact Qualys Support to activate IdP-based API authentication your subscription.
2. Qualys Support requests the necessary technical information to enable IdP-based authentication. See the Prerequisites for details.
3. Once we receive the required technical information, we will enable IdP-based API authentication support.

API Authentication Workflow

Once activated, you can leverage password less authentication for Qualys API using an IdP-provided access token. The following is the basic workflow for IdP-based API authentication.

1. Use the Authentication API to generate the JSON Web Token (JWT) for API access.
2. Use this JWT token in the API requests. Qualys verifies if the correct JWT token is provided or not.
3. Upon successful verification, you are allowed to access the Qualys APIs. 

Support for Certificate Rotation

Currently we support certificate, public key, and Key ID (KID) rotation using JWKS URL. If you opt in for certificate rotation, Qualys periodically (every 30 minutes) retrieves the latest certificate, public key, and KID details. This ensures that the authentication is done with the latest credentials.

Enhancement for Certificate Rotation

We have introducesd real-time dynamic JWKS URL rotation. This helps you authenticate using the latest certificates immediately, without waiting for the next scheduled interval for retrieving the authentication credentials.