第 7 章 User Storage SPI

您可以使用 User Storage SPI 编写 Red Hat Single Sign-On 的扩展来连接外部用户数据库和凭证存储。内置的 LDAP 和 ActiveDirectory 支持是此操作中此 SPI 的实现。开箱即用，Red Hat Single Sign-On 使用其本地数据库来创建、更新和查找用户并验证凭证。然而，组织拥有现有的外部专有用户数据库，他们无法迁移到红帽单点登录的数据模型。对于这样的情况，应用程序开发人员可编写用户存储 SPI 的实施，以桥接 Red Hat Single Sign-On 用来登录用户和管理它们的内部用户对象模型。

当红帽单点登录运行时需要查找用户，如登录用户时，它会执行几个步骤来定位用户。首先，它会查看用户是否在用户缓存中；如果用户发现它使用内存中表示。然后，它将在 Red Hat Single Sign-On 本地数据库中查找该用户。如果没有找到用户，则通过 User Storage SPI 供应商实施循环来执行用户查询，直到其中之一返回用户查找运行时。提供程序查询用户的外部用户存储，并将用户的外部数据表示映射到 Red Hat Single Sign-On 的用户 metamodel。

用户存储 SPI 供应商实施还可以执行复杂的条件查询，对用户执行 CRUD 操作，验证和管理凭证，或者一次对许多用户执行批量更新。它取决于外部存储的功能。

用户存储 SPI 提供程序实施与（通常）Jkarta EE 组件相似打包并部署。默认情况下，它们不会被启用，但必须在管理控制台的 User Federation 选项卡下启用和配置。

警告

如果您的用户供应商实施正在使用某些用户属性作为元数据属性来链接/提交用户身份，请确保用户无法编辑属性，并且对应的属性是只读的。示例是 LDAP_ID 属性，内置 Red Hat Single Sign-On LDAP 供应商用于存储 LDAP 服务器端用户的 ID。请参阅 Threat 模型缓解章节中的详细信息。

7.1. 供应商接口

在构建 User Storage SPI 实施时，您必须定义供应商类和供应商工厂。提供商类实例按照供应商工厂为每个事务创建。提供程序类执行用户查询和其他用户操作的繁重处理。它们必须实施 org.keycloak.storage.UserStorageProvider 接口。

package org.keycloak.storage;

public interface UserStorageProvider extends Provider {


    /**
     * Callback when a realm is removed.  Implement this if, for example, you want to do some
     * cleanup in your user storage when a realm is removed
     *
     * @param realm
     */
    default
    void preRemove(RealmModel realm) {

    }

    /**
     * Callback when a group is removed.  Allows you to do things like remove a user
     * group mapping in your external store if appropriate
     *
     * @param realm
     * @param group
     */
    default
    void preRemove(RealmModel realm, GroupModel group) {

    }

    /**
     * Callback when a role is removed.  Allows you to do things like remove a user
     * role mapping in your external store if appropriate

     * @param realm
     * @param role
     */
    default
    void preRemove(RealmModel realm, RoleModel role) {

    }

}

package org.keycloak.storage;

public interface UserStorageProvider extends Provider {


    /**
     * Callback when a realm is removed.  Implement this if, for example, you want to do some
     * cleanup in your user storage when a realm is removed
     *
     * @param realm
     */
    default
    void preRemove(RealmModel realm) {

    }

    /**
     * Callback when a group is removed.  Allows you to do things like remove a user
     * group mapping in your external store if appropriate
     *
     * @param realm
     * @param group
     */
    default
    void preRemove(RealmModel realm, GroupModel group) {

    }

    /**
     * Callback when a role is removed.  Allows you to do things like remove a user
     * role mapping in your external store if appropriate

     * @param realm
     * @param role
     */
    default
    void preRemove(RealmModel realm, RoleModel role) {

    }

}

Copy to Clipboard

您可能会考虑 UserStorageProvider 接口不是稀疏的？本章稍后将看到，您的供应商课程可能会实施的其他混合接口来支持用户集成。

UserStorageProvider 实例为每个事务创建一次。事务完成后，调用 UserStorageProvider.close （） 方法，然后实例便被垃圾回收。实例由供应商工厂创建。提供程序工厂实施 org.keycloak.storage.UserStorageProviderFactory 接口。

package org.keycloak.storage;

/**
 * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
 * @version $Revision: 1 $
 */
public interface UserStorageProviderFactory<T extends UserStorageProvider> extends ComponentFactory<T, UserStorageProvider> {

    /**
     * This is the name of the provider and will be shown in the admin console as an option.
     *
     * @return
     */
    @Override
    String getId();

    /**
     * called per Keycloak transaction.
     *
     * @param session
     * @param model
     * @return
     */
    T create(KeycloakSession session, ComponentModel model);
...
}

package org.keycloak.storage;

/**
 * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
 * @version $Revision: 1 $
 */
public interface UserStorageProviderFactory<T extends UserStorageProvider> extends ComponentFactory<T, UserStorageProvider> {

    /**
     * This is the name of the provider and will be shown in the admin console as an option.
     *
     * @return
     */
    @Override
    String getId();

    /**
     * called per Keycloak transaction.
     *
     * @param session
     * @param model
     * @return
     */
    T create(KeycloakSession session, ComponentModel model);
...
}

Copy to Clipboard

在实施 UserStorageProviderFactory 时，提供者类必须将 concrete provider 类指定为模板参数。这是运行时必须内省此类，以扫描其功能（其实施的其他接口）。例如，如果您的供应商类命名为 FileProvider，则工厂类应如下所示：

public class FileProviderFactory implements UserStorageProviderFactory<FileProvider> {

    public String getId() { return "file-provider"; }

    public FileProvider create(KeycloakSession session, ComponentModel model) {
       ...
    }

public class FileProviderFactory implements UserStorageProviderFactory<FileProvider> {

    public String getId() { return "file-provider"; }

    public FileProvider create(KeycloakSession session, ComponentModel model) {
       ...
    }

Copy to Clipboard

getId （） 方法返回 User Storage 供应商的名称。当您想要为特定域启用提供程序时，admin 控制台的 User Federation 页面中会显示此 ID。

create （） 方法负责分配提供程序类的实例。它取 org.keycloak.models.KeycloakSession 参数。此对象可用于查找其他信息和元数据，以及提供对运行时内各种其他组件的访问。ComponentModel 参数代表供应商如何在特定域中启用和配置。它包含启用的供应商的实例 ID，以及在通过 admin 控制台启用时为它指定的任何配置。

UserStorageProviderFactory 还具有其他功能，本章稍后会用到它。

第 7 章 User Storage SPI

7.1. 供应商接口

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links