Keycloak 18→25迁移：自定义SAML IdP默认映射器不显示

可能原因及解决办法 #

• 自定义IdP未正确继承核心SAML类
  Keycloak 20+版本对SAML IdP扩展机制做了调整，若自定义IdP未继承org.keycloak.broker.saml.SAMLIdentityProvider或org.keycloak.broker.saml.SAMLEndpoint核心父类，仅实现基础接口的话，会无法加载默认映射器。需检查自定义IdP的实现类，确保继承正确的父类。

• 未主动注册默认映射器
  Keycloak 18中默认映射器会自动关联到SAML IdP，但25版本要求自定义IdP在getIdpMapperTypes()方法中显式注册默认映射器类型：

  @Override
  public List<ProviderConfigProperty> getIdpMapperTypes() {
      List<ProviderConfigProperty> types = super.getIdpMapperTypes();
      // 添加Attribute Importer等默认映射器
      types.add(new ProviderConfigProperty(SAMLAttributeImporterMapper.PROVIDER_ID, "Attribute Importer", "导入远程IdP属性", ProviderConfigProperty.STRING_TYPE, null));
      return types;
  }
  

• SPI声明不完整
  检查META-INF/services/org.keycloak.broker.provider.IdentityProviderFactory文件，确保自定义IdP工厂类的providerId声明正确，且已引入SAML相关SPI依赖。Keycloak 25对SPI校验更严格，缺失依赖会导致默认组件无法加载。

• API版本不兼容
  从18到25版本间Keycloak有大量API变更，比如映射器的ProviderConfigProperty结构、SPI注册逻辑都有调整。需对照官方文档，替换自定义IdP中所有过时的API调用，适配25版本的规范。

内容的提问来源于stack exchange，提问作者Rafael Jorda