Tomcat Servlet容器如何判断认证成功？自定义LoginModule问题排查

Tomcat对JAAS LoginModule的认证成功判定有明确规则，你的自定义LoginModule虽然login()和commit()都返回true且添加了Principal，但核心问题在于Tomcat无法识别你添加的角色Principal，导致权限校验失败。

一、Tomcat认证成功的核心判定条件 #

Tomcat完成认证并允许访问受保护资源，需要同时满足：

• login()方法返回true且未抛出LoginException
• commit()方法返回true
• Subject中存在至少一个用户Principal（代表登录用户的身份）
• 该用户拥有web.xml中auth-constraint指定的角色，且Tomcat能正确识别这些角色

二、你的自定义LoginModule问题所在 #

你添加的两个CustomPrincipal实例，Tomcat默认会将它们都视为用户Principal，而非角色。Tomcat识别角色的规则如下：

• 默认情况下，Tomcat的JAASRealm只会把org.apache.catalina.realm.GenericPrincipal类的实例视为角色载体（或通过roleClassNames配置指定的类）
• 若使用自定义Principal类，必须明确告诉Tomcat哪些实例是角色

三、修复方案 #

方案1：使用Tomcat原生GenericPrincipal（低耦合）

修改commit()方法，添加用户Principal的同时，用GenericPrincipal携带角色信息：

import org.apache.catalina.realm.GenericPrincipal;
import java.util.Collections;

@Override
public boolean commit() {
    // 添加用户身份Principal
    subject.getPrincipals().add(new CustomPrincipal("admin"));
    // 添加角色：GenericPrincipal的第三个参数是角色集合
    subject.getPrincipals().add(new GenericPrincipal(null, null, Collections.singletonList("users")));
    return true;
}

方案2：配置JAASRealm识别自定义角色Principal

在Tomcat的server.xml或context.xml中配置JAASRealm的roleClassNames属性，将你的CustomPrincipal全类名加入，让Tomcat识别该类实例为角色：

<Realm className="org.apache.catalina.realm.JAASRealm"
       appName="YourAppName"
       userClassNames="com.yourpackage.CustomPrincipal"
       roleClassNames="com.yourpackage.CustomPrincipal"/>

注意：这种方式下需要区分用户Principal和角色Principal（比如通过命名规则或不同类实现），避免Tomcat混淆。

方案3：让自定义Principal实现Tomcat的Role接口（高耦合）

让CustomPrincipal实现org.apache.catalina.Role接口，Tomcat会自动识别这类实例为角色：

import org.apache.catalina.Role;

public class CustomPrincipal implements java.security.Principal, Role {
    @Override
    public String getName() {
        return "users"; // 角色名
    }
    // 实现Principal和Role的其他接口方法...
}

四、额外注意事项 #

• 角色名大小写敏感，确保web.xml中auth-constraint的角色名与你添加的角色名完全一致
• 若使用FORM认证，login()方法应从回调中获取用户名和密码（即使是极简验证，也需确保回调被正确处理）

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