Docs:ModAuthTicket¶

Module: mod_auth_ticket

• Table of contents
• Docs:ModAuthTicket
  • Description
  • Installation
  • Options
  • Examples

Description¶

mod_auth_ticket is an auth module that provides server-level protection based on external logon scheme (OpenID, SAML, OAuth. etc). This is useful if you want to
provide a single-sign-on feature that protects multiple webapps (each webapp do
not need to support such feature - even static content can be protected).

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

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.

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: 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: auth-ticket.override = 1

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

Case 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-ticket.timeout = <seconds> - Optional, defaults to 86400

Sets lifetime of issued ticket.

Note that cookie issued by "authurl" page is only used once, and is replaced
by MAT-issued ticket (= randomly generated token) immediately. This parameter
specifies lifetime of MAT-issued ticket.

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).

Examples¶

server.modules += ("mod_auth_ticket")

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