Project

General

Profile

Docs ModAuthTicket » History » Revision 2

Revision 1 (tai, 2011-04-30 05:00) → Revision 2/7 (tai, 2011-04-30 05:01)

h1. Docs:ModAuthTicket 

 *Module: mod_auth_ticket* 

 {{>toc}} 

 h2. Description 

 mod_auth_ticket is an auth module that provides server-level protection base on external logon scheme (OpenID, SAML, OAuth. etc). 

 This module redirects unauthenticated access to specified external page, and let that page inject authinfo back to the module by using signed/encrypted cookie. 

 h2. Installation 

 This module is a 3rd party module and is not included in the official distribution. You can download it from: 

   https://github.com/tai/mod-auth-ticket-for-lighttpd/ 

 Standard lighttpd module building procedure works, but I have provided a Makefile that needs some editing, 
 but might be simpler for who's used to it. Before building, you'll need lighttpd source extracted somewhere. 

 h2. Options 

 Latest manual is always available from: https://github.com/tai/mod-auth-ticket-for-lighttpd/wiki/Manpage 

 *auth-ticket.name = "cookiename"* - Required 

 Cookie name to use. This cookie is first created by "authurl" page, and then redirected back to MAT to notify SSO auth result. 

 *auth-ticket.key = "secret-password"* - Required 

 Secret key to encrypt/decrypt/sign/verify cookie data between "authurl" page and MAT. Any string of any length will do. 

 For actual encryption/signing scheme used, you can select it in "authurl" page (there're several cookie formats you can choose to generate). 

 *auth-ticket.override = [012]* - Required, defaults to 2 

 Controls how browser-supplied authinfo will be handled. There are 3 cases: 

 Case 1: #1: auth-ticket.overide = 0 

     * If supplied by browser, uses "Authorization:" header instead of MAT cookie. 
     * Use case: If you dual-protect your site with (locally provided) BasicAuth and (externally provided) SSO, you can give BasicAuth a higher priority by specifying this mode. 

 Case 2: #2: auth-ticket.override = 1 

     * Also a dual-protected mode, but gives MAT cookie a higher priority. 

 Case 3: #3: auth-ticket.override = 2 

     * This is a MAT-only mode. Incoming "Authorization:" header is ignored, and will not fall back to BasicAuth even if MAT-auth has failed. This is a recommended default. 

 *auth-ticket.authurl = "url-in-case-of-authfail"* - Optional, empty by default 

 Redirection URL in case of authentication failure. 

 This page needs to work as a bridge between MAT and your selection of SSO scheme, so you would need to place your custom page to this URL. As an example of such page, see files under demo/ folder. 

 If this page is not specified, no redirection will occur. This is same as allowing anonymous access, which is useful in some use-cases (like semi-public Wiki). 

 *auth-cookie.options = "any=cookie; parameter"* - Optional, defaults to empty 

 Any other options you want to include in a cookie. 

 *auth-ticket.loglevel = [0-4]* - Optional, defaults to 1 (ERROR) 

 Sets loglevel. Currently supported levels are: 0 (FATAL), 1(ERROR), 2(WARN), 3(INFO), 4(DEBUG). If you set this to DEBUG, some sensitive information (username, issued token) will be logged (but password will not be logged - it is impossible to log one anyway). 

 h2. Examples 

 <pre> 
 server.modules += ("mod_auth_cookie") 

 $HTTP["url"] =~ "^/demo/passwd\.protected" { 
         auth-cookie.override = 2 
         auth-cookie.timeout    = 86400 
         auth-cookie.key        = "sharedsecret.passwd" 
         auth-cookie.name       = "AuthByPasswd" 
         auth-cookie.options    = "path=/; httponly;" 
         auth-cookie.authurl    = "/demo/passwd/login.php" 
 } 
 </pre>