Setting up OIDC access control

This section provides instructions on how to integrate OpenID Connect (OIDC) with your Klocwork application. This setup will enable users to log in to Klocwork using their existing credentials from an OIDC identity provider (IdP).

When you switch to OIDC from another authentication method, all of your current users will be removed. We strongly recommend backing up the projects_root/permissions_data folder before switching.

Prerequisites

Before starting the OIDC integration, ensure you have the following:

  • An active OIDC identity provider (IdP) (for example, Google or Microsoft Entra)

  • Administrative access to both the Validate Server and the OIDC IdP

  • The necessary information and metadata from the IdP (for example, Client ID, Client Secret, Authorization Endpoint, Token Endpoint, and UserInfo Endpoint)

  • Version 24.2 or newer of kwauth from one of the following packages: kwauthtools, kwbuildtools, or the kw-cmd-installer found in kw-desktop-tools. See Installing the Auth Tools package.

When setting up a secure connection (SSL) with OIDC, it is best practice to configure and test your SSL connection before setting up OIDC. This approach reduces the number of potential failure points. See Enabling SSL for SAML or OIDC authentication.

Step 1: Select user provisioning method and administrator account

To select your user provisioning method, edit the /projects_root/config/admin.conf file or run kwauthconfigw, adding or choosing the following attribute:

user.manager=modern-jit OR modern-pp

where:

  • modern-jit is modern authentication with just-in-time provisioning, where user accounts are created automatically when your user logs in for the first time through an IdP.

    Choose this option if you would like to have Validate automatically create users after they successfully authenticate. If you choose this method, you only need to add users in your IdP.

  • modern-pp is modern authentication for pre-provisioned accounts.

    Choose this option if you would like to explicitly add new users and configure groups or permissions using Validate's integrated user management tools. If you choose this method, you will need to add new users to both Validate and your IdP.

To set the administrator account, add the following to admin.conf:
init.admin.name=<user>

where:<user> is the user to be granted administrator privileges

For example, if you are using your company's IdP credentials, set init.admin.name=janedoe@company.com

Save the changes.

Make sure to add an administrator account when selecting modern-pp, as you won't be able to log in with any other user until you add it to Validate.

Step 2: Add Klocwork to your identity provider

To configure Klocwork on your OIDC IdP:

  1. Log in to your IdP's administration console.

  2. Create an OIDC application for Klocwork. Provide the following details:

    • A redirect URL to your Validate server, for example:

      https://{your-server-host}:{port}/kwauthgateway/login/oauth2/code/{custom-idp-registration-id}

If your IdP is secured by SSL and uses a self-signed certificate, add the certificate to your environment to ensure Validate can communicate with the IdP.

Step 3: Configure OIDC authentication on the Validate Server

Add the following parameters, either through kwauthconfigw or by creating a file named auth.properties in /projects_root/config/.

Example configuration for Azure or Keycloak

Copy
kw.authFramework=openid
kw.userIdAttribute=preferred_username
kw.userDnAttribute=name
kw.openid.prompt=login

spring.security.oauth2.client.provider.{custom-idp-registration-id}.issuer-uri={https://login.microsoftonline.com/aaaaaa-bbbbb-1234/v2.0 | https://my.keycloak.com/realms/my-realm
spring.security.oauth2.client.registration.{custom-idp-registration-id}.client-id={client-id-provided-by-idp}
spring.security.oauth2.client.registration.{custom-idp-registration-id}.client-secret={client-secret-provided-by-idp}
spring.security.oauth2.client.registration.{custom-idp-registration-id}.scope=openid,email,profile

Example configuration for Google, GitHub, Facebook, or Okta

Copy
kw.authFramework=openid
kw.userIdAttribute=preferred_username
kw.userDnAttribute=name
kw.openid.prompt=login

spring.security.oauth2.client.registration.{google|github|google|facebook|okta}.client-id={client-id-provided-by-idp}
spring.security.oauth2.client.registration.{google|github|google|facebook|okta}.client-secret={client-secret-provided-by-idp}
Parameter Description Example
Framework The framework for your authentication, in this case, openid kw.authFramework=openid
User ID attribute SAML/OIDC principal attribute key used to retrieve the attribute value that maps to a Validate user name kw.userIdAttribute=preferred_username
Display Name attribute The display name in Validate kw.userDnAttribute=name
Issuer URI The authorization server, preceded by security attributes

spring.security.oauth2.client.provider.keycloak.issuer-uri=https://your_klocwork_server.com/realms/kwrealm/

Client ID The OAuth 2.0 Client Identifier valid at the authorization server, preceded by security attributes spring.security.oauth2.client.registration.keycloak.client-id=kwopenid
Client secret The Client secret from your IdP, preceded by security attributes spring.security.oauth2.client.registration.keycloak.client-secret=jgp0ZFerrHsHGaT9H8FHL9tNv7fyoA4b
Scope The OAuth 2.0 scope, preceded by security attributes and openid. Available values: profile, email, address, phone, offline_access. See Requesting Claims using Scope Values and Offline Access spring.security.oauth2.client.registration.keycloak.scope=openid profile
Authorization grant type The OAuth 2.0 authorization grant type, preceded by security attributes spring.security.oauth2.client.registration.keycloak.authorization-grant-type=authorization_code
Redirect URI (Optional) The redirect URI, preceded by security attributes spring.security.oauth2.client.registration.keycloak.redirect-uri=http://localhost:${KW_PORT}/kwauthgateway/login/oauth2/code/kwopenid
Request expiry (Optional) The maximum duration for device authorization flow, in seconds kw.RequestExpirySeconds=180
Prompt (Optional) Behavior for authentication and consent process. Available values: none, login, consent, select_account. See Authentication Request kw.openid.prompt=none

Step 4: Test your OIDC integration

To test the OIDC integration:

  1. Restart your Validate server.

  2. Open Validate browser and click on the Login button. You should be redirected to your IdP for authentication.

  3. Follow the device authorization flow for OIDC authentication.

After authenticating with the IdP, you should be redirected back to Validate and logged in automatically.

Troubleshooting

Here are some common error messages you may encounter during setup, and how to fix them:

  • "Unable to find valid certification path to requested target": Your IdP is using a self-signed certificate. Please add the certificate to your environment so Validate can use it to communicate with the IdP.

  • "Signing credentials must not be empty when authentication requests require signing": The IdP requires signing and the certificates have not been included in the configuration.

  • "Unsupported authentication framework specified in configuration": Framework is not configured. Ensure that kw.authFramework is set to saml or openid in your auth.properties file.

  • If you encounter issues when configuring your IdP settings in Validate, it might be useful to turn on IdP debug logging. This will provide extended information that can assist in troubleshooting.

    Do not forget to turn off debug logging in production as it could leak sensitive information as well as consume a large amount of disk space.

    To turn on IdP debug logging, choose one of the following methods:

    • Set the KW_DEBUG environment variable to true and set the logging level for kwauthgateway to debug.

    • In the auth.properties file, set kw.debugAttributes to true. This setting allows you to see a text representation of the attributes returned from the IdP, helping you determine which one to use as kw.userIdAttribute. Keep in mind that while kw.debugAttributes=true, the server will not be usable because you won't be able to log in.

More information

To enable SSL for OIDC, see Enabling SSL for SAML or OIDC authentication