Commit | Line | Data |
---|---|---|
d185ffb9 FT |
1 | htextauth(1) |
2 | ============ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | htextauth - HTTP Basic authenticator for ashd(7) | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | *htextauth* [*-hCs*] [*-r* 'REALM'] 'AUTHCMD' ['ARGS'...] `--` 'CHILD' ['ARGS'...] | |
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
14 | ||
15 | The *htextauth* handler starts a single child handler which it passes | |
16 | all requests it receives, assuming they pass an authentication | |
17 | test. *htextauth* will request HTTP Basic credentials from the client, | |
18 | and pass such credentials to an external program in order to verify | |
19 | them. The authentication program will be called every time a new user | |
20 | needs to be authenticated. See the AUTHENTICATION section, below, for | |
21 | the calling convention used for the authentication program. | |
22 | ||
23 | *htextauth* is a persistent handler, as defined in *ashd*(7), and the | |
24 | specified child handler must also be a persistent handler. | |
25 | ||
26 | By default, *htextauth* will cache successfully verified credentials, | |
27 | so that the authentication program does not have to be called for each | |
28 | and every request. Cached credentials are cleared from the cache when | |
29 | they have not been used for over 30 minutes. | |
30 | ||
19d4a41e FT |
31 | When authentication succeeds, *htextauth* removes the HTTP |
32 | `Authorization` header from the request before passing the request on | |
33 | to the child handler, and adds the `X-Ash-Remote-User` header in its | |
34 | place, containing the name of the authenticated user. | |
35 | ||
d185ffb9 FT |
36 | If the child handler exits, *htextauth* exits as well. |
37 | ||
38 | OPTIONS | |
39 | ------- | |
40 | ||
41 | *-h*:: | |
42 | ||
43 | Print a brief help message to standard output and exit. | |
44 | ||
45 | *-C*:: | |
46 | ||
47 | Do not cache credentials. | |
48 | ||
49 | *-s*:: | |
50 | ||
51 | Require that all requests are made over HTTPS. | |
52 | ||
53 | *-r* 'REALM':: | |
54 | ||
55 | Specify 'REALM' as the authentication realm when requesting | |
56 | credentials from the client. | |
57 | ||
58 | AUTHENTICATION | |
59 | -------------- | |
60 | ||
61 | When a previously unseen user needs to be authenticated, *htextauth* | |
62 | will fork and execute the 'AUTHCMD' program, with any arguments that | |
63 | follow. *htextauth* will pass two lines of text to the authentication | |
64 | program's standard input: the given user name on the first line, and | |
65 | the password on the second. The credentials are checked in advance so | |
66 | that they do not contain any control characters (below ASCII 32). | |
67 | ||
68 | If the authentication program successfully verifies the credentials | |
69 | and wishes to grant access to the client, it needs to exit | |
70 | successfully; that is, with exit status 0. Any other exit (including | |
71 | being killed by a signal) is taken by *htextauth* as a failure. | |
72 | ||
73 | The authentication program can specify a reason for any failure by | |
74 | writing such on standard output. If the program exits unsuccessfully, | |
75 | *htextauth* will include any such message in the error page sent to | |
76 | the client. | |
77 | ||
78 | Note that *htextauth* will wait for the authentication program to exit | |
79 | and not process any other requests until then. | |
80 | ||
ea4e6725 FT |
81 | FILES |
82 | ----- | |
83 | The file `etc/extauth/vhtpasswd` in the *ashd* source distribution is | |
84 | a simple authenticator program (written in Python) that can be used | |
85 | with *htextauth*, which verifies the given credentials against a | |
86 | simple database of users with encrypted passwords. It can be used as | |
87 | is, or as a simple example of how to produce authenticator | |
88 | programs. The accompanying `mkhtpasswd` program can be used to | |
89 | maintain the password database. | |
90 | ||
d185ffb9 FT |
91 | AUTHOR |
92 | ------ | |
93 | Fredrik Tolf <fredrik@dolda2000.com> | |
94 | ||
95 | SEE ALSO | |
96 | -------- | |
d3ef283f | 97 | *ashd*(7), RFC 2617 |