1. Clone / copy the source/ directory into your Java project workspace, or reference the pre-built JARs from Maven Central.

2. Build from source (if not using Maven Central):

   cd source/
   mvn clean install -DskipTests
   

3. Add to your application POM (see XML above in Required dependencies).

4. Place keycloak-saml.xml (your SP configuration) at WEB-INF/keycloak-saml.xml in your WAR, or provide it via SamlConfigResolver.

5. Register the authentication filter in WEB-INF/web.xml:

   <filter>
     <filter-name>Keycloak SAML Filter</filter-name>
     <filter-class>org.keycloak.adapters.saml.servlet.SamlFilter</filter-class>
   </filter>
   <filter-mapping>
     <filter-name>Keycloak SAML Filter</filter-name>
     <url-pattern>/*</url-pattern>
   </filter-mapping>
   

6. Environment / config: Set IDP metadata URL or inline the IDP certificate. All configuration lives in keycloak-saml.xml; no environment variables are required beyond standard JVM args.

7. Wildfly users: Install the SAML adapter zip on the server and add <secure-deployment> to standalone.xml.

Public API

The following symbols are visible in the source file listing. No excerpts were provided, so documentation is based on class names and package structure as they appear in the file tree.

SamlDeployment

// org.keycloak.adapters.saml.SamlDeployment
public interface SamlDeployment {
    IDP getIDP();
    SP getSP();
    // binding, name ID format, role mappings provider, etc.
}

Central configuration object representing a fully parsed SAML SP deployment. Use this to access IDP endpoint URLs, signing keys, SP entity ID, and assertion consumer service URLs after parsing keycloak-saml.xml.

SamlDeploymentContext

// org.keycloak.adapters.saml.SamlDeploymentContext
public class SamlDeploymentContext {
    public SamlDeploymentContext(SamlDeployment deployment);
    public SamlDeployment resolveDeployment(HttpFacade facade);
}

Holds and resolves the SamlDeployment for the current request. Pass a SamlConfigResolver implementation to support multi-tenant SAML configurations resolved per-request.

DeploymentBuilder

// org.keycloak.adapters.saml.config.parsers.DeploymentBuilder
public class DeploymentBuilder {
    public SamlDeployment build(
        InputStream is,
        ResourceLoader resourceLoader
    ) throws ParsingException;
}

Parses a keycloak-saml.xml input stream into a SamlDeployment. Use this in custom bootstrap code outside of a servlet container to programmatically load SAML configuration.

SamlAuthenticator

// org.keycloak.adapters.saml.SamlAuthenticator
public abstract class SamlAuthenticator {
    public AuthOutcome authenticate();
    protected abstract void assertionHandler(SamlSession session);
}

The primary authentication orchestrator. Extend this class to plug the SAML authentication flow into a custom HTTP framework. It drives the redirect/POST bindings, response validation, and session creation lifecycle.

RoleMappingsProvider

// org.keycloak.adapters.saml.RoleMappingsProvider
public interface RoleMappingsProvider {
    Set<String> mapRoles(
        String principalName,
        Set<String> roles
    );
}

SPI for translating SAML assertion roles into application roles. Implement this interface and register via roleMappingsProvider config in keycloak-saml.xml to customize role translation logic.

Working examples

Scenario - Parse keycloak-saml.xml programmatically

Load and inspect a SAML deployment configuration at application startup without a servlet container.

import org.keycloak.adapters.saml.config.parsers.DeploymentBuilder;
import org.keycloak.adapters.saml.config.parsers.ResourceLoader;
import org.keycloak.adapters.saml.SamlDeployment;

import java.io.InputStream;

public class SamlConfigLoader {
    public static SamlDeployment load() throws Exception {
        InputStream is = SamlConfigLoader.class
            .getResourceAsStream("/keycloak-saml.xml");

        ResourceLoader loader = resource ->
            SamlConfigLoader.class.getResourceAsStream(resource);

        DeploymentBuilder builder = new DeploymentBuilder();
        SamlDeployment deployment = builder.build(is, loader);

        System.out.println("SP Entity ID: " + deployment.getEntityID());
        System.out.println("IDP SSO URL:  " +
            deployment.getIDP().getSingleSignOnService().getRequestBindingUrl());
        return deployment;
    }
}

Scenario - Custom role mapping via RoleMappingsProvider

Map SAML assertion roles to application-specific roles using a custom provider.

import org.keycloak.adapters.saml.RoleMappingsProvider;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;

public class AppRoleMappingsProvider implements RoleMappingsProvider {

    private static final Map<String, String> ROLE_MAP = Map.of(
        "saml-admin",   "APP_ADMIN",
        "saml-viewer",  "APP_VIEWER"
    );

    @Override
    public Set<String> mapRoles(String principalName, Set<String> roles) {
        return roles.stream()
            .map(r -> ROLE_MAP.getOrDefault(r, r))
            .collect(Collectors.toSet());
    }

    @Override
    public void init(SP.RoleMappingsProviderConfig config) { }

    @Override
    public void close() { }
}

Register in keycloak-saml.xml:

<RoleMappingsProvider id="custom-role-mapper"
  class="com.example.AppRoleMappingsProvider"/>

Scenario - Multi-tenant SAML with SamlConfigResolver

Resolve a different SamlDeployment per incoming request based on hostname.

import org.keycloak.adapters.saml.SamlConfigResolver;
import org.keycloak.adapters.saml.SamlDeployment;
import org.keycloak.adapters.saml.SamlDeploymentContext;
import org.keycloak.adapters.spi.HttpFacade;
import org.keycloak.adapters.saml.config.parsers.DeploymentBuilder;
import org.keycloak.adapters.saml.config.parsers.ResourceLoader;

import java.io.InputStream;
import java.util.concurrent.ConcurrentHashMap;

public class TenantSamlConfigResolver implements SamlConfigResolver {

    private final ConcurrentHashMap<String, SamlDeployment> cache =
        new ConcurrentHashMap<>();

    @Override
    public SamlDeployment resolve(HttpFacade.Request request) {
        String host = request.getHeader("Host");
        return cache.computeIfAbsent(host, this::loadForTenant);
    }

    private SamlDeployment loadForTenant(String host) {
        String resource = "/saml/" + host + "/keycloak-saml.xml";
        InputStream is = getClass().getResourceAsStream(resource);
        ResourceLoader loader = r -> getClass().getResourceAsStream(r);
        try {
            return new DeploymentBuilder().build(is, loader);
        } catch (Exception e) {
            throw new RuntimeException("Failed to load SAML config for: " + host, e);
        }
    }
}

File walkthrough

• saml/ - Parent directory for all SAML adapter modules; contains module POM.
• saml/core/ - Core SAML adapter logic: authentication handlers, session model, XML config parsers, role mapping.
• saml/core/src/main/java/org/keycloak/adapters/saml/ - Top-level SAML adapter classes including SamlAuthenticator, SamlDeployment, SamlSession, and SamlSessionStore.
• saml/core/src/main/java/org/keycloak/adapters/saml/config/ - Config POJOs: IDP, SP, Key, KeycloakSamlAdapter.
• saml/core/src/main/java/org/keycloak/adapters/saml/config/parsers/ - XML parsers for keycloak-saml.xml; DeploymentBuilder is the entry point.
• saml/core/src/main/java/org/keycloak/adapters/saml/profile/ - Authentication handler profiles: web browser SSO (BrowserHandler, SamlEndpoint) and ECP.
• saml/core/src/main/java/org/keycloak/adapters/saml/rotation/ - Public key locator using SAML IDP descriptor for key rotation support.
• saml/core/src/main/java/org/keycloak/adapters/saml/descriptor/ - Parsers for SAML metadata descriptor documents (IDP key extraction).
• saml/core/src/main/java/org/keycloak/adapters/cloned/ - Cloned HTTP client utilities for adapter-internal use; not part of the public API.
• saml/core-public/ - Stable public API JAR; depend on this rather than saml/core for SPI implementations.
• saml/wildfly/ - Wildfly subsystem integration, module descriptors, and server-side adapter wiring.
• saml/wildfly-elytron/ - Elytron security framework bridge for Wildfly SAML authentication.
• spi/ - Keycloak SPI extension modules for server-side customization.
• pom.xml - Root Maven build file; use mvn clean install from here.

Common pitfalls and fixes

• Version mismatch between adapter and server: The adapter JAR version must exactly match your Keycloak server version; mixing versions causes assertion parsing failures. Fix: pin both to the same release (e.g., 24.0.0).
• Missing keycloak-saml.xml on classpath: DeploymentBuilder throws a NullPointerException if the stream is null. Fix: verify the file is in WEB-INF/ and the ResourceLoader lambda resolves relative paths correctly.
• IDP certificate rotation breaks signature validation: The adapter caches public keys. Fix: configure SamlDescriptorPublicKeyLocator with the IDP metadata URL so keys are refreshed automatically.
• Wildfly module isolation: Classes from saml/core are not visible to deployments unless the module is listed in jboss-deployment-structure.xml. Fix: add <module name="org.keycloak.keycloak-saml-core"/> to your deployment descriptor.
• ECP profile not activated: ECP (SOAP-based) authentication requires an explicit <SP ... EcpEnabled="true"> in keycloak-saml.xml; it is disabled by default.
• Role mapping provider not found: If a custom RoleMappingsProvider is on a different classloader than the adapter, it will silently fall back to no mapping. Fix: ensure the provider class is in the same WAR or module as the adapter.

Vibe-coding prompt template

I have the Keycloak Java SAML adapter source code located in the `source/` directory
of this project. I also have a USAGE.md file that documents the real class names,
package structure, and integration patterns for this library.

Please help me integrate the Keycloak SAML adapter (keycloak-saml-core) into my
existing Java web application step by step:

1. Read USAGE.md and the file tree under source/ to understand the available classes.
2. Add the correct Maven dependencies to my pom.xml (match my Keycloak server version).
3. Create or update WEB-INF/keycloak-saml.xml with my IDP and SP settings.
4. Register the SAML filter in WEB-INF/web.xml.
5. If I need multi-tenancy, implement SamlConfigResolver using the pattern in USAGE.md.
6. If I need custom role mapping, implement RoleMappingsProvider and register it.
7. Show me how to use DeploymentBuilder to validate my configuration at startup.
8. Point out any version pinning or classloader pitfalls from the Common Pitfalls section.

My project details: [INSERT YOUR FRAMEWORK, JAVA VERSION, AND KEYCLOAK SERVER VERSION HERE]

License and credit

This source is part of the Keycloak project, licensed under the Apache License, Version 2.0. See source/LICENSE or https://www.apache.org/licenses/LICENSE-2.0.

Upstream repository: https://github.com/keycloak/keycloak

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

AI-First Identity and Access Management Server

Automation, Utilities & Developer Tools

Free