mod_auth

MODULE

mod_auth

MODULE SUMMARY

User authentication using text files, dets or mnesia database.

DESCRIPTION

This module provides for basic user authentication using textual files, dets databases aswell as mnesia databases. The following config directives are supported:

• <Directory>
• AuthDBType
• AuthAccessPassword
• AuthUserFile
• AuthGroupFile
• AuthName
• allow
• deny
• require

The Directory config directive is central to be able to restrict access to certain areas of the server. Please read about the Directory config directive.

DIRECTIVE: "Directory"

Syntax: <Directory regexp-filename>
Default: - None -
Module: mod_auth(3)
Related: allow, deny, AuthAccessPassword AuthGroupFile, AuthUserFile, AuthName, require

<Directory> and </Directory> are used to enclose a group of directives which applies only to the named directory and sub-directories of that directory. regexp-filename is an extended regular expression (See regexp(3)). For example:

<Directory /usr/local/httpd[12]/htdocs>
     AuthAccessPassword sOmEpAsSwOrD
     AuthDBType plain
     AuthName My Secret Garden
     AuthUserFile /var/tmp/server_root/auth/user
     AuthUserFile /var/tmp/server_root/auth/group
     require user ragnar edward
     require group group1
     allow from 123.145.244.5
</Directory>
    

If multiple directory sections match the directory (or its parents), then the directives are applied with the shortest match first. For example if you have one directory section for garden/ and one for garden/flowers, the garden/ section matches first.

DIRECTIVE: "AuthDBType"

Syntax: AuthDBType plain | dets | mnesia
Default: - None -
Module: mod_auth(3)
Context: <Directory>
Related: allow, deny, AuthAccessPassword, AuthName, AuthUserFile, AuthUserFile, require

AuthDBType sets the type of authentication database that is used for this directory.

Only the dets and mnesia storage methods allow writing of dynamic user data. plain is a read only method.

If you use the mnesia storage method, you need to create the mnesia tables httpd_user and httpd_group yourself prior to starting the server.

For security reasons, make sure that the mnesia tables are stored outside the document tree of the Web server. If it is placed in the directory which it protects, clients will be able to download them.

DIRECTIVE: "AuthUserFile"

Syntax: AuthUserFile filename
Default: - None -
Module: mod_auth(3)
Context: <Directory>
Related: allow, deny, AuthDBType, AuthAccessPassword, AuthGroupFile, AuthName, require

AuthUserFile sets the name of a file which contains the list of users and passwords for user authentication. filename can be either absolute or relative to the ServerRoot.

If using the plain storage method, this file is a plain text file, where each line contains a user name followed by a colon, followed by the non-encrypted password. The behavior is undefined if user names are duplicated. For example:

ragnar:s7Xxv7
edward:wwjau8
    

If using the dets storage method, the user database is maintained by dets and should not be edited by hand. Use the API in this module to create / edit the user database.

This directive is ignored if using the mnesia storage method.

For security reasons, make sure that the AuthUserFile is stored outside the document tree of the Web server. If it is placed in the directory which it protects, clients will be able to download it.

DIRECTIVE: "AuthGroupFile"

Syntax: AuthGroupFile filename
Default: - None -
Module: mod_auth(3)
Context: <Directory>
Related: allow, deny, AuthName, AuthUserFile, AuthDBType, AuthAccessPassword, require

AuthGroupFile sets the name of a file which contains the list of user groups for user authentication. filename can be either absolute or relative to the ServerRoot.

If you use the plain storage method, the group file is a plain text file, where each line contains a group name followed by a colon, followed by the member user names separated by spaces. For example:

group1: bob joe ante
     

If using the dets storage method, the group database is maintained by dets and should not be edited by hand. Use the API in this module to create / edit the group database.

This directive is ignored if using the mnesia storage method.

For security reasons, make sure that the AuthGroupFile is stored outside the document tree of the Web server. If it is placed in the directory which it protects, clients will be able to download it.

DIRECTIVE: "AuthName"

Syntax: AuthName auth-domain
Default: - None -
Module: mod_auth(3)
Context: <Directory>
Related: allow, deny, AuthGroupFile, AuthUserFile, AuthDBType, AuthAccessPassword, require

AuthName sets the name of the authorization realm (auth-domain) for a directory. This string informs the client about which user name and password to use.

DIRECTIVE: "AuthAccessPassword"

Syntax: AuthAccessPassword password
Default: - None -
Module: mod_auth(3)
Context: <Directory>
Related: allow, deny, AuthGroupFile, AuthUserFile, AuthDBType, AuthName, require

AuthAccessPassword sets the password required for API calls. All API calls to mod_auth require this password to be specified or they will fail with the error reason not_authorized.

DIRECTIVE: "allow"

Syntax: allow from host host ...
Default: allow from all
Module: mod_auth(3)
Context: <Directory>
Related: AuthAccessPassword, deny, AuthGroupFile, AuthGroupFile, AuthName, AuthDBType require

allow defines a set of hosts which should be granted access to a given directory. host is one of the following:

all

All hosts are allowed access.

A regular expression (Read regexp(3))

All hosts having a numerical IP address matching the specific regular expression are allowed access.

For example:

allow from 123.34.56.11 150.100.23
    

The host 123.34.56.11 and all machines on the 150.100.23 subnet are allowed access.

DIRECTIVE: "deny"

Syntax: deny from host host ...
Default: deny from all
Module: mod_auth(3)
Context: <Directory>
Related: allow, AuthGroupFile, AuthGroupFile, AuthName, AuthDBType, AuthAccessPassword, require

deny defines a set of hosts which should not be granted access to a given directory. host is one of the following:

all

All hosts are denied access.

A regular expression (Read regexp(3))

All hosts having a numerical IP address matching the specific regular expression are denied access.

For example:

deny from 123.34.56.11 150.100.23
    

The host 123.34.56.11 and all machines on the 150.100.23 subnet are denied access.

DIRECTIVE: "require"

Syntax: require entity-name entity entity ...
Default: - None -
Module: mod_auth(3)
Context: <Directory>
Related: allow, deny, AuthGroupFile, AuthUserFile, AuthName, AuthDBType, AuthAccessPassword

require defines users which should be granted access to a given directory using a secret password. The allowed syntaxes are:

require user user-name user-name ...

Only the named users can access the directory.

require group group-name group-name ...

Only users in the named groups can access the directory.

EWSAPI MODULE INTERACTION

Uses the following EWSAPI interaction data, if available:

{real_name, {Path, AfterPath}}

as defined in mod_alias(3).

Exports the following EWSAPI interaction data, if possible:

{remote_user, User}

The user name with which the user has authenticated himself.

Uses the following exported EWSAPI functions:

• mod_alias:path/3

EXPORTS

add_user(UserName, Password, UserData, Port, Dir) -> true | {error, Reason}

Types:
UserName = string()
Password = string()
UserData = term()
Port = integer()
Dir = string()
Reason = term()

add_user/5 adds a user to the user database. If the operation is succesful, this function returns true. If an error occurs, {error,Reason} is returned.

delete_user(UserName, Port, Dir) -> true | {error, Reason}

Types:
UserName = string()
Port = integer()
Dir = string()
Reason = term()

delete_user/3 deletes a user from the user database. If the operation is succesful, this function returns true. If an error occurs, {error,Reason} is returned.

get_user(UserName, Port, Dir) -> {ok, #httpd_user} | {error, Reason}

Types:
UserName = string()
Port = integer()
Dir = string()
Reason = term()

get_user/3 returns a httpd_user record containing the userdata for a specific user. If the user cannot be found, {error, Reason} is returned.

list_users(Port, Dir) -> {ok, Users}

Types:
UserName = string()
Port = integer()
Dir = string()
Users = list()

list_users/2 returns a list of users in the user database for a specific Port/Dir.

add_group_member(GroupName, UserName, Port, Dir) -> true | {error, Reason}

Types:
GroupName = string()
UserName = string()
Port = integer()
Dir = string()
Reason = term()

add_group_member/4 adds a user to a group. If the group does not exist, it is created and the user is added to the group. Upon successful operation, this function returns true

delete_group_member(GroupName, UserName, Port, Dir) -> true | {error, Reason}

Types:
GroupName = string()
UserName = string()
Port = integer()
Dir = string()
Reason = term()

delete_group_member/4 adds a user to a group. If the group or the user does not exist, this function returns an error, otherwise it returns true.

list_group_members(GroupName, Port, Dir) -> {ok, Users} | {error, Reason}

Types:
GroupName = string()
Port = integer()
Dir = string()
Users = list()
Reason = term()

list_group_members/3 lists the members of a specified group. If the group does not exist or there is an error, {error, Reason} is returned.

list_groups(Port, Dir) -> {ok, Groups} | {error, Reason}

Types:
Port = integer()
Dir = string()
Groups = list()
Reason = term()

list_groups/2 lists all the groups available. If there is an error, {error, Reason} is returned.

delete_group(GroupName, Port, Dir) -> true | {error, Reason}

Types:
Port = integer()
Dir = string()
GroupName = string()
Reason = term()

delete_group/3 deletes the group specified and returns true. If there is an error, {error, Reason} is returned.

SEE ALSO

httpd(3), mod_alias(3),

AUTHORS

Mattias Nilsson - support@erlang.ericsson.se
Original implementation: Joakim Grebenö - support@erlang.ericsson.se