README

Apache module mod_authnz_pam
============================

Apache module mod_authnz_pam serves as PAM authorization module,
supplementing authentication done by other modules, for example
mod_auth_kerb. It can also be used as a full Basic Authentication
provider for testing purposes, running the [login, password]
authentication through the PAM stack.

The primary intended use is in connection with sssd and pam_sss.so.

Module configuration
--------------------

Authorization:

Let us assume there is already Kerberos authentication configured:

    <Location /private>
      AuthType Kerberos
      AuthName "Kerberos Login"
      KrbMethodNegotiate On
      KrbMethodK5Passwd Off
      KrbAuthRealms EXAMPLE.COM
      Krb5KeyTab /etc/http.keytab
      KrbLocalUserMapping On
      Require valid-user
    </Location>

The Require valid-user line can be replaced by

    Require pam-account pam_service_name

for example to run authorization check for the Kerberos-authenticated
user using the PAM service pam_service_name.

This can be useful to get for example host-based access control from
an IPA server for the web service.

Basic Authentication:

The module is configured using the

    AuthBasicProvider PAM

directive and then by specifying the PAM service name:

    AuthPAMService name_of_the_PAM_service

      The PAM service to authenticate against.

Example:

    <Location /private>
      AuthType Basic
      AuthName "private area"
      AuthBasicProvider PAM
      AuthPAMService tlwiki
      Require valid-user
    </Location>

The PAM service needs to be configured. For the above shown
tlwiki example, file /etc/pam.d/tlwiki could be created with content

    auth    required   pam_sss.so
    account required   pam_sss.so

to authenticate against sssd.

As part of the Basic Authentication operation, both PAM authentication
and PAM account verification (auth and account in PAM service
configuration) are run. This is to ensure that the HTTP status 401
is returned when the user is not permitted to log in, allowing fallback
to different authentication mechanism. That also means that for the
above example

      AuthBasicProvider PAM
      AuthPAMService tlwiki

it is not necessary to use

      Require pam-account tlwiki

and

      Require valid-user

is enough because the account verification will be run as part of the
HTTP authentication. In fact, using Require pam-account with the same
PAM service name will cause the account PAM checks to be run twice.
On the other hand, it is possible to configure Require pam-account
with different PAM service name than the AuthPAMService value and get
two separate account PAM checks during the Basic Authentication.

Handling expired password:

    AuthPAMExpiredRedirect <URL> [<status>]

For both the authorization and HTTP Basic authentication case, if the
password the user has presented has expired (PAM return codes
PAM_CRED_EXPIRED or PAM_NEW_AUTHTOK_REQD), when AuthPAMExpiredRedirect
is specified with a URL, redirect is made to that location. For
FreeIPA server, the setting would be

    AuthPAMExpiredRedirect https://<IPA-server>/ipa/ui/reset_password.html

It is also possible to use placeholders in the URL that will be replaced
with current location (for backreference) and username (to prefill)
on the target page:

	%s	URL of the current page.
	%u	The username that was used for the PAM authentication.
	%%	The character % itself.

For example for FreeIPA 4.1+, the value can actually be

    https://<IPA-server>/ipa/ui/reset_password.html?url=%s

By default the redirect is done using 303 See Other. The redirect
status can be specified as numerical value in the 3xx range.

SELinux:

On SELinux enabled systems, boolean httpd_mod_auth_pam needs to
be enabled:

    setsebool -P httpd_mod_auth_pam 1

Building from sources
---------------------

When building from sources, command

    apxs -i -a -c mod_authnz_pam.c -lpam -Wall -pedantic

should build and install the module.

License
-------

Copyright 2014--2022 Jan Pazdziora

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.