How to Fix Keycloak SAML Protocol Error

In this tutorial, you'll learn about How to Fix Keycloak SAML Protocol Error. We cover key concepts, practical examples, and best practices.

Keycloak SAML authentication returns SAML response validation failed or Invalid assertion — the SAML response from the identity provider does not match Keycloak's expected configuration.

The Problem

ERROR [org.keycloak.protocol.saml] Error processing SAML response:
SAML assertion validation failed: org.keycloak.common.VerificationException:
Signature validation failed for SAML assertion

Step-by-Step Fix

Step 1: Verify signing configuration

In the Keycloak admin console, go to Clients > SAML Client > Settings:

Client Signature Required: ON
Force POST Binding: ON
Force Name ID Format: ON
Sign Documents: ON
Sign Assertions: ON

Step 2: Import IDP metadata

# Download IDP metadata
wget https://idp.example.com/metadata -O /tmp/idp-metadata.xml

Then in Keycloak: Clients > Import > Select File.

Step 3: Configure SAML bindings

SAML Binding: POST Binding
Assertion Consumer URL: https://auth.example.com/realms/myrealm/broker/saml/endpoint

Step 4: Set up encryption

Encrypt Assertions: ON
Encryption Algorithm: AES-256

Step 5: Check audience and issuer

Expected Audience: https://auth.example.com/auth/realms/myrealm
Issuer: https://idp.example.com/metadata

Step 6: Test SAML login

curl -v "https://auth.example.com/realms/myrealm/protocol/saml?SAMLRequest=ENCODED_REQUEST"

Prevention Tips

• Export and compare IDP metadata regularly
• Use signed SAML assertions for security
• Validate signature algorithms match between IDP and Keycloak
• Test SAML flow with different browsers to rule out cache issues

Common Mistakes with saml error

1. Non-exhaustive pattern matches that compile with warnings then crash at runtime
2. Misunderstanding that String is [Char] with poor performance for large text operations
3. Using foldl instead of foldl' causing stack overflow on large lists

These mistakes appear frequently in real-world KEYCLOAK code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ