.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "mod_auth_tkt 3" .TH mod_auth_tkt 3 "2019-01-26" "2.3.99b1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mod_auth_tkt \- apache ticket authentication module .SH "DESCRIPTION" .IX Header "DESCRIPTION" mod_auth_tkt is a lightweight cookie-based authentication module, written in C, for apache versions 1.3.x, 2.0.x, and 2.2.x It implements a single-signon framework that works across multiple apache instances, different apache versions, and multiple machines. .PP mod_auth_tkt itself is completely repository-agnostic, as the actual authentication is done by a user-supplied \s-1CGI\s0 or script in your language of choice (examples are provided in Perl, with contrib libraries for use with python and \s-1PHP\s0). This allows authentication against virtually any kind of user repository you can imagine (password files, ldap directories, databases, etc.) .PP mod_auth_tkt supports inactivity timeouts (including the ability to control how aggressively the ticket is refreshed), the ability to include arbitrary user data within the cookie, configurable cookie names and domains, token-based access to subsections of a site, and optional 'guest' access for unauthenticated users. .SH "CONFIGURATION" .IX Header "CONFIGURATION" mod_auth_tkt is configured in your apache configuration files using the following set of directives (all mod_auth_tkt directives begin with 'TKTAuth'): .SS "Server Directives" .IX Subsection "Server Directives" mod_auth_tkt supports two apache server-level directives, one required \&\- TKTAuthDigest, the shared secret used for digest hashing \- and one optional \- TKTAuthDigestType, the type of digest to use in ticket hashes. Both may be global or specific to a virtual host. .IP "TKTAuthSecret " 4 .IX Item "TKTAuthSecret " String \- the secret used for digest hashing. This should be kept secret and changed periodically. e.g. .Sp .Vb 1 \& TKTAuthSecret "w b@5b15#664038f.f9d8U19b7e25 664eY9ad2%4393e,a2ef" .Ve .IP "TKTAuthDigestType [ \s-1MD5\s0 | \s-1SHA256\s0 | \s-1SHA512\s0 ]" 4 .IX Item "TKTAuthDigestType [ MD5 | SHA256 | SHA512 ]" String, one of \s-1MD5\s0 | \s-1SHA256\s0 | \s-1SHA512.\s0 The digest/hash type to use in tickets. The default is \s-1MD5,\s0 which is faster, but has now been shown to be vulnerable to collision attacks. Such attacks are not directly applicable to mod_auth_tkt, which primarily relies on the security of the shared secret rather than the strength of the hashing scheme. More paranoid users will probably prefer to use one of the \s-1SHA\s0 digest types, however. .Sp The default is likely to change in a future version, so setting the digest type explicitly is encouraged. .Sp Note that using one of the \s-1SHA\s0 digest types with the perl \s-1CGI\s0 scripts requires a version of Apache::AuthTkt >= 2.1. .SS "Directory Directives" .IX Subsection "Directory Directives" All directory-level directives are optional, except that either TKTAuthLoginURL or TKTAuthGuestLogin (or both) must be set to cause mod_auth_tkt to be invoked for a particular directory. As usual, directory-level directives may be set in Directory or Location sections, or in .htaccess files. .IP "AuthType None / require " 4 .IX Item "AuthType None / require " mod_auth_tkt requires the following standard apache authentication directives to trigger authentication: .Sp .Vb 2 \& AuthType None \& require valid\-user # or require user1, user2, etc. .Ve .IP "TKTAuthLoginURL " 4 .IX Item "TKTAuthLoginURL " Standard \s-1URL\s0 to which unauthenticated users are redirected. This is a required directive unless you are using guest mode via 'TKTAuthGuestLogin on'. e.g. .Sp .Vb 1 \& TKTAuthLoginURL https://www.example.com/auth/login.cgi .Ve .IP "TKTAuthTimeoutURL " 4 .IX Item "TKTAuthTimeoutURL " \&\s-1URL\s0 to which users are redirected in the event their ticket times out. Default: TKTAuthLoginURL. e.g. .Sp .Vb 1 \& TKTAuthTimeoutURL https://www.example.com/auth/login.cgi?timeout=1 .Ve .IP "TKTAuthPostTimeoutURL " 4 .IX Item "TKTAuthPostTimeoutURL " \&\s-1URL\s0 to which users are redirected in the event their ticket times out during a \s-1POST\s0 operation. This case is distinguished to allow you to handle such cases specially \- you probably don't want to redirect back to the referrer after login, for instance. Default: TKTAuthTImeoutURL. e.g. .Sp .Vb 1 \& TKTAuthPostTimeoutURL https://www.example.com/auth/login.cgi?posttimeout=1 .Ve .IP "TKTAuthUnauthURL " 4 .IX Item "TKTAuthUnauthURL " \&\s-1URL\s0 to which users are redirected in the event that they are not authorised for a particular area e.g. incorrect tokens. .Sp .Vb 1 \& TKTAuthUnauthURL https://www.example.com/auth/login.cgi?unauth=1 .Ve .IP "TKTAuthGuestLogin " 4 .IX Item "TKTAuthGuestLogin " Flag to turn on 'guest' mode, which means that any user without a valid ticket is authenticated anyway as the TKTAuthGuestUser user. This is useful for allowing public access for guests and robots, while allowing more personalised or privileged access for users who login. Default: off. e.g. .Sp .Vb 1 \& TKTAuthGuestLogin on .Ve .IP "TKTAuthGuestCookie " 4 .IX Item "TKTAuthGuestCookie " Flag to indicate whether or not to issue a ticket cookie for guest users. Issuing a cookie is primarily useful where you are using UUID-ed guest users where you want them to keep the initial guest username you issue them for tracking purposes. e.g. .Sp .Vb 1 \& TKTAuthGuestCookie on .Ve .Sp Default is 'off', unless you use a TKTAuthGuestUser with a \s-1UUID\s0 (see next), in which case it's 'on'. Setting explicitly is recommended, however. .IP "TKTAuthGuestUser " 4 .IX Item "TKTAuthGuestUser " Username to be used for the guest user (in the ticket uid, \&\s-1REMOTE_USER\s0 environment variable, etc). .Sp On apache 2.0.x and 2.2.x (but not on apache 1.3.x), the TKTAuthGuestUser may also contain a special sprintf-like pattern '%U', which is expanded to 36\-character \s-1UUID,\s0 allowing individualised guest usernames. The \f(CW%U\fR may also include an integer <= 36 to limit the number of characters used in the \&\s-1UUID\s0 e.g. \f(CW%12U\fR, \f(CW%20U\fR etc. .Sp Default: 'guest'. Examples: .Sp .Vb 2 \& TKTAuthGuestUser visitor \& TKTAuthGuestUser guest\-%12U .Ve .IP "TKTAuthGuestFallback " 4 .IX Item "TKTAuthGuestFallback " Flag to indicate that a timed out user ticket should automatically fallback to 'guest' status, and issue a new guest ticket, instead of redirecting to the TKTAuthTimeoutURL. Only makes sense with TKTAuthGuestLogin on, of course. .Sp Default: off. .IP "TKTAuthGuestEmpty " 4 .IX Item "TKTAuthGuestEmpty " Flag to indicate that the guest username should be an empty string. Useful for allowing applications to fallback to native authentication when \s-1REMOTE_USER\s0 is empty (\s-1NOTE: REMOTE_USER\s0 must exist to satisfy Require valid-user, but will be empty). Only makes sense with TKTAuthGuestLogin on, of course. .Sp Default: off. .IP "TKTAuthTimeout " 4 .IX Item "TKTAuthTimeout " The ticket timeout period, in seconds. After this period, the ticket is considered stale, and the user is redirected to the TKTAuthTimeoutURL (if set, else to the TKTAuthLoginURL). Note that the ticket can be automatically refreshed, however, using the next setting. .Sp The following units can also be specified on the timeout (with no spaces between timeout and unit): y/years, M/months, w/weeks, d/days, h/hours, m/minutes, and s/seconds. .Sp This timeout is protected by the ticket hashing, so cannot be trivially modified, unlike the TKTAuthCookieExpires setting below. .Sp Setting TKTAuthTimeout to 0 means never timeout, but this is strongly discouraged, as it allows for trivial replay attacks. Set it to a week or two if you really don't want timeouts. .Sp Default: 2h. Examples: .Sp .Vb 3 \& TKTAuthTimeout 86400 \& TKTAuthTimeout 1w \& TKTAuthTimeout 1w 4d 3h .Ve .IP "TKTAuthTimeoutRefresh " 4 .IX Item "TKTAuthTimeoutRefresh " A number between 0 and 1 indicating whether and how to refresh ticket timestamps. 0 means never refresh (hard timeouts). 1 means refresh tickets every time. .33 (for example) means refresh if less than .33 of the timeout period remains. .Sp This is a politeness setting for those paranoid types who have their browsers set to confirm all cookies \- refreshing every time quickly becomes \s-1VERY\s0 tedious. Default: 0.5. e.g. .Sp .Vb 1 \& TKTAuthTimeoutRefresh 0.66 .Ve .IP "TKTAuthCookieName " 4 .IX Item "TKTAuthCookieName " The name used for the ticket cookie. Default: 'auth_tkt'. .IP "TKTAuthDomain " 4 .IX Item "TKTAuthDomain " The domain to use in ticket cookies, which defines the hosts for which the browser will submit this cookie. Default: the apache ServerName (either global or for a specific virtual host). .IP "TKTAuthCookieExpires " 4 .IX Item "TKTAuthCookieExpires " \&\fB\s-1NB:\s0\fR This directive is not currently supported on apache 1.3.x! .Sp The period until the cookie expires, used to set the 'expires' field on the ticket cookie, in seconds. This is useful if you want cookies to persist across browser sessions (and your login script must support it too, of course). .Sp The following units can also be specified on the expiry period (with no spaces between period and unit): y/years, M/months, w/weeks, d/days, h/hours, m/minutes, and s/seconds. .Sp Note that his is a \fBclient-side\fR setting and is not protected by the ticket hashing, so you should always set a TKTAuthTimeout in addition to using an expiry. Cookie expiries are refreshed with tickets if TKTAuthTimeoutRefresh is set. .Sp Default: none (not used). .Sp e.g. .Sp .Vb 3 \& TKTAuthCookieExpires 86400 \& TKTAuthCookieExpires 1w \& TKTAuthCookieExpires 1w 3d 4h .Ve .IP "TKTAuthBackArgName " 4 .IX Item "TKTAuthBackArgName " The name used for the back \s-1GET\s0 parameter. If this is set, mod_auth_tkt will add a \s-1GET\s0 parameter to all redirect URLs containing a URI-escaped version of the current requested page e.g. if the requested page is http://www.example.com/index.html and TKTAuthBackArgName is set to \&'back', mod_auth_tkt will add a parameter like: .Sp .Vb 1 \& back=http%3A%2F%2Fwww.example.com%2Findex.html .Ve .Sp to the TKTAuthLoginURL it redirects to, allowing your login script to redirect back to the requested page upon successful login. .Sp To omit altogether, set to the string \fBNone\fR i.e. .Sp .Vb 1 \& TKTAuthBackArgName None .Ve .Sp Default: 'back'. .IP "TKTAuthBackCookieName " 4 .IX Item "TKTAuthBackCookieName " The cookie name to use for the back cookie. If this is set, mod_auth_tkt will set a back cookie containing a URI-escaped version of current requested page when redirecting (see TKTAuthBackArgName above), instead of using a \s-1GET\s0 parameter. .Sp Default: none (not used). .IP "TKTAuthToken " 4 .IX Item "TKTAuthToken " String indicating a required token for the given location, implementing a simple form of token-based access control. If the user's ticket does not contain one or more of the required tokens in the ticket token list then mod_auth_tkt will redirect to the TKTAuthUnauthURL location (or TKTAuthLoginURL if not set). Your login script is expected to set the appropriate token list up at login time, of course. .Sp Note that this directive can be repeated, and the semantics are that \&\fBany\fR of the required tokens is sufficient for access i.e. the tokens are ORed. .Sp Default: none (not used). .Sp e.g. .Sp .Vb 2 \& TKTAuthToken finance \& TKTAuthToken admin .Ve .IP "TKTAuthIgnoreIP " 4 .IX Item "TKTAuthIgnoreIP " Flag indicating that mod_auth_tkt should ignore the client \s-1IP\s0 address in authenticating tickets (your login script must support this as well, setting the client \s-1IP\s0 address to 0.0.0.0). This is often required out on the open internet, especially if you are using an \s-1HTTPS\s0 login page (as you should) and are dealing with more than a handful of users (the typical problem being transparent \s-1HTTP\s0 proxies at ISPs). .Sp Default: 'off' i.e. ticket is only valid from the originating \&\s-1IP\s0 address. .Sp e.g. .Sp .Vb 1 \& TKTAuthIgnoreIP on .Ve .IP "TKTAuthRequireSSL " 4 .IX Item "TKTAuthRequireSSL " Flag used to indicate that tickets should be refused except in \&\s-1SSL/HTTPS\s0 protected contexts (redirects to TKTAuthLoginURL if not, which presumably would be using \s-1HTTPS\s0). Default: 'off' (\fBdon't\fR require \s-1SSL\s0). e.g. .Sp .Vb 1 \& TKTAuthRequireSSL on .Ve .Sp See also TKTAuthCookieSecure below. .IP "TKTAuthCookieSecure " 4 .IX Item "TKTAuthCookieSecure " Flag used to set the 'secure' flag on all ticket cookies issued, indicating to the browser that they should only be sent in \&\s-1SSL/HTTPS\s0 protected contexts. Default: 'off' (\fBdon't\fR set \&'secure' flag). e.g. .Sp .Vb 1 \& TKTAuthCookieSecure on .Ve .Sp TKTAuthRequireSSL and TKTAuthCookieSecure are normally used together. One case where it makes sense to use them separately is where you are proxying through a separate SSL-equipped reverse proxy, where you would want to use TKTAuthCookieSecure by itself (since the proxied request will never be via \s-1SSL\s0). .IP "TKTAuthDebug " 4 .IX Item "TKTAuthDebug " Turn on mod_auth_tkt debug output messages in your error log, with verbosity increasing with higher integer values. Current range: 1\-3. .Sp Note that you will also require apache 'LogLevel debug' set to see these messages. .SH "EXAMPLES" .IX Header "EXAMPLES" Minimal config using logins: .PP .Vb 5 \& \& AuthType None \& require valid\-user \& TKTAuthLoginURL https://www.example.com/auth/login.cgi \& .Ve .PP Minimal config using guest logins (users can still login explicitly, of course): .PP .Vb 5 \& \& AuthType None \& require valid\-user \& TKTAuthGuestLogin on \& .Ve .PP Example internet configuration: .PP .Vb 10 \& \& AuthType None \& require valid\-user \& TKTAuthLoginURL https://www.example.com/auth/login.cgi \& TKTAuthTimeoutURL https://www.example.com/auth/login.cgi?timeout=1 \& TKTAuthPostTimeoutURL https://www.example.com/auth/login.cgi?timeout=1&post=1 \& TKTAuthIgnoreIP on \& TKTAuthTimeout 2h \& TKTAuthCookieExpires 2h \& .Ve .PP Example intranet configuration: .PP .Vb 10 \& \& AuthType None \& require valid\-user \& TKTAuthGuestLogin on \& TKTAuthLoginURL https://www.example.com/auth/login.cgi \& TKTAuthTimeoutURL https://www.example.com/auth/login.cgi?timeout=1 \& TKTAuthPostTimeoutURL https://www.example.com/auth/login.cgi?timeout=1&post=1 \& TKTAuthTimeout 4h \& TKTAuthCookieExpires 4h \& .Ve .SH "SUPPORT" .IX Header "SUPPORT" Support is available on the mod_auth_tkt mailing list, courtesy of sourceforge: .IP "List" 4 .IX Item "List" modauthtkt\-users@lists.sourceforge.net .IP "List Page and Signup" 4 .IX Item "List Page and Signup" https://lists.sourceforge.net/lists/listinfo/modauthtkt\-users .IP "List Archive" 4 .IX Item "List Archive" http://sourceforge.net/mailarchive/forum.php?forum=modauthtkt\-users .SH "BUGS" .IX Header "BUGS" Ticket payload should include \s-1IP\s0 address, to make debugging \s-1IP\s0 address problems easier. .SH "AUTHOR" .IX Header "AUTHOR" Gavin Carr .SH "LICENCE" .IX Header "LICENCE" mod_auth_tkt is licensed under the terms of the Apache Licence.