From 6beeb1b708550be0d4a53b272283e17e5e35fe17 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:01:30 +0200 Subject: Adding upstream version 2.4.57. Signed-off-by: Daniel Baumann --- docs/manual/mod/mod_authnz_fcgi.html.en | 566 ++++++++++++++++++++++++++++++++ 1 file changed, 566 insertions(+) create mode 100644 docs/manual/mod/mod_authnz_fcgi.html.en (limited to 'docs/manual/mod/mod_authnz_fcgi.html.en') diff --git a/docs/manual/mod/mod_authnz_fcgi.html.en b/docs/manual/mod/mod_authnz_fcgi.html.en new file mode 100644 index 0000000..de10c85 --- /dev/null +++ b/docs/manual/mod/mod_authnz_fcgi.html.en @@ -0,0 +1,566 @@ + + + + + +mod_authnz_fcgi - Apache HTTP Server Version 2.4 + + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+ +
+

Apache Module mod_authnz_fcgi

+
+

Available Languages:  en  | + fr 

+
+ + + + +
Description:Allows a FastCGI authorizer application to handle Apache +httpd authentication and authorization
Status:Extension
Module Identifier:authnz_fcgi_module
Source File:mod_authnz_fcgi.c
Compatibility:Available in version 2.4.10 and later
+

Summary

+ +

This module allows FastCGI authorizer applications to + authenticate users and authorize access to resources. It supports + generic FastCGI authorizers which participate in a single phase + for authentication and authorization as well as Apache httpd-specific + authenticators and authorizors which participate in one or both + phases.

+ +

FastCGI authorizers can authenticate using user id and password, + such as for Basic authentication, or can authenticate using arbitrary + mechanisms.

+
+ +
top
+
+

Invocation modes

+ +

The invocation modes for FastCGI authorizers supported by this + module are distinguished by two characteristics, type and + auth mechanism.

+ +

Type is simply authn for authentication, + authz for authorization, or authnz for + combined authentication and authorization.

+ +

Auth mechanism refers to the Apache httpd configuration + mechanisms and processing phases, and can be + AuthBasicProvider, Require, or + check_user_id. The first two of these + correspond to the directives used to enable participation in the + appropriate processing phase.

+ +

Descriptions of each mode:

+ +
+
Type authn, mechanism + AuthBasicProvider
+ +
In this mode, + FCGI_ROLE is set to AUTHORIZER and + FCGI_APACHE_ROLE is set to AUTHENTICATOR. + The application must be defined as provider type authn + using + AuthnzFcgiDefineProvider and enabled with + AuthBasicProvider. + When invoked, the application is + expected to authenticate the client using the provided user id and + password. Example application: + +
#!/usr/bin/perl
+use FCGI;
+my $request = FCGI::Request();
+while ($request->Accept() >= 0) {
+    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
+    die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
+    die if !$ENV{'REMOTE_PASSWD'};
+    die if !$ENV{'REMOTE_USER'};
+
+    print STDERR "This text is written to the web server error log.\n";
+
+    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
+        $ENV{'REMOTE_PASSWD'} eq "bar" ) {
+        print "Status: 200\n";
+        print "Variable-AUTHN_1: authn_01\n";
+        print "Variable-AUTHN_2: authn_02\n";
+        print "\n";
+    }
+    else {
+        print "Status: 401\n\n";
+    }
+}
+ + + Example configuration: +
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/
+<Location "/protected/">
+  AuthType Basic
+  AuthName "Restricted"
+  AuthBasicProvider FooAuthn
+  Require ...
+</Location>
+ +
+ +
Type authz, mechanism + Require
+
In this mode, FCGI_ROLE is set to + AUTHORIZER and FCGI_APACHE_ROLE is set to + AUTHORIZER. The application must be defined as + provider type authz using + AuthnzFcgiDefineProvider. When invoked, the application + is expected to authorize the client using the provided user id and other + request data. Example application: +
#!/usr/bin/perl
+use FCGI;
+my $request = FCGI::Request();
+while ($request->Accept() >= 0) {
+    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHORIZER";
+    die if $ENV{'FCGI_ROLE'}        ne "AUTHORIZER";
+    die if $ENV{'REMOTE_PASSWD'};
+
+    print STDERR "This text is written to the web server error log.\n";
+
+    if ($ENV{'REMOTE_USER'} eq "foo1") {
+        print "Status: 200\n";
+        print "Variable-AUTHZ_1: authz_01\n";
+        print "Variable-AUTHZ_2: authz_02\n";
+        print "\n";
+    }
+    else {
+        print "Status: 403\n\n";
+    }
+}
+ + + Example configuration: +
AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10103/
+<Location "/protected/">
+  AuthType ...
+  AuthName ...
+  AuthBasicProvider ...
+  Require FooAuthz
+</Location>
+ +
+ +
Type authnz, mechanism + AuthBasicProvider + Require
+ +
In this mode, which supports the web server-agnostic FastCGI + AUTHORIZER protocol, FCGI_ROLE is set to + AUTHORIZER and FCGI_APACHE_ROLE is not set. + The application must be defined as provider type authnz + using + AuthnzFcgiDefineProvider. The application is expected to + handle both authentication and authorization in the same invocation + using the user id, password, and other request data. The invocation + occurs during the Apache httpd API authentication phase. If the + application returns 200 and the same provider is invoked during the + authorization phase (via Require), mod_authnz_fcgi + will return success for the authorization phase without invoking the + application. Example application: +
#!/usr/bin/perl
+use FCGI;
+my $request = FCGI::Request();
+while ($request->Accept() >= 0) {
+    die if $ENV{'FCGI_APACHE_ROLE'};
+    die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";
+    die if !$ENV{'REMOTE_PASSWD'};
+    die if !$ENV{'REMOTE_USER'};
+
+    print STDERR "This text is written to the web server error log.\n";
+
+    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
+        $ENV{'REMOTE_PASSWD'} eq "bar" &&
+        $ENV{'REQUEST_URI'} =~ m%/bar/.*%) {
+        print "Status: 200\n";
+        print "Variable-AUTHNZ_1: authnz_01\n";
+        print "Variable-AUTHNZ_2: authnz_02\n";
+        print "\n";
+    }
+    else {
+        print "Status: 401\n\n";
+    }
+}
+ + + Example configuration: +
AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
+<Location "/protected/">
+  AuthType Basic
+  AuthName "Restricted"
+  AuthBasicProvider FooAuthnz
+  Require FooAuthnz
+</Location>
+ +
+ +
Type authn, mechanism + check_user_id
+ +
In this mode, FCGI_ROLE is set to + AUTHORIZER and FCGI_APACHE_ROLE is set to + AUTHENTICATOR. The application must be defined as + provider type authn using + AuthnzFcgiDefineProvider. AuthnzFcgiCheckAuthnProvider + specifies when it is called. Example application: +
#!/usr/bin/perl
+use FCGI;
+my $request = FCGI::Request();
+while ($request->Accept() >= 0) {
+    die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR";
+    die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER";
+
+    # This authorizer assumes that the RequireBasicAuth option of 
+    # AuthnzFcgiCheckAuthnProvider is On:
+    die if !$ENV{'REMOTE_PASSWD'};
+    die if !$ENV{'REMOTE_USER'};
+
+    print STDERR "This text is written to the web server error log.\n";
+
+    if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") &&
+        $ENV{'REMOTE_PASSWD'} eq "bar" ) {
+        print "Status: 200\n";
+        print "Variable-AUTHNZ_1: authnz_01\n";
+        print "Variable-AUTHNZ_2: authnz_02\n";
+        print "\n";
+    }
+    else {
+        print "Status: 401\n\n";
+        # If a response body is written here, it will be returned to
+        # the client.
+    }
+}
+ + + Example configuration: +
AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10103/
+<Location "/protected/">
+  AuthType ...
+  AuthName ...
+  AuthnzFcgiCheckAuthnProvider FooAuthn \
+                               Authoritative On \
+                               RequireBasicAuth Off \
+                               UserExpr "%{reqenv:REMOTE_USER}"
+  Require ...
+</Location>
+ +
+ +
+ +
top
+
+

Additional examples

+ +
    +
  1. If your application supports the separate authentication and + authorization roles (AUTHENTICATOR and AUTHORIZER), define + separate providers as follows, even if they map to the same + application: + +
    AuthnzFcgiDefineProvider authn  FooAuthn  fcgi://localhost:10102/
+AuthnzFcgiDefineProvider authz  FooAuthz  fcgi://localhost:10102/
    + + + Specify the authn provider on + AuthBasicProvider + and the authz provider on + Require: + +
    AuthType Basic
+AuthName "Restricted"
+AuthBasicProvider FooAuthn
+Require FooAuthz
    + +
    2. + +
  2. If your application supports the generic AUTHORIZER role + (authentication and authorizer in one invocation), define a + single provider as follows: + +
    AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/
    + + + Specify the authnz provider on both AuthBasicProvider + and Require: + +
    AuthType Basic
+AuthName "Restricted"
+AuthBasicProvider FooAuthnz
+Require FooAuthnz
    + +
    3. +
+
top
+
+

Limitations

+ +

The following are potential features which are not currently + implemented:

+ +
+
Apache httpd access checker
+
The Apache httpd API access check phase is a separate + phase from authentication and authorization. Some other FastCGI + implementations implement this phase, which is denoted by the + setting of FCGI_APACHE_ROLE to ACCESS_CHECKER.
+ +
Local (Unix) sockets or pipes
+
Only TCP sockets are currently supported.
+ +
Support for mod_authn_socache
+
mod_authn_socache interaction should be implemented for + applications which participate in Apache httpd-style + authentication.
+ +
Support for digest authentication using AuthDigestProvider
+
This is expected to be a permanent limitation as there is + no authorizer flow for retrieving a hash.
+ +
Application process management
+
This is expected to be permanently out of scope for + this module. Application processes must be controlled by + other means. For example, fcgistarter can be used to + start them.
+ +
AP_AUTH_INTERNAL_PER_URI
+
All providers are currently registered as + AP_AUTH_INTERNAL_PER_CONF, which means that checks are not + performed again for internal subrequests with the same + access control configuration as the initial request.
+ +
Protocol data charset conversion
+
If mod_authnz_fcgi runs in an EBCDIC compilation + environment, all FastCGI protocol data is written in EBCDIC + and expected to be received in EBCDIC.
+ +
Multiple requests per connection
+
Currently the connection to the FastCGI authorizer is + closed after every phase of processing. For example, if the + authorizer handles separate authn and authz + phases then two connections will be used.
+ +
URI Mapping
+
URIs from clients can't be mapped, such as with the + ProxyPass used with FastCGI responders.
+ +
+ +
top
+
+

Logging

+ +
    +
  1. Processing errors are logged at log level error + and higher.
    2. +
  2. Messages written by the application are logged at log + level warn.
    3. +
  3. General messages for debugging are logged at log level + debug.
    4. +
  4. Environment variables passed to the application are + logged at log level trace2. The value of the + REMOTE_PASSWD variable will be obscured, + but any other sensitive data will be visible in the + log.
    5. +
  5. All I/O between the module and the FastCGI application, + including all environment variables, will be logged in printable + and hex format at log level trace5. All + sensitive data will be visible in the log.
    6. +
+ +

LogLevel can be used + to configure a log level specific to mod_authnz_fcgi. For + example:

+ +
LogLevel info authnz_fcgi:trace8
+ + +
+
top
+

AuthnzFcgiCheckAuthnProvider Directive

+ + + + + + + +
Description:Enables a FastCGI application to handle the check_authn +authentication hook.
Syntax:AuthnzFcgiCheckAuthnProvider provider-name|None +option ...
Default:none
Context:directory
Status:Extension
Module:mod_authnz_fcgi
+

This directive is used to enable a FastCGI authorizer to + handle a specific processing phase of authentication or + authorization.

+ +

Some capabilities of FastCGI authorizers require enablement + using this directive instead of + AuthBasicProvider:

+ +
    +
  • Non-Basic authentication; generally, determining the user + id of the client and returning it from the authorizer; see the + UserExpr option below
    • +
  • Selecting a custom response code; for a non-200 response + from the authorizer, the code from the authorizer will be the + status of the response
    • +
  • Setting the body of a non-200 response; if the authorizer + provides a response body with a non-200 response, that body + will be returned to the client; up to 8192 bytes of text are + supported
    • +
+ +
+
provider-name
+
This is the name of a provider defined with + AuthnzFcgiDefineProvider.
+ +
None
+
Specify None to disable a provider enabled + with this directive in an outer scope, such as in a parent + directory.
+ +
option
+
The following options are supported: + +
+
Authoritative On|Off (default On)
+
This controls whether or not other modules are allowed + to run when this module has a FastCGI authorizer configured + and it fails the request.
+ +
DefaultUser userid
+
When the authorizer returns success and UserExpr + is configured and evaluates to an empty string (e.g., authorizer + didn't return a variable), this value will be used as the user + id. This is typically used when the authorizer has a concept of + guest, or unauthenticated, users and guest users are mapped to + some specific user id for logging and other purposes.
+ +
RequireBasicAuth On|Off (default Off)
+
This controls whether or not Basic auth is required + before passing the request to the authorizer. If required, + the authorizer won't be invoked without a user id and + password; 401 will be returned for a request without that.
+ +
UserExpr expr (no default)
+
When Basic authentication isn't provided by the client + and the authorizer determines the user, this expression, + evaluated after calling the authorizer, determines the + user. The expression follows + ap_expr syntax and must resolve to a string. A typical + use is to reference a Variable-XXX + setting returned by the authorizer using an option like + UserExpr "%{reqenv:XXX}". If + this option is specified and the user id can't be retrieved + using the expression after a successful authentication, the + request will be rejected with a 500 error.
+ +
+
+
+ +
+
top
+

AuthnzFcgiDefineProvider Directive

+ + + + + + + +
Description:Defines a FastCGI application as a provider for +authentication and/or authorization
Syntax:AuthnzFcgiDefineProvider type provider-name +backend-address
Default:none
Context:server config
Status:Extension
Module:mod_authnz_fcgi
+

This directive is used to define a FastCGI application as + a provider for a particular phase of authentication or + authorization.

+ +
+
type
+
This must be set to authn for authentication, + authz for authorization, or authnz for + a generic FastCGI authorizer which performs both checks.
+ +
provider-name
+
This is used to assign a name to the provider which is + used in other directives such as + AuthBasicProvider + and + Require.
+ +
backend-address
+
This specifies the address of the application, in the form + fcgi://hostname:port/. The application process(es) + must be managed independently, such as with + fcgistarter.
+
+ +
+
+
+

Available Languages:  en  | + fr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3