Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - JASPIC</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>JASPIC</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Static_configuration">Static configuration</a><ol><li><a href="#AuthConfigProvider">AuthConfigProvider</a></li><li><a href="#ServerAuthModule">ServerAuthModule</a></li></ol></li><li><a href="#Dynamic_configuration">Dynamic configuration</a></li><li><a href="#3rd_party_modules">3rd party modules</a><ol><li><a href="#Philip_Green_II's_module_for_Google_OAuth_2">Philip Green II's module for Google OAuth 2</a></li></ol></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>Tomcat implements JASPIC 1.1 Maintenance Release B
9 
  (<a href="https://www.jcp.org/en/jsr/detail?id=196">JSR 196</a>). The
10 
  implementation is primarily intended to enable the integration of 3rd party
11 
  JASPIC authentication implementations with Tomcat.</p>
12 
 
13 
  <p>JASPIC may be configured in one of two ways:</p>
14 
  <ul>
15 
    <li>At the container level via the static configuration file
16 
        <code>$CATALINA_BASE/conf/jaspic-providers.xml</code>. With this
17 
        approach all required classes must be visible to Tomcat's Common class
18 
        loader which normally means placing a JAR in
19 
        <code>$CATALINA_BASE/lib</code>.</li>
20 
     <li>At the web application level via dynamic configuration using the JASPIC
21 
         API. With this approach all required classes must be visible to the web
22 
         application class loader which normally means placing a JAR in the web
23 
         application's <code>WEB-INF/lib</code> directory.</li>
24 
  </ul>
25 
 
26 
  <p>Users should be aware that if the static JASPIC configuration file
27 
     configures JASPIC for a given web application then the JASPIC configuration
28 
     will take precedence over any <code>&lt;login-config&gt;</code> present in
29 
     the web application's <code>WEB-INF/web.xml</code> file.</p>
30 
 
31 
</div><h3 id="Static_configuration">Static configuration</h3><div class="text">
32 
 
33 
  <div class="subsection"><h4 id="AuthConfigProvider">AuthConfigProvider</h4><div class="text">
34 
 
35 
    <p>If the 3rd party implementation includes an
36 
    <code>AuthConfigProvider</code> then a web application can be configured to
37 
    use it by nesting the following inside the
38 
    <code>&lt;jaspic-providers&gt;</code> element in
39 
    <code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
40 
<div class="codeBox"><pre><code>&lt;provider name="any"
41 
          className="fully.qualified.implementation.class.Name"
42 
          layer="HttpServlet"
43 
          appContext="Catalina/localhost /contextPath"
44 
          description="any"&gt;
45 
  &lt;property name="see-provider-documentation"
46 
            value="see-provider-documentation" /&gt;
47 
&lt;/provider&gt;</code></pre></div>
48 
 
49 
    <p>The <code>name</code> and <code>description</code> attributes are not
50 
    used by Tomcat.</p>
51 
 
52 
    <p>The <code>className</code> attribute must be the fully qualified class
53 
    name of the <code>AuthConfigProvider</code>. The implementation may be
54 
    packaged with the web application or in Tomcat's
55 
    <code>$CATALINA_BASE/lib</code> directory.</p>
56 
 
57 
    <p>The <code>layer</code> attribute must be <code>HttpServlet</code>.</p>
58 
 
59 
    <p>The <code>appContext</code> attribute must be exactly the concatenation
60 
    of:</p>
61 
    <ul>
62 
      <li>The engine name</li>
63 
      <li>The forward slash character</li>
64 
      <li>The host name</li>
65 
      <li>A single space</li>
66 
      <li>The context path</li>
67 
    </ul>
68 
 
69 
    <p>If the <code>AuthConfigProvider</code> supports configuration via
70 
    properties these may be specified via <code>&lt;property&gt;</code> elements
71 
    nesting inside the <code>&lt;provide&gt;</code> element.</p>
72 
 
73 
  </div></div>
74 
 
75 
  <div class="subsection"><h4 id="ServerAuthModule">ServerAuthModule</h4><div class="text">
76 
 
77 
    <p>If the 3rd party implementation only provides an
78 
    <code>ServerAuthModule</code> then it will be necessary to provide a number
79 
    of supporting classes. These may be a custom implementation or,
80 
    alternatively, Tomcat provides a simple wrapper implementation for
81 
    <code>ServerAuthModule</code>s.
82 
    </p>
83 
 
84 
    <p>Tomcat's wrapper for <code>ServerAuthModule</code> can be configured
85 
    by nesting the following inside the
86 
    <code>&lt;jaspic-providers&gt;</code> element in
87 
    <code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
88 
<div class="codeBox"><pre><code>&lt;provider name="any"
89 
          className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
90 
          layer="HttpServlet"
91 
          appContext="Catalina/localhost /contextPath"
92 
          description="any"&gt;
93 
  &lt;property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
94 
            value="fully.qualified.implementation.class.Name" /&gt;
95 
  &lt;property name="see-provider-documentation"
96 
            value="see-provider-documentation" /&gt;
97 
&lt;/provider&gt;</code></pre></div>
98 
 
99 
    <p>The configuration is similar to the <code>AuthConfigProvider</code> in
100 
    the previous section but with some key differences.</p>
101 
 
102 
    <p>The <code>className</code> attribute must be
103 
    <code>org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider</code>.</p>
104 
 
105 
    <p>The <code>ServerAuthModule</code>(s) are specified via properties. The
106 
    property name must be
107 
    <code>org.apache.catalina.authenticator.jaspic.ServerAuthModule.n</code>
108 
    where <code>n</code> is the index of the module. The index must start at 1
109 
    an increment in steps of 1 until all modules are defined. The value of the
110 
    property must be the fully qualified class name of the module.</p>
111 
  </div></div>
112 
 
113 
</div><h3 id="Dynamic_configuration">Dynamic configuration</h3><div class="text">
114 
 
115 
  <p>JASPIC modules and configuration can be packaged within a WAR file with the
116 
  web application. The web application can then register the required JASPIC
117 
  configuration when it starts using the standard JASPIC APIs.</p>
118 
 
119 
  <p>If parallel deployment is being used then dynamic configuration should not
120 
  be used. The JASPIC API assumes that a context path is unique for any given
121 
  host which is not the case when using parallel deployment. When using parallel
122 
  deployment, static JASPIC configuration should be used. This will require that
123 
  all versions of the application use the same JASPIC configuration.</p>
124 
 
125 
</div><h3 id="3rd_party_modules">3rd party modules</h3><div class="text">
126 
 
127 
  <p>This is not an exhaustive list. The Tomcat community welcomes contributions
128 
  that add to this section.</p>
129 
 
130 
  <div class="subsection"><h4 id="Philip_Green_II's_module_for_Google_OAuth_2">Philip Green II's module for Google OAuth 2</h4><div class="text">
131 
 
132 
    <p>The source code for this module along with the
133 
    <a href="https://github.com/phillipgreenii/google-oauth-2.0-serverauthmodule">documentation</a>
134 
    which includes details of the necessary Google API configuration is
135 
    available on GitHub.</p>
136 
 
137 
    <p>A sample configuration for using this module with Tomcat would look like
138 
    this:</p>
139 
<div class="codeBox"><pre><code>&lt;jaspic-providers xmlns="https://tomcat.apache.org/xml"
140 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
141 
                  xsi:schemaLocation="https://tomcat.apache.org/xml jaspic-providers.xsd"
142 
                  version="1.0"&gt;
143 
  &lt;provider name="google-oauth"
144 
            className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
145 
            layer="HttpServlet"
146 
            appContext="Catalina/localhost /contextPath"
147 
            description="Google OAuth test"&gt;
148 
    &lt;property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
149 
              value="com.idmworks.security.google.GoogleOAuthServerAuthModule" /&gt;
150 
    &lt;property name="oauth.clientid"
151 
              value="obtained-from-Google-console" /&gt;
152 
    &lt;property name="oauth.clientsecret"
153 
              value="obtained-from-Google-console" /&gt;
154 
    &lt;property name="ignore_missing_login_context"
155 
              value="true" /&gt;
156 
  &lt;/provider&gt;
157 
&lt;/jaspic-providers&gt;</code></pre></div>
158 
  </div></div>
159 
 
160 
</div></div></div></div></div><footer><div id="footer">
161 
    Copyright &copy; 1999-2025, The Apache Software Foundation
162 
    <br>
163 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
164 
    are either registered trademarks or trademarks of the Apache Software
165 
    Foundation.
166 
    </div></footer></div></body></html>