Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

# Apache Module mod_authn_sasl Version 1.2

Available Languages: en

Description: | User authentication using Cyrus libsasl2 password verification service
Status: | External
Module Identifier: | authn_sasl_module
Source File: | mod_authn_sasl.c
Compatibility: | Available in Apache 2.2 and later

### Summary

This module provides the `mod_auth_basic` authentication front-end a way to authenticate users by checking credentials via the Cyrus SASL library. This may be interesting for setups where other daemons (e.g. for SMTP, IMAP or LDAP) already running at a machine use SASL to authenticate users. The module is also useful to authenticate users against databases that use shadow passwords. You do not need to elevate Apache HTTPD's access rights to superuser privileges. See `AuthSaslPwcheckMethod` for more information about this topic.

Note that on many systems access to the SASL database and `saslauthd` communication socket is restricted. You might have to add Apache HTTPD to the a certain system group (like sasl or similar) in order to be able to use the password verification services provided by the Cyrus SASL library.

When using `mod_auth_basic` this module is invoked with the directive `AuthBasicProvider` and a value of `sasl`. Using it with `mod_auth_digest` is unfortunately not possible for conceptual technical reasons.

### Directives

### Example Configurations

### See also

- `AuthBasicProvider`
- libsasl2 documentation

Sourceforge project

## AuthSaslPwcheckMethod Directive

Description: | Sets the pwcheck_method used by libsasl2 for authentication.
Syntax: | `AuthSaslPwcheckMethod method [method2]`
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_sasl

The `AuthSaslPwcheckMethod` directive sets the password check method used by libsasl2 for authentication. The module supports the two methods saslauthd and sasldb. If both of them are given as parameters the second one is used if the user could not be authenticated by the first one. The saslauthd can be configured to check the password with a variety of mechanisms. Please see the documentation that comes with it for more information.

For example:

`AuthSaslPwcheckMethod sasldb saslauthd`

will first try to authenticate using the sasldb method and will try saslauthd if the user could not be authenticated using sasldb. Generally using sasldb boils down to users being authenticated using the SASL database whereas saslauthd defers authentication to the SASL authentication daemon, which also ships with the libsasl2 distribution. The saslauth daemon supports a number of mechanisms of its own, which allow it to do verification of passwords in a variety of ways, including PAM, LDAP, Kerberos, to name a few. One of the mechanisms actually is sasldb, it's also offered here directly (really through the auxprop method, which is an alias for sasldb here) because it's relatively popular and can be used without running another daemon. Since saslauthd runs with superuser privileges, this is how you would, for example, want to authenticate users against the data contained in /etc/shadow or any mechanism the requires elevated privileges. See the documentation that comes with libsasl2 for more information about the methods (local copy).

If no `AuthSaslPwcheckMethod` directive is given, the authentication defaults to the saslauthd method.

## AuthSaslServiceName Directive

Description: | Sets the service name used by libsasl2 during authentication.
Syntax: | `AuthSaslServiceName name`
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_sasl

The `AuthSaslServiceName` directive sets the service name to be used by libsasl2 during user authentication. Depending on the `AuthSaslPwcheckMethod` used this name affects the way how authentication takes place. For example, if `saslauthd` is used and it is doing password verification via the `pam` mechanism, the service name is passed on to the PAM library. Thus PAM configuration is loaded from `/etc/pam.d/name`. The value of this directive is unused if you use `sasldb` on the other hand. Consult the documentation for the mechanism of you choice to see if the SASL service name is used for plaintext username/password authentication.

For example:

`AuthSaslServiceName webmail`

will use webmail as a service name, doing PAM authentication as specified in the file `/etc/pam.d/webmail` if you use `saslauthd` with the `pam` mechanism.

If no `AuthSaslServiceName` directive is given, the default service name http is used.

This directive was know as `AuthSaslAppname` up to version 1.0.2 of this module, but that name is now deprecated in favor of this one. Support for the old name may be removed from future version without further notice, so please update your configuration.

## AuthSaslDbPath Directive

Description: | Sets the path to the sasldb file used by libsasl2 for user authentication.
Syntax: | `AuthSaslDbPath path`
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_sasl

The `AuthSaslDbPath` directive sets the path to the sasldb file used by libsasl2 during user authentication. It is only needed if `AuthSaslPwcheckMethod` is set to sasldb and you don't want to or can't use the systemwide database in /etc/sasldb2. It's also good if you want to have separate databases for different web services. Keep in mind that the webserver needs to be able to access the file, so you need to give the httpd process read rights on the file. This potentially allows any script run by the webserver to read the file contents as well. So, it's a rather unsafe place to keep your most secret passwords. Using `AuthSaslPwcheckMethod` with saslauthd and the sasldb method there can effectively prevent this direct access.

For example:

`AuthSaslDbPath /var/www/sites/cms/userdb`

will use the file /var/www/sites/cms/userdb as a sasl database to look up users and passwords during authenticaton.

If no `AuthSaslDbPath` directive is given, the default path /etc/sasldb2 is used.

## AuthSaslRealm Directive

Description: | Sets the user realm(s) that may be used by libsasl2 during authentication.
Syntax: | `AuthSaslRealm realm [ realm ] ...`
Context: | directory, .htaccess
Override: | AuthConfig
Status: | Extension
Module: | mod_authn_sasl

The `AuthSaslRealm` directive sets the user realm(s) that may be used by libsasl2 during authentication. The Cyrus SASL library supports the concept of realms. A realm is an abstract set of users and certain mechanisms authenticate users in a certain realm. Users can log in with a username in the format `user@realm` to specify what realm they are in. Use this directive if you need to limit the set of allowed realms users can specify. The first realm in the list is the default realm that will be used for all users that log in without specifying a realm part in the user name.

For example:

`AuthSaslRealm acme.edu cs.acme.edu`

will require users to be member in the realm acme.edu or cs.acme.edu to be able to authenticate successfully. It will use the realm acme.edu for users who do not explicitly specify a realm in the login user name.

## Example Configuration .htaccess

This .htaccess file will let Apache HTTPD grant access only to users wo can be authenticated against saslauthd:

`AuthType Basic
AuthName "private area"
AuthBasicProvider sasl
AuthBasicAuthoritative On
AuthSaslPwcheckMethod saslauthd
Require valid-user
`

Available Languages: en