Custom Claim for Token-based Authentication

We have introduced Custom Claim Support for token-based authentication. This enhancement gives customers greater flexibility in mapping their identity provider (IdP) users to Qualys users, particularly for IdPs such as Azure Active Directory that do not allow customization of the sub claim in JWT tokens.

This feature is applicable to all Qualys products that have implemented IdP-based authentication.

How It Works

During onboarding, customers provide Qualys with certificates (or a JWK URL), an Audience, and an Issuer value to establish the IdP integration. For user authentication, Qualys maps each incoming token to a Qualys user by matching the value of the JWT sub claim against the External ID field of the corresponding Qualys user.

With the Custom Claim Support enhancement, you can now optionally specify an alternative JWT claim, such as preferred_username, at the time of onboarding. When provided, Qualys uses this custom claim value for the External ID mapping instead of the default sub claim.

Behavior Details

Custom Claim offers the following behavior:

• Optional configuration: Providing a custom claim is not mandatory. If no custom claim is specified during onboarding, Qualys continues to use the sub claim for External ID mapping.

• User-scoped applicability: The custom claim configuration applies only to the specific users who provides it. Other users continue to use the sub claim by default.

• Fallback to sub claim: If the specified custom claim is present in the token but contains no value, or if the claim is absent from the token entirely, Qualys automatically falls back to the sub claim for the External ID lookup. Authentication is not failed in absebse of custom claim.

• Supported IdPs: This feature is especially relevant for users using Azure Active Directory, which does not permit customization of the sub claim. Users can designate an alternate claim (for example, preferred_username) to use as the External ID mapping key.

Onboarding Requirements

To use a custom claim, provide the following information to Qualys Support when onboarding IdP-based authentication:

• Certificate or JWK URL

• Audience Value

• Issuer Values

• Custom claim name (optional): The name of the JWT claim to use for External ID mapping (for example, preferred_username).
  
  Ensure that the External ID of each Qualys user is set to the value that will appear in the specified custom claim in their JWT token. For example, if preferred_username is configured as the custom claim, the External ID for each Qualys user must match the value of preferred_username in that user's token.