Description: | Allows a FastCGI authorizer application to handle Apache httpd authentication and authorization |
---|---|
Status: | Extension |
ModuleIdentifier: | authnz_fcgi_module |
SourceFile: | mod_authnz_fcgi.c |
Compatibility: | Available in version 2.4.10 and later |
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.
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:
authn
, mechanism AuthBasicProvider
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>
authz
, mechanism Require
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>
authnz
, mechanism AuthBasicProvider
+ Require
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>
authn
, mechanism check_user_id
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>
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
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
The following are potential features which are not currently implemented:
FCGI_APACHE_ROLE
to ACCESS_CHECKER
.fcgistarter
can be used to start them.ProxyPass
used with FastCGI responders.error
and higher.warn
.debug
.trace2
. The value of the REMOTE_PASSWD
variable will be obscured, but any other sensitive data will be visible in the log.trace5
. All sensitive data will be visible in the log.
LogLevel
can be used to configure a log level specific to mod_authnz_fcgi. For example:
LogLevel info authnz_fcgi:trace8
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
:
UserExpr
option belowAuthnzFcgiDefineProvider
.None
None
to disable a provider enabled with this directive in an outer scope, such as in a parent directory.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.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.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.
AuthBasicProvider
and Require
.fcgistarter
.
© 2017 The Apache Software Foundation
Licensed under the Apache License, Version 2.0.
https://httpd.apache.org/docs/2.4/en/mod/mod_authnz_fcgi.html