Onboarding OpenID Connect

Prerequisites

To enable OpenID Connect API authentication support, provide the following information to Qualys Support:

• 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 provide 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 OAuth-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 initiated password-less API 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 password-less authentication.

The OAuth currently supports mapping an external ID to only a single user.

Onboarding Steps

To start using OpenID Connect API authentication, the following onboarding process must be completed:

1. Contact Qualys Support to request OpenID Connect API authentication activation for your subscription.
2. Qualys Support requests the necessary technical information to enable OIDC. See the Prerequisites for details.
3. Once we receive the required technical information, we will enable OpenID Connect API authentication support.

Authentication Workflow using OIDC

Once the OIDC Authentication is activated for your account, you can leverage password less authentication for Qualys API using an Identity Provider (IdP). The following are the basic authentication workflow with OIDC.

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.

Planned Enhancement for Certificate Rotation

In the upcoming release, we plan to introduce real-time dynamic JWKS URL rotation. This will help you authenticate using the latest certificates immediately, without waiting for the next scheduled interval for retrieving the authentication credentials.