granicus.if.org Git - apache/blob - docs/manual/mod/mod_authnz_fcgi.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_authnz_fcgi.xml.meta">
  24
  25 <name>mod_authnz_fcgi</name>
  26 <description>Allows a FastCGI authorizer application to handle Apache
  27 httpd authentication and authorization</description>
  28 <status>Extension</status>
  29 <sourcefile>mod_authnz_fcgi.c</sourcefile>
  30 <identifier>authnz_fcgi_module</identifier>
  31 <compatibility>Available in version 2.4.10 and later</compatibility>
  32
  33 <summary>
  34     <p>This module allows FastCGI authorizer applications to
  35     authenticate users and authorize access to resources.  It supports
  36     generic FastCGI authorizers which participate in a single phase
  37     for authentication and authorization as well as Apache httpd-specific
  38     authenticators and authorizors which participate in one or both
  39     phases.</p>
  40
  41     <p>FastCGI authorizers can authenticate using user id and password,
  42     such as for Basic authentication, or can authenticate using arbitrary
  43     mechanisms.</p>
  44 </summary>
  45
  46 <seealso><a href="../howto/auth.html">Authentication, Authorization,
  47 and Access Control</a></seealso>
  48 <seealso><module>mod_auth_basic</module></seealso>
  49 <seealso><program>fcgistarter</program></seealso>
  50 <seealso><module>mod_proxy_fcgi</module></seealso>
  51
  52 <section id="invocations"><title>Invocation modes</title>
  53
  54     <p>The invocation modes for FastCGI authorizers supported by this
  55     module are distinguished by two characteristics, <em>type</em> and
  56     auth <em>mechanism</em>.</p>
  57
  58     <p><em>Type</em> is simply <code>authn</code> for authentication,
  59     <code>authz</code> for authorization, or <code>authnz</code> for
  60     combined authentication and authorization.</p>
  61
  62     <p>Auth <em>mechanism</em> refers to the Apache httpd configuration
  63     mechanisms and processing phases, and can be <code>
  64     AuthBasicProvider</code>, <code>Require</code>, or <code>
  65     check_user_id</code>.  The first two of these
  66     correspond to the directives used to enable participation in the
  67     appropriate processing phase.</p>
  68
  69     <p>Descriptions of each mode:</p>
  70
  71     <dl>
  72       <dt><em>Type</em> <code>authn</code>, <em>mechanism</em>
  73       <code>AuthBasicProvider</code></dt>
  74
  75       <dd>In this mode,
  76       <code>FCGI_ROLE</code> is set to <code>AUTHORIZER</code> and
  77       <code>FCGI_APACHE_ROLE</code> is set to <code>AUTHENTICATOR</code>.
  78       The application must be defined as provider type <em>authn</em>
  79       using <directive module="mod_authnz_fcgi">
  80       AuthnzFcgiDefineProvider</directive> and enabled with
  81       <directive module="mod_auth_basic">AuthBasicProvider</directive>.
  82       When invoked, the application is
  83       expected to authenticate the client using the provided user id and
  84       password.  Example application:
  85
  86 <highlight language="perl">
  87 #!/usr/bin/perl
  88 use FCGI;
  89 while (FCGI::accept >= 0) {
  90     die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
  91     die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
  92     die if !$ENV{'REMOTE_PASSWD'};
  93     die if !$ENV{'REMOTE_USER'};
  94
  95     print STDERR "This text is written to the web server error log.\n";
  96
  97     if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &amp;&amp;
  98         $ENV{'REMOTE_PASSWD'} eq "bar" ) {
  99         print "Status: 200\n";
 100         print "Variable-AUTHN_1: authn_01\n";
 101         print "Variable-AUTHN_2: authn_02\n";
 102         print "\n";
 103     }
 104     else {
 105         print "Status: 401\n\n";
 106     }
 107 }
 108 </highlight>
 109
 110       Example configuration:
 111 <highlight language="config">
 112 AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/
 113 &lt;Location "/protected/"&gt;
 114   AuthType Basic
 115   AuthName "Restricted"
 116   AuthBasicProvider FooAuthn
 117   Require ...
 118 &lt;/Location&gt;
 119 </highlight>
 120       </dd>
 121
 122       <dt><em>Type</em> <code>authz</code>, <em>mechanism</em>
 123       <code>Require</code></dt>
 124       <dd>In this mode, <code>FCGI_ROLE</code> is set to <code>
 125       AUTHORIZER</code> and <code>FCGI_APACHE_ROLE</code> is set to
 126       <code>AUTHORIZER</code>.  The application must be defined as
 127       provider type <em>authz</em> using <directive module="mod_authnz_fcgi">
 128       AuthnzFcgiDefineProvider</directive>.  When invoked, the application
 129       is expected to authorize the client using the provided user id and other
 130       request data.  Example application:
 131 <highlight language="perl">
 132 #!/usr/bin/perl
 133 use FCGI;
 134 while (FCGI::accept >= 0) {
 135     die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHORIZER";
 136     die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
 137     die if $ENV{'REMOTE_PASSWD'};
 138
 139     print STDERR "This text is written to the web server error log.\n";
 140
 141     if ($ENV{'REMOTE_USER'} eq "foo1") {
 142         print "Status: 200\n";
 143         print "Variable-AUTHZ_1: authz_01\n";
 144         print "Variable-AUTHZ_2: authz_02\n";
 145         print "\n";
 146     }
 147     else {
 148         print "Status: 403\n\n";
 149     }
 150 }
 151 </highlight>
 152
 153       Example configuration:
 154 <highlight language="config">
 155 AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10103/
 156 &lt;Location "/protected/"&gt;
 157   AuthType ...
 158   AuthName ...
 159   AuthBasicProvider ...
 160   Require FooAuthz
 161 &lt;/Location&gt;
 162 </highlight>
 163       </dd>
 164
 165       <dt><em>Type</em> <code>authnz</code>, <em>mechanism</em>
 166       <code>AuthBasicProvider</code> <em>+</em> <code>Require</code></dt>
 167
 168       <dd>In this mode, which supports the web server-agnostic FastCGI
 169       <code>AUTHORIZER</code> protocol, <code>FCGI_ROLE</code> is set to
 170       <code>AUTHORIZER</code> and <code>FCGI_APACHE_ROLE</code> is not set.
 171       The application must be defined as provider type <em>authnz</em>
 172       using <directive module="mod_authnz_fcgi">
 173       AuthnzFcgiDefineProvider</directive>.  The application is expected to
 174       handle both authentication and authorization in the same invocation
 175       using the user id, password, and other request data.  The invocation
 176       occurs during the Apache httpd API authentication phase.  If the
 177       application returns 200 and the same provider is invoked during the
 178       authorization phase (via <directive>Require</directive>), mod_authnz_fcgi
 179       will return success for the authorization phase without invoking the
 180       application.  Example application:
 181 <highlight language="perl">
 182 #!/usr/bin/perl
 183 use FCGI;
 184 while (FCGI::accept >= 0) {
 185     die if $ENV{'FCGI_APACHE_ROLE'};
 186     die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";
 187     die if !$ENV{'REMOTE_PASSWD'};
 188     die if !$ENV{'REMOTE_USER'};
 189
 190     print STDERR "This text is written to the web server error log.\n";
 191
 192     if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &amp;&amp;
 193         $ENV{'REMOTE_PASSWD'} eq "bar" &amp;&amp;
 194         $ENV{'REQUEST_URI'} =~ m%/bar/.*%) {
 195         print "Status: 200\n";
 196         print "Variable-AUTHNZ_1: authnz_01\n";
 197         print "Variable-AUTHNZ_2: authnz_02\n";
 198         print "\n";
 199     }
 200     else {
 201         print "Status: 401\n\n";
 202     }
 203 }
 204 </highlight>
 205
 206       Example configuration:
 207 <highlight language="config">
 208 AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
 209 &lt;Location "/protected/"&gt;
 210   AuthType Basic
 211   AuthName "Restricted"
 212   AuthBasicProvider FooAuthnz
 213   Require FooAuthnz
 214 &lt;/Location&gt;
 215 </highlight>
 216       </dd>
 217
 218       <dt><em>Type</em> <code>authn</code>, <em>mechanism</em>
 219       <code>check_user_id</code></dt>
 220
 221       <dd>In this mode, <code>FCGI_ROLE</code> is set to <code>
 222       AUTHORIZER</code> and <code>FCGI_APACHE_ROLE</code> is set to
 223       <code>AUTHENTICATOR</code>.  The application must be defined as
 224       provider type <em>authn</em> using <directive module="mod_authnz_fcgi">
 225       AuthnzFcgiDefineProvider</directive>.  <directive
 226       module="mod_authnz_fcgi">AuthnzFcgiCheckAuthnProvider</directive>
 227       specifies when it is called.  Example application:
 228 <highlight language="perl">
 229 #!/usr/bin/perl
 230 use FCGI;
 231 while (FCGI::accept >= 0) {
 232     die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
 233     die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";
 234
 235     # This authorizer assumes that the RequireBasicAuth option of
 236     # AuthnzFcgiCheckAuthnProvider is On:
 237     die if !$ENV{'REMOTE_PASSWD'};
 238     die if !$ENV{'REMOTE_USER'};
 239
 240     print STDERR "This text is written to the web server error log.\n";
 241
 242     if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &amp;&amp;
 243         $ENV{'REMOTE_PASSWD'} eq "bar" ) {
 244         print "Status: 200\n";
 245         print "Variable-AUTHNZ_1: authnz_01\n";
 246         print "Variable-AUTHNZ_2: authnz_02\n";
 247         print "\n";
 248     }
 249     else {
 250         print "Status: 401\n\n";
 251         # If a response body is written here, it will be returned to
 252         # the client.
 253     }
 254 }
 255 </highlight>
 256
 257       Example configuration:
 258 <highlight language="config">
 259 AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10103/
 260 &lt;Location "/protected/"&gt;
 261   AuthType ...
 262   AuthName ...
 263   AuthnzFcgiCheckAuthnProvider FooAuthn \
 264                                Authoritative On \
 265                                RequireBasicAuth Off \
 266                                UserExpr "%{reqenv:REMOTE_USER}"
 267   Require ...
 268 &lt;/Location&gt;
 269 </highlight>
 270       </dd>
 271
 272     </dl>
 273
 274 </section>
 275
 276 <section id="examples"><title>Additional examples</title>
 277
 278   <ol>
 279     <li>If your application supports the separate authentication and
 280     authorization roles (<code>AUTHENTICATOR</code> and <code>AUTHORIZER</code>), define
 281     separate providers as follows, even if they map to the same
 282     application:
 283
 284 <highlight language="config">
 285 AuthnzFcgiDefineProvider authn  FooAuthn  fcgi://localhost:10102/
 286 AuthnzFcgiDefineProvider authz  FooAuthz  fcgi://localhost:10102/
 287 </highlight>
 288
 289     Specify the authn provider on
 290     <directive module="mod_auth_basic">AuthBasicProvider</directive>
 291     and the authz provider on
 292     <directive module="mod_authz_core">Require</directive>:
 293
 294 <highlight language="config">
 295 AuthType Basic
 296 AuthName "Restricted"
 297 AuthBasicProvider FooAuthn
 298 Require FooAuthz
 299 </highlight>
 300     </li>
 301
 302     <li>If your application supports the generic <code>AUTHORIZER</code> role
 303     (authentication and authorizer in one invocation), define a
 304     single provider as follows:
 305
 306 <highlight language="config">
 307 AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
 308 </highlight>
 309
 310     Specify the authnz provider on both <directive>AuthBasicProvider</directive>
 311     and <directive>Require</directive>:
 312
 313 <highlight language="config">
 314 AuthType Basic
 315 AuthName "Restricted"
 316 AuthBasicProvider FooAuthnz
 317 Require FooAuthnz
 318 </highlight>
 319     </li>
 320 </ol>
 321 </section>
 322
 323 <section id="limitations"><title>Limitations</title>
 324
 325     <p>The following are potential features which are not currently
 326     implemented:</p>
 327
 328     <dl>
 329       <dt>Apache httpd access checker</dt>
 330       <dd>The Apache httpd API <em>access check</em> phase is a separate
 331       phase from authentication and authorization.  Some other FastCGI
 332       implementations implement this phase, which is denoted by the
 333       setting of <code>FCGI_APACHE_ROLE</code> to <code>ACCESS_CHECKER</code>.</dd>
 334
 335       <dt>Local (Unix) sockets or pipes</dt>
 336       <dd>Only TCP sockets are currently supported.</dd>
 337
 338       <dt>Support for mod_authn_socache</dt>
 339       <dd>mod_authn_socache interaction should be implemented for
 340       applications which participate in Apache httpd-style
 341       authentication.</dd>
 342
 343       <dt>Support for digest authentication using AuthDigestProvider</dt>
 344       <dd>This is expected to be a permanent limitation as there is
 345       no authorizer flow for retrieving a hash.</dd>
 346
 347       <dt>Application process management</dt>
 348       <dd>This is expected to be permanently out of scope for
 349       this module.  Application processes must be controlled by
 350       other means.  For example, <program>fcgistarter</program> can be used to
 351       start them.</dd>
 352
 353       <dt>AP_AUTH_INTERNAL_PER_URI</dt>
 354       <dd>All providers are currently registered as
 355       AP_AUTH_INTERNAL_PER_CONF, which means that checks are not
 356       performed again for internal subrequests with the same
 357       access control configuration as the initial request.</dd>
 358
 359       <dt>Protocol data charset conversion</dt>
 360       <dd>If mod_authnz_fcgi runs in an EBCDIC compilation
 361       environment, all FastCGI protocol data is written in EBCDIC
 362       and expected to be received in EBCDIC.</dd>
 363
 364       <dt>Multiple requests per connection</dt>
 365       <dd>Currently the connection to the FastCGI authorizer is
 366       closed after every phase of processing.  For example, if the
 367       authorizer handles separate <em>authn</em> and <em>authz</em>
 368       phases then two connections will be used.</dd>
 369
 370       <dt>URI Mapping</dt>
 371       <dd>URIs from clients can't be mapped, such as with the <directive>
 372       ProxyPass</directive> used with FastCGI responders.</dd>
 373
 374     </dl>
 375
 376 </section>
 377
 378 <section id="logging"><title>Logging</title>
 379
 380     <ol>
 381         <li>Processing errors are logged at log level <code>error</code>
 382         and higher.</li>
 383         <li>Messages written by the application are logged at log
 384         level <code>warn</code>.</li>
 385         <li>General messages for debugging are logged at log level
 386         <code>debug</code>.</li>
 387         <li>Environment variables passed to the application are
 388         logged at log level <code>trace2</code>. The value of the
 389         <code>REMOTE_PASSWD</code> variable will be obscured,
 390         but <strong>any other sensitive data will be visible in the
 391         log</strong>.</li>
 392         <li>All I/O between the module and the FastCGI application,
 393         including all environment variables, will be logged in printable
 394         and hex format at log level <code>trace5</code>.  <strong>All
 395         sensitive data will be visible in the log.</strong></li>
 396     </ol>
 397
 398     <p><directive module="core">LogLevel</directive> can be used
 399     to configure a log level specific to mod_authnz_fcgi.  For
 400     example:</p>
 401
 402 <highlight language="config">
 403 LogLevel info authnz_fcgi:trace8
 404 </highlight>
 405
 406 </section>
 407
 408 <directivesynopsis>
 409 <name>AuthnzFcgiDefineProvider</name>
 410 <description>Defines a FastCGI application as a provider for
 411 authentication and/or authorization</description>
 412 <syntax>AuthnzFcgiDefineProvider <em>type</em> <em>provider-name</em>
 413 <em>backend-address</em></syntax>
 414 <default>none</default>
 415 <contextlist><context>server config</context></contextlist>
 416 <usage>
 417     <p>This directive is used to define a FastCGI application as
 418     a provider for a particular phase of authentication or
 419     authorization.</p>
 420
 421     <dl>
 422       <dt><em>type</em></dt>
 423       <dd>This must be set to <em>authn</em> for authentication,
 424       <em>authz</em> for authorization, or <em>authnz</em> for
 425       a generic FastCGI authorizer which performs both checks.</dd>
 426
 427       <dt><em>provider-name</em></dt>
 428       <dd>This is used to assign a name to the provider which is
 429       used in other directives such as
 430       <directive module="mod_auth_basic">AuthBasicProvider</directive>
 431       and
 432       <directive module="mod_authz_core">Require</directive>.</dd>
 433
 434       <dt><em>backend-address</em></dt>
 435       <dd>This specifies the address of the application, in the form
 436       <em>fcgi://hostname:port/</em>.  The application process(es)
 437       must be managed independently, such as with
 438       <program>fcgistarter</program>.</dd>
 439     </dl>
 440 </usage>
 441 </directivesynopsis>
 442
 443 <directivesynopsis>
 444 <name>AuthnzFcgiCheckAuthnProvider</name>
 445 <description>Enables a FastCGI application to handle the check_authn
 446 authentication hook.</description>
 447 <syntax>AuthnzFcgiCheckAuthnProvider <em>provider-name</em>|<code>None</code>
 448 <em>option</em> ...</syntax>
 449 <default>none</default>
 450 <contextlist><context>directory</context></contextlist>
 451 <usage>
 452     <p>This directive is used to enable a FastCGI authorizer to
 453     handle a specific processing phase of authentication or
 454     authorization.</p>
 455
 456     <p>Some capabilities of FastCGI authorizers require enablement
 457     using this directive instead of
 458     <directive>AuthBasicProvider</directive>:</p>
 459
 460     <ul>
 461       <li>Non-Basic authentication; generally, determining the user
 462       id of the client and returning it from the authorizer; see the
 463       <code>UserExpr</code> option below</li>
 464       <li>Selecting a custom response code; for a non-200 response
 465       from the authorizer, the code from the authorizer will be the
 466       status of the response</li>
 467       <li>Setting the body of a non-200 response; if the authorizer
 468       provides a response body with a non-200 response, that body
 469       will be returned to the client; up to 8192 bytes of text are
 470       supported</li>
 471     </ul>
 472
 473     <dl>
 474       <dt><em>provider-name</em></dt>
 475       <dd>This is the name of a provider defined with <directive>
 476       AuthnzFcgiDefineProvider</directive>.</dd>
 477
 478       <dt><code>None</code></dt>
 479       <dd>Specify <code>None</code> to disable a provider enabled
 480       with this directive in an outer scope, such as in a parent
 481       directory.</dd>
 482
 483       <dt><em>option</em></dt>
 484       <dd>The following options are supported:
 485
 486       <dl>
 487          <dt>Authoritative On|Off (default On)</dt>
 488          <dd>This controls whether or not other modules are allowed
 489          to run when this module has a FastCGI authorizer configured
 490          and it fails the request.</dd>
 491
 492          <dt>DefaultUser <em>userid</em></dt>
 493          <dd>When the authorizer returns success and <code>UserExpr</code>
 494          is configured and evaluates to an empty string (e.g., authorizer
 495          didn't return a variable), this value will be used as the user
 496          id.  This is typically used when the authorizer has a concept of
 497          guest, or unauthenticated, users and guest users are mapped to
 498          some specific user id for logging and other purposes.</dd>
 499
 500          <dt>RequireBasicAuth On|Off (default Off)</dt>
 501          <dd>This controls whether or not Basic auth is required
 502          before passing the request to the authorizer.  If required,
 503          the authorizer won't be invoked without a user id and
 504          password; 401 will be returned for a request without that.</dd>
 505
 506          <dt>UserExpr <em>expr</em> (no default)</dt>
 507          <dd>When Basic authentication isn't provided by the client
 508          and the authorizer determines the user, this expression,
 509          evaluated after calling the authorizer, determines the
 510          user.  The expression follows <a href="../expr.html">
 511          ap_expr syntax</a> and must resolve to a string.  A typical
 512          use is to reference a <code>Variable-<em>XXX</em></code>
 513          setting returned by the authorizer using an option like
 514          <code>UserExpr "%{reqenv:<em>XXX</em>}"</code>.  If
 515          this option is specified and the user id can't be retrieved
 516          using the expression after a successful authentication, the
 517          request will be rejected with a 500 error.</dd>
 518
 519        </dl>
 520       </dd>
 521      </dl>
 522 </usage>
 523 </directivesynopsis>
 524
 525 </modulesynopsis>