Jakarta 认证 (原 JASPIC)

目录

简介

Tomcat 实现了 Jakarta 认证 3.1。此实现主要旨在使第三方认证实现与 Tomcat 集成。

Jakarta 认证可以通过以下两种方式之一进行配置

  • 在容器级别，通过静态配置文件 $CATALINA_BASE/conf/jaspic-providers.xml。采用此方法，所有必需的类都必须对 Tomcat 的 Common 类加载器可见，这通常意味着将 JAR 放在 $CATALINA_BASE/lib 中。
  • 在 Web 应用程序级别，通过使用 Jakarta 认证 API 进行动态配置。采用此方法，所有必需的类都必须对 Web 应用程序类加载器可见，这通常意味着将 JAR 放在 Web 应用程序的 WEB-INF/lib 目录中。

用户应注意，如果静态 Jakarta 认证配置文件为给定的 Web 应用程序配置了 Jakarta 认证，则 Jakarta 认证配置将优先于 Web 应用程序的 WEB-INF/web.xml 文件中存在的任何 <login-config>。

静态配置

AuthConfigProvider

如果第三方实现包含 AuthConfigProvider，则可以通过在 $CATALINA_BASE/conf/jaspic-providers.xml 文件中的 <jaspic-providers> 元素内嵌套以下内容来配置 Web 应用程序使用它。

<provider name="any"
          className="fully.qualified.implementation.class.Name"
          layer="HttpServlet"
          appContext="Catalina/localhost /contextPath"
          description="any">
  <property name="see-provider-documentation"
            value="see-provider-documentation" />
</provider>

name 和 description 属性不被 Tomcat 使用。

className 属性必须是 AuthConfigProvider 的完全限定类名。该实现可以与 Web 应用程序一起打包，或放置在 Tomcat 的 $CATALINA_BASE/lib 目录中。

layer 属性必须是 HttpServlet。

appContext 属性必须是以下内容的精确拼接

  • 引擎名称
  • 正斜杠字符
  • 主机名
  • 一个空格
  • 上下文路径

如果 AuthConfigProvider 支持通过属性进行配置，则可以通过嵌套在 <provide> 元素内的 <property> 元素来指定这些属性。

ServerAuthModule

如果第三方实现仅提供一个 ServerAuthModule，则需要提供一些支持类。这些可以是自定义实现，或者，Tomcat 也为 ServerAuthModule 提供了简单的包装器实现。

Tomcat 的 ServerAuthModule 包装器可以通过在 $CATALINA_BASE/conf/jaspic-providers.xml 文件中的 <jaspic-providers> 元素内嵌套以下内容进行配置。

<provider name="any"
          className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
          layer="HttpServlet"
          appContext="Catalina/localhost /contextPath"
          description="any">
  <property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
            value="fully.qualified.implementation.class.Name" />
  <property name="see-provider-documentation"
            value="see-provider-documentation" />
</provider>

此配置与上一节中的 AuthConfigProvider 类似，但有一些关键区别。

className 属性必须是 org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider。

ServerAuthModule(s) 通过属性指定。属性名称必须是 org.apache.catalina.authenticator.jaspic.ServerAuthModule.n，其中 n 是模块的索引。索引必须从 1 开始，并以 1 的步长递增，直到所有模块都定义完毕。属性的值必须是模块的完全限定类名。

动态配置

Jakarta 认证模块和配置可以与 Web 应用程序一起打包在 WAR 文件中。然后，Web 应用程序可以在启动时使用标准的 Jakarta 认证 API 注册所需的 Jakarta 认证配置。

如果正在使用并行部署，则不应使用动态配置。Jakarta 认证 API 假定任何给定主机的上下文路径是唯一的，这在使用并行部署时并非如此。在使用并行部署时，应使用静态 Jakarta 认证配置。这将要求应用程序的所有版本使用相同的 Jakarta 认证配置。

第三方模块

这不是一个详尽的列表。Tomcat 社区欢迎对本节进行补充的贡献。

Philip Green II 的 Google OAuth 2 模块

此模块的源代码以及包含所需 Google API 配置详细信息的文档可在 GitHub 上获取。

在 Tomcat 中使用此模块的示例配置如下所示

<jaspic-providers xmlns="https://tomcat.net.cn/xml"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="https://tomcat.net.cn/xml jaspic-providers.xsd"
                  version="1.0">
  <provider name="google-oauth"
            className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
            layer="HttpServlet"
            appContext="Catalina/localhost /contextPath"
            description="Google OAuth test">
    <property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
              value="com.idmworks.security.google.GoogleOAuthServerAuthModule" />
    <property name="oauth.clientid"
              value="obtained-from-Google-console" />
    <property name="oauth.clientsecret"
              value="obtained-from-Google-console" />
    <property name="ignore_missing_login_context"
              value="true" />
  </provider>
</jaspic-providers>