Setting up SAML access control
In this topic: |
This section provides instructions on how to integrate SAML (Security Assertion Markup Language) with your Klocwork application. This setup will enable users to log in to Klocwork using their existing credentials from a SAML identity provider (IdP).
projects_root/permissions_data
folder before switching.Prerequisites
Before starting the SAML integration, ensure you have the following:
-
An active SAML identity provider (IdP) (for example, Keycloak, Okta, or Github)
-
Administrative access to both the Validate Server and the SAML IdP
-
The necessary information from the IdP (for example, SAML metadata as URL, or xml-file and entity-id for the Klocwork application)
-
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 SAML, it is best practice to configure and test your SSL connection before setting up SAML. This approach reduces the number of potential failure points. See Enabling SSL for SAML or OIDC authentication.
Step 1: Add Klocwork to your identity provider
To configure Klocwork on your SAML IdP:
-
Log in to your IdP's administration console.
-
Create a new SAML application for Klocwork. Provide the following details:
-
An entity or client ID for the application, for example:
kwsaml
-
Your Assertion Consumer Service (ACS) URL, for example:
https://your_klocwork_server.com/kwauthgateway/login/saml2/sso/{your-custom-idp-registration-id}
-
-
Configure certificates. Generate an RSA private key and a X.509 Certificate signed with that key. An example is as follows:
openssl genpkey -algorithm RSA -out private-key.pem openssl req -new -x509 -key private-key.pem -out certificate.crt -days 365 openssl pkcs12 -export -out certificate.pfx -inkey private-key.pem -in certificate.crt (importable pfx certificate)
Then, import the certificate to your IdP.
-
Configure attribute mapping. Ensure that the IdP is configured to include an attribute that can be used as a Validate user name in its SAML response (such as user name or email)
-
Save the configuration.
Step 2: 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.
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.
modern-pp
, as you won't be able to log in with any other user until you add it to Validate.Step 3: Configure SAML authentication on the Validate Server
Add the following parameters, either through kwauthconfigw or by creating a file named auth.properties
in /projects_root/config/
.
In the next example, replace the {custom-idp-registration-id} with the last part of your ACS URL (for instance, https://your_klocwork_server.com/kwauthgateway/login/saml2/sso/{your-custom-idp-registration-id}
), and substitute private-key.pem and certificate.crt with the private key and certificated generated in Step 1.
kw.authFramework=saml
kw.userIdAttribute={SAML attribute key for username data}
kw.userDnAttribute={SAML attribute key for display name data}
kw.saml.force_authn=true
spring.security.saml2.relyingparty.registration.{custom-idp-registration-id}.assertingparty.metadata-uri = {SAML metadata URL or metadata XML path} i.e https://login.microsoftonline.com/abc-def-xyz-321/federationmetadata/2007-06/federationmetadata.xml?appid=qwe-asd-zxc-123
spring.security.saml2.relyingparty.registration.{custom-idp-registration-id}.entity-id = {your entity or client id}
spring.security.saml2.relyingparty.registration.{custom-idp-registration-id}.signing.credentials[0].private-key-location=file:${PROJECTS_ROOT}/auth/private-key.pem
spring.security.saml2.relyingparty.registration.{custom-idp-registration-id}.signing.credentials[0].certificate-location=file:${PROJECTS_ROOT}/auth/certificate.crt
Parameter | Description | Example |
---|---|---|
Framework | The framework for your authentication, in this case, SAML | kw.authFramework=saml |
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 |
Metadata URI | Points to an XML file that contains important configuration information about the IdP. This information includes the IdP's public keys, endpoints, and other settings required for establishing a secure SAML authentication flow. | spring.security.saml2.relyingparty.registration.kwrealm.assertingparty.metadata-uri=https://your_klocwork_server.com/realms/kwrealm/protocol/saml/descriptor |
Entity ID | The Entity ID that you have specified in your IdP, preceded by security attributes | spring.security.saml2.relyingparty.registration.kwrealm.entity-id=kwsaml |
Private key location | The location of the private key, preceded by security attributes | spring.security.saml2.relyingparty.registration.kwrealm.signing.credentials[0].private-key-location=file:${PROJECTS_ROOT}/auth/local.key |
Certificate location | The location of the certificate, preceded by security attributes | spring.security.saml2.relyingparty.registration.kwrealm.signing.credentials[0].certificate-location=file:${PROJECTS_ROOT}/auth/local.crt |
Request expiry | (Optional) The maximum duration for device authorization flow, in seconds | kw.RequestExpirySeconds=180 |
Force authentication | (Optional) Prompt the user to re-enter their credentials (such as user name and password) regardless of any existing authentication session. The default is true. | kw.saml.force_authn=true |
Passive SAML | (Optional) Specifies whether the authentication request should be "passive," meaning the IdP should not interact with the user. The default is false, meaning the IdP must not proceed with authentication if it requires user interaction (such as prompting for credentials). | kw.saml.is_passive=false |
Step 4: Test your SAML integration
To test the SAML integration:
-
Restart your Validate server.
-
Open Validate browser and click on the Login button. You should be redirected to your IdP for authentication.
-
Follow the device authorization flow for SAML 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 tosaml
oropenid
in yourauth.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 forkwauthgateway
todebug
. -
In the
auth.properties
file, setkw.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 askw.userIdAttribute
. Keep in mind that whilekw.debugAttributes=true
, the server will not be usable because you won't be able to log in.
-
More information
To enable SSL for SAML, see Enabling SSL for SAML or OIDC authentication