SpringSecurity6.4中一次性令牌登录(One-Time Token Login)实现_Java

本系列spring boot 版本 3.4.0

本系列spring security 版本 6.4.2

spring security为一次性令牌（one-time token，ott）认证提供了支持，通过onetimetokenlogin()dsl（domain specific language，领域特定语言，它使用了一种特定的语法和约定来简化配置和管理spring应用程序的过程。）即可使用该功能。在进行实现之前，需要明确ott功能在框架中的范围。

一、理解一次性令牌与一次性密码的区别

人们常常会混淆一次性令牌（ott）和一次性密码（otp），但在 spring security 中，这两个概念在几个关键方面有所不同。为了清晰起见，我们将假设 otp 指的是基于时间的一次性密码（totp）或基于 hmac 的一次性密码（hotp）。

1.区别一：设置要求

ott：无需初始设置。用户无需提前进行任何配置。
otp：通常需要设置，例如使用外部工具生成和共享一个密钥来生成一次性密码。

2.区别二：令牌交付/发送

ott：通常需要实现一个自定义的 onetimetokengenerationsuccesshandler ，负责将令牌交付给最终用户。
otp：令牌通常由外部工具生成，因此无需通过应用程序发送给用户。

3.区别三：令牌生成

ott：通过onetimetokenservice.generate(generateonetimetokenrequest)方法在服务器端生成令牌。
otp：令牌不一定是在服务器端生成的，通常是由客户端使用共享密钥创建的。

总结来说，一次性令牌（ott）提供了一种无需额外账户设置即可验证用户的方法，与通常涉及更复杂设置过程并依赖外部工具生成令牌的一次性密码（otp）不同。

二、一次性令牌登录的流程

一次性令牌登录主要分为两个步骤：

用户提交用户标识符（通常为用户名）请求令牌，令牌会以魔法链接（magic link）的形式，通过电子邮件、短信等方式发送给用户。
用户将令牌提交到一次性令牌登录端点，也就是点击魔法链接。若令牌有效，则用户成功登录。

整体流程

开始→用户访问一次性令牌登录页面
→点击发送令牌按钮
→发送post /ott/generate 请求
→generateonetimetokenfilter 监听post /ott/generate 请求，并通过onetimetokenservice.generate()方法在服务器端生成令牌
→令牌生成成功后，调用自定义的onetimetokengenerationsuccesshandler接口实现类的handle()方法
→handle()方法负责通过email或短信将包含令牌的魔法链接（magic link）发送给用户
→用户接收到邮件/短信后，点击魔法链接
→服务器端接收get /login/ott请求
→由 defaultonetimetokensubmitpagegeneratingfilter 生成一次性令牌提交页面，并返回给用户
→用户点击提交页面中的登录按钮
→发送post /login/ott 请求，服务端需要自定义一个http接口,请求路径为post /login/ott→服务器端进入身份认证流程(filterchainproxy.dofilter→authenticationfilter.dofilterinternal)
→authenticationfilter.attemptauthentication方法中通过调用this.authenticationconverter.convert(request)构造onetimetokenauthenticationtoken实例，其中this.authenticationconverter是onetimetokenauthenticationconverter的实例
→authenticationfilter.dofilterinternal方法中通过调用authenticationmanager.authenticate(onetimetokenauthenticationtoken)进行认证
→调用providermanager.authenticate(onetimetokenauthenticationtoken)→交给onetimetokenauthenticationprovider认证
→onetimetokenauthenticationprovider.authenticate()方法调用onetimetokenservice.consume(onetimetokenauthenticationtoken)方法消费token，对token进行验证
→验证通过
→调用userdetailsservice.loaduserbyusername获取用户信息和权限信息
→认证完成
→dispatcherservlet接着处理post /login/ott 请求
→调用服务端自定义的对应controller方法
→该方法处理登录成功后的一些逻辑，比如重定向到指定页面，记录日志等。
→结束

三、一次性令牌登录的配置

1.ott与默认生成的登录页面的集成

onetimetokenlogin()dsl可与formlogin()结合使用，这会在默认生成的登录页面中添加一个一次性令牌请求表单，同时设置defaultonetimetokensubmitpagegeneratingfilter来生成默认的一次性令牌提交页面。

2.发送令牌给用户

spring security无法确定令牌的交付方式，因此需提供自定义的onetimetokengenerationsuccesshandler。

最常用的发送策略之一是通过电子邮件、短信等发送一个魔法链接。

在下面的示例中，我们将创建一个魔法链接并将其发送到用户的电子邮件。

一次性令牌登录配置

@configuration
@enablewebsecurity
public class securityconfig {

    @bean
    public securityfilterchain filterchain(httpsecurity http) {
        http
            // ...
            .formlogin(customizer.withdefaults())
            .onetimetokenlogin(customizer.withdefaults());
        return http.build();
    }

}

自定义onetimetokengenerationsuccesshandler

@component // ①
public class magiclinkonetimetokengenerationsuccesshandler implements onetimetokengenerationsuccesshandler {
    private final mailsender mailsender;
    private final onetimetokengenerationsuccesshandler redirecthandler = new redirectonetimetokengenerationsuccesshandler("/ott/sent");

    @override
    public void handle(httpservletrequest request, httpservletresponse response, onetimetoken onetimetoken) throws ioexception, servletexception {
        uricomponentsbuilder builder = uricomponentsbuilder.fromhttpurl(urlutils.buildfullrequesturl(request))
                .replacepath(request.getcontextpath())
                .replacequery(null)
                .fragment(null)
                .path("/login/ott")
                .queryparam("token", onetimetoken.gettokenvalue()); // ②
        string magiclink = builder.touristring();
        string email = getuseremail(onetimetoken.getusername()); // ③
        this.mailsender.send(email, "your spring security one time token", "use the following link to sign in into the application: " + magiclink); // ④
        this.redirecthandler.handle(request, response, onetimetoken); // ⑤
    }

    private string getuseremail() {
        // ...
    }
}

发送令牌给用户成功后要跳转到的页面

@controller
public class pagecontroller {

    @getmapping("/ott/sent")
    string ottsent() {
        return "my-template";
    }

}

① 将 magiclinkonetimetokengenerationsuccesshandler 配置为 spring bean

② 创建一个带有 token 作为查询参数的登录处理 url

③ 根据用户名检索用户电子邮件

④ 使用 javamailsender api 向用户发送带有魔法链接的电子邮件

⑤ 使用 redirectonetimetokengenerationsuccesshandler 进行重定向到您想要的 url

邮件内容将类似于：

use the following link to sign in into the application: http://localhost:8080/login/ott?token=a830c444-29d8-4d98-9b46-6aba7b22fe5b

默认提交页面会检测url中的token查询参数，并将它的值自动填充到表单字段中。

3.配置一次性令牌提交页面

默认的一次性令牌提交页面由 defaultonetimetokensubmitpagegeneratingfilter 生成，并监听 get /login/ott 。url 也可以这样更改：

配置默认提交页面 url

@configuration
@enablewebsecurity
public class securityconfig {

    @bean
    public securityfilterchain filterchain(httpsecurity http) {
        http
            // ...
            .formlogin(customizer.withdefaults())
            .onetimetokenlogin((ott) -> ott
                .defaultsubmitpageurl("/ott/submit")
            );
        return http.build();
    }

}

@component
public class magiclinkgenerationsuccesshandler implements onetimetokengenerationsuccesshandler {
    // ...
}

tips:2025.1.14官方文档示例是使用submitpageurl(string)dsl 方法进行更改。我使用 spring security6.4.2 测试时，只有defaultsubmitpageurl(string)dsl 方法。因此示例修改为defaultsubmitpageurl(string)dsl 方法。

4.自定义一次性令牌提交页面

如果您想使用自己的一次性令牌提交页面，您可以禁用默认页面，然后提供自己的端点。

禁用默认提交页面

@configuration
@enablewebsecurity
public class securityconfig {

    @bean
    public securityfilterchain filterchain(httpsecurity http) {
        http
            .authorizehttprequests(authorize -> authorize
                .anyrequest().authenticated()
            )
            .formlogin(customizer.withdefaults())
            .onetimetokenlogin((ott) -> ott
                // 禁用默认提交页面
                .showdefaultsubmitpage(false)
                // 自定义提交页面url
                .defaultsubmitpageurl("/ott/submit")
            );
        return http.build();
    }

}

@controller
public class mycontroller {

    // 自定义默认提交页面入口
    @getmapping("/ott/submit")
    public string ottsubmitpage() {
        return "my-ott-submit";
    }

}

@component
public class magiclinkgenerationsuccesshandler implements onetimetokengenerationsuccesshandler {
    // ...
        
    @override
    public void handle(httpservletrequest request, httpservletresponse response, onetimetoken onetimetoken) throws ioexception, servletexception {
        uricomponentsbuilder builder = uricomponentsbuilder.fromhttpurl(urlutils.buildfullrequesturl(request))
                .replacepath(request.getcontextpath())
                .replacequery(null)
                .fragment(null)
                .path("/ott/submit")
                .queryparam("token", onetimetoken.gettokenvalue()); // ②
        string magiclink = builder.touristring();
        string email = getuseremail(onetimetoken.getusername()); // ③
        this.mailsender.send(email, "your spring security one time token", "use the following link to sign in into the application: " + magiclink); // ④
        this.redirecthandler.handle(request, response, onetimetoken); // ⑤
    }
    
    // ...
}

5.更改一次性令牌生成 url

默认情况下， generateonetimetokenfilter 监听 post /ott/generate 请求。该 url 可以通过使用 tokengeneratingurl(string) dsl 方法进行更改：

// java示例
@configuration
@enablewebsecurity
public class securityconfig {
    @bean
    public securityfilterchain filterchain(httpsecurity http) {
        http
            // ...
            .formlogin(customizer.withdefaults())
            .onetimetokenlogin((ott) -&gt; ott
                .tokengeneratingurl("/ott/my-generate-url")
            );
        return http.build();
    }
}

tips:2025.1.14官方文档示例是使用generatetokenurl(string)dsl 方法进行更改。我使用 spring security6.4.2 测试时，只有tokengeneratingurl(string)dsl 方法。因此示例修改为tokengeneratingurl(string)dsl 方法。

6.自定义如何生成和消费令牌

定义生成和使用一次性令牌常见操作的接口是onetimetokenservice。spring security默认使用inmemoryonetimetokenservice，生产环境可考虑使用jdbconetimetokenservice。

一些自定义 onetimetokenservice 最常见的原因包括但不限于：

更改一次性令牌过期时间
存储更多生成令牌请求的信息
更改令牌值的创建方式
在使用一次性令牌时进行额外验证

有两种自定义方式：

一是将自定义的onetimetokenservice作为bean提供，会被onetimetokenlogin()dsl自动识别：

@configuration 
@enablewebsecurity 
public class securityconfig {
    @bean
    public securityfilterchain filterchain(httpsecurity http) {
        http.formlogin(customizer.withdefaults())
            .onetimetokenlogin(customizer.withdefaults());
        return http.build();
    }
    @bean
    public onetimetokenservice onetimetokenservice() {
        return new mycustomonetimetokenservice();
    }
}

二是将onetimetokenservice实例传递给dsl，当存在多个securityfilterchain且每个需要不同的onetimetokenservice时，这种方式很有用：

@configuration 
@enablewebsecurity 
public class securityconfig {
    @bean
    public securityfilterchain filterchain(httpsecurity http) {
        http.formlogin(customizer.withdefaults())
            .onetimetokenlogin((ott) -> ott
                .tokenservice(new mycustomonetimetokenservice())
            );
        return http.build();
    }
}

tips:2025.1.14官方文档示例是使用onetimetokenservice(onetimetokenservice)dsl 方法进行更改。我使用 spring security6.4.2 测试时，只有tokenservice(onetimetokenservice)dsl 方法。因此示例修改为tokenservice(onetimetokenservice)dsl 方法。

7.完整配置示例

@configuration 
@enablewebsecurity 
public class securityconfig {
    
        /**
     * 配置security过滤链，用于处理一次性令牌登录
     *
     * @param http 用于配置web安全的httpsecurity对象
     * @param userdetailsservice 自定义的用户信息查询服务，实现了userdetailsservice接口
     * @param mailsender 邮件服务
     * @return 配置好的securityfilterchain对象
     */
    @bean
    @order(1)
    public securityfilterchain ottloginsecurityfilterchain(httpsecurity http, final onetimetokenservice onetimetokenservice, final userdetailsserviceimpl userdetailsservice, final javamailsender mailsender) throws exception {
        http.formlogin(customizer.withdefaults())
                // 配置请求授权，所有请求都需要认证
                .authorizehttprequests(authorize -> authorize.anyrequest().authenticated())
                // 禁用csrf保护，适用于本例的简单演示场景，在生产环境中需谨慎考虑。若是前后端分离情况，需要禁用
                .csrf(csrfconfigurer::disable)
                // 配置一次性令牌登录
                .onetimetokenlogin(ott->ott
                        // （可选）设置一次性令牌生成的url，默认值：/ott/generate
                        .tokengeneratingurl("/ott/generate")
                        // （可选）设置一次性令牌生成和验证的服务，实现onetimetokenservice接口，默认值：inmemoryonetimetokenservice实例
                        .tokenservice(onetimetokenservice)
                        // （必做）配置一次性令牌生成成功后的处理，默认值：redirectonetimetokengenerationsuccesshandler实例
                        .tokengenerationsuccesshandler(new customonetimetokengenerationsuccesshandler(mailsender))
                        // （可选）设置是否显示默认的登录提交页面，默认值：true
                        .showdefaultsubmitpage(true)
                        // （可选）设置默认登录提交页面的url，默认值：/login/ott
                        .defaultsubmitpageurl("/login/ott")
                        // （可选）配置认证转换器，用于将http请求中的token转换为onetimetokenauthenticationtoken认证对象，默认值：onetimetokenauthenticationconverter实例
                        .authenticationconverter(new onetimetokenauthenticationconverter())
                        // （可选）配置认证提供者，用于验证onetimetokenauthenticationtoken认证对象，默认值：onetimetokenauthenticationprovider实例
                        .authenticationprovider(new onetimetokenauthenticationprovider(onetimetokenservice, userdetailsservice))
                        // （可选）配置认证成功后的处理
                        .authenticationsuccesshandler(((request, response, authentication) -> {
                            system.out.println("认证成功");
                        }))
                        // （可选）配置认证失败后的处理
                        .authenticationfailurehandler((request, response, exception) -> {
                            system.out.println("认证失败:"+exception.getmessage());
                            new defaultredirectstrategy().sendredirect(request, response, "/login");
                        })
                        // （可选）设置一次性令牌登录成功后的url
                        // （必做）添加一个 /login/ott 类型的http接口
                        .loginprocessingurl("/login/ott")

                );

        // 构建并返回配置好的security过滤链
        return http.build();
    }
    
    @bean
    public onetimetokenservice onetimetokenservice() {
        // 创建自定义的onetimetokenservice实例
        // 为了测试方便，直接使用内置的inmemoryonetimetokenservice
        return new inmemoryonetimetokenservice();
    }
    
    static class customonetimetokengenerationsuccesshandler implements onetimetokengenerationsuccesshandler {

        private final redirectstrategy redirectstrategy = new defaultredirectstrategy();
        private final javamailsender mailsender;

        public customonetimetokengenerationsuccesshandler(javamailsender mailsender) {
            this.mailsender = mailsender;
        }

        @override
        public void handle(httpservletrequest request, httpservletresponse response, onetimetoken onetimetoken) throws ioexception, servletexception {
            // 发送邮件或短信给用户
            uricomponentsbuilder builder = uricomponentsbuilder.fromuristring(urlutils.buildfullrequesturl(request))
                    .replacepath(request.getcontextpath())
                    .replacequery(null)
                    .fragment(null)
                    .path("/login/ott") // 设置默认登录提交页面的url
                    .queryparam("token", onetimetoken.gettokenvalue());
            string magiclink = builder.touristring();
            // 发件人：从数据库或配置文件中读取，这里只是测试，直接写死
            string from = "test@test.com";
            string email = getuseremail(onetimetoken.getusername());

            simplemailmessage msg = new simplemailmessage();
            msg.setfrom(from);
            msg.setto(email);
            msg.setsubject("your spring security one time token");
            msg.settext("use the following link to sign in into the application: " + magiclink);

            this.mailsender.send(msg);

            // 为了测试方便，重定向到token提交页
            string redirecturl = "/login/ott?token=" + onetimetoken.gettokenvalue();
            this.redirectstrategy.sendredirect(request, response, redirecturl);
        }

        private string getuseremail(string username) {
            // todo 获取用户邮箱地址
            return "test@test.com";
        }
    }
}

@restcontroller
public class ottlogincontroller {

    private final redirectstrategy redirectstrategy = new defaultredirectstrategy();
    @postmapping("/login/ott")
    public void login(httpservletrequest request, httpservletresponse response) throws ioexception {
        system.out.println("认证成功后跳转到主页");
        this.redirectstrategy.sendredirect(request,response,"/");
    }

}

通过以上配置，可以根据具体需求灵活使用spring security的一次性令牌登录功能。