Configuring KnowBe4 SAML with Keycloak

Overview

While not officially supported in their documentation, KnowBe4 can utilize Keycloak’s SAML endpoints for Single Sign On.

There are, however, a few extra steps in order to get the information both parties need.

Initial Keycloak Configuration

1. Create a new SAML client in your authentication realm

• Set the Client type to SAML
• Set the Client ID to KnowBe4

2. Once created, scroll down to SAML capabilities and set the following:

• Set Name ID format to email
• Enable Force name ID format

3. Scroll down to Signature and Encryption and set the following:

• Enable Sign documents
• Enable Sign assertions

You may leave other settings blank for now, we will collect the information in the following steps

4. We need to collect the following information from our Keycloak server:

• The SAML target for your realm
• The fingerprint of the SAML certificate

SAML Target

1. Navigate to Realm settings
2. Select the General tab
3. Look for Endpoints and click SAML 2.0 Identity Provider metadata
4. Copy the URL of any of the md:SingleSignOnService fields, they are all identical and save this for later

Certificate Fingerprint

1. While still on the XML screen from above, copy the contents of the ds:X509Certificate section to a file, such as /tmp/kc.pem
2. Edit this file to include:

• -----BEGIN CERTIFICATE----- before the certificate data
• -----END CERTIFICATE----- after the certificate data

3. Generate a sha256 fingerprint by running:

• openssl x509 -in /tmp/kc.pem -noout -fingerprint -sha256

4. Copy this fingerprint and save it for later
5. Save your changes

Initial KnowBe4 Configuration

For now, do NOT click Enable SAML SSO, we are not ready for it yet

1. Log into training.knowbe4.com
2. Click on your email in the upper right corner and click on Account Settings
3. Expand Account Integrations and click SAML
4. Enable Allow Account Creation from SAML Login
5. Enter the SAML target URL from earlier into IdP SSO Target URL
6. Set IdP Cert Fingerprint to SHA-256 and paste the fingerprint we generated earlier.
7. Enable Sign SP AuthnRequest
8. Optionally enable Enable SP AuthnRequest Expiration Notifications

• This way you can receive notifications to rotate your client certificates in Keycloak

9. Download the Current AuthnRequest Certificate and save the .cer file for later
10. Copy following URLs and save them for later:

• SSO Sign-in URL
• SSO Sign-out URL
• SSO Callback URL
• Bypass-SSO Login URL

11. Don’t forget to click Save Changes

Followup Keycloak Configuration

Now that we have all the necessary information from KnowBe4, we can finish setting up our Keycloak Client:

1. Navigate back to your KnowBe4 client in Keycloak
2. Under Access Settings, set the following:

• Set Valid redirect URIs to the SSO Callback URL you saved earlier
• Set IDP-Initiated SSO URL name to the SSO Sign-in URL you saved earlier

3. Click to enter the Advanced tab and set the following:

• Set Logout Service Redirect Binding URL to the SSO Sign-out URL you saved earlier

The last thing we need to do is convert and import the certificate we downloaded from Knowbe4 earlier. Before we can upload it to Keycloak, we must convert it from binary DER format to ASCII PEM format:

1. Navigate to where you saved the .cer file from earlier.
2. Convert it to PEM by running the following:

• openssl x509 -in Knowbe4-AuthnRequest-Current-202507221129.cer -inform der -out knowbe4.pem

We can test to ensure the certificate was properly converted by running the following: openssl x509 -in knowbe4.pem -text If successful you should see valid certificate Issuer, Validity, and Subject information. The Certificate at the bottom of the output should also match the text in the Current AuthnRequestCertificate box on KnowBe4

To install the certificate in Keycloak, do the following:

1. Click to enter the Keys tab of your client
2. Ensure Client signature required is checked
3. Click Import Key
4. Set Archive format to Certificate PEM
5. Drag or Browse to the file we generated earlier (knowbe4.pem)
6. Click Import

Both Keycloak and KnowBe4 should now be fully configured for SAML SSO

Testing SSO

We are finally ready to test our SAML Logins to KnowBe4. As a safety precaution, we will use two windows, one will stay logged into the admin console and the other we will use to test SAML.

1. Navigate back to your KnowBe4 SAML settings
2. Open a private browsing window
3. In your non-private window, click Enable SAML SSO
4. Save your changes, DO NOT LOG OUT
5. In your private browser window, navigate to training.knowbe4.com
6. Enter your email address

You should now be redirected to your Keycloak server for login. If all goes well, you can optionally click Disable non-SAML Logins for All Users and log out.

Troubleshooting

While this is certainly not every failure scenario, this should cover the most common SAML issues

Not Redirected to Keycloak

• Make sure the IdP SSO Target URL field is correct in KnowBe4

Keycloak says Invalid Request

Check your Keycloak logs for the following:

WARN  [org.keycloak.events] (executor-thread-35451) type="LOGIN_ERROR", realmId="redacted", clientId="null", userId="null", ipAddress="redacted", error="client_not_found", reason="Cannot_match_source_hash"

• Check your client’s ClientID and make sure it says KnowBe4 or the contents of the Entity ID field on KnowBe4’s SAML settings page

ERROR [org.keycloak.protocol.saml.SamlService] (executor-thread-35451) request validation failed: org.keycloak.common.VerificationException: org.keycloak.common.VerificationException: Invalid query param signature
        at org.keycloak.protocol.saml.SamlProtocolUtils.verifyRedirectSignature(SamlProtocolUtils.java:179)
        at org.keycloak.protocol.saml.SamlProtocolUtils.verifyRedirectSignature(SamlProtocolUtils.java:144)
        at org.keycloak.protocol.saml.SamlService$RedirectBindingProtocol.verifySignature(SamlService.java:818)
        at org.keycloak.protocol.saml.SamlService$BindingProtocol.handleSamlRequest(SamlService.java:304)
        at org.keycloak.protocol.saml.SamlService$BindingProtocol.execute(SamlService.java:702)
        at org.keycloak.protocol.saml.SamlService.redirectBinding(SamlService.java:870)
        at org.keycloak.protocol.saml.SamlService$quarkusrestinvoker$redirectBinding_redacted.invoke(Unknown Source)
        at org.jboss.resteasy.reactive.server.handlers.InvocationHandler.handle(InvocationHandler.java:29)
        at io.quarkus.resteasy.reactive.server.runtime.QuarkusResteasyReactiveRequestContext.invokeHandler(QuarkusResteasyReactiveRequestContext.java:141)
        at org.jboss.resteasy.reactive.common.core.AbstractResteasyReactiveContext.run(AbstractResteasyReactiveContext.java:145)
        at io.quarkus.vertx.core.runtime.VertxCoreRecorder$14.runWith(VertxCoreRecorder.java:576)
        at org.jboss.threads.EnhancedQueueExecutor$Task.run(EnhancedQueueExecutor.java:2513)
        at org.jboss.threads.EnhancedQueueExecutor$ThreadBody.run(EnhancedQueueExecutor.java:1538)
        at org.jboss.threads.DelegatingRunnable.run(DelegatingRunnable.java:29)
        at org.jboss.threads.ThreadLocalResettingRunnable.run(ThreadLocalResettingRunnable.java:29)
        at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
        at java.base/java.lang.Thread.run(Thread.java:840)
Caused by: org.keycloak.common.VerificationException: Invalid query param signature
        at org.keycloak.protocol.saml.SamlProtocolUtils.verifyRedirectSignature(SamlProtocolUtils.java:176)
        ... 16 more

• Make sure that the certificate you uploaded to the Keys section in Keycloak matches the Current AuthnRequest Certificate certificate in KnowBe4

Login Fails after Successful Keycloak Login

• Make sure that the fingerprint you set for IdP Cert Fingerprint is correct