mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
* lib/webrick: Add documentation for WEBrick::HTTPAuth
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31505 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain
parent
6626b0a2c5
commit
8c2a52937f
10 changed files with 285 additions and 17 deletions
|
|
@ -1,3 +1,7 @@
|
|||
Wed May 11 08:36:38 2011 Eric Hodel <drbrain@segment7.net>
|
||||
|
||||
* lib/webrick: Add documentation for WEBrick::HTTPAuth
|
||||
|
||||
Wed May 11 03:06:35 2011 Eric Hodel <drbrain@segment7.net>
|
||||
|
||||
* lib/rss.rb: Add documentation for RSS. Patch by Steve Klabnik.
|
||||
|
|
|
|||
|
|
@ -133,6 +133,12 @@
|
|||
# +:ProxyContentHandler+ callback which will be invoked with the request and
|
||||
# respone after the remote content has been fetched.
|
||||
#
|
||||
# == Basic and Digest authentication
|
||||
#
|
||||
# WEBrick provides both Basic and Digest authentication for regular and proxy
|
||||
# servers. See WEBrick::HTTPAuth, WEBrick::HTTPAuth::BasicAuth and
|
||||
# WEBrick::HTTPAuth::DigestAuth.
|
||||
#
|
||||
# == WEBrick as a Production Web Server
|
||||
#
|
||||
# WEBrick can be run as a production server for small loads.
|
||||
|
|
|
|||
|
|
@ -15,10 +15,46 @@ require 'webrick/httpauth/htdigest'
|
|||
require 'webrick/httpauth/htgroup'
|
||||
|
||||
module WEBrick
|
||||
|
||||
##
|
||||
# HTTPAuth provides both basic and digest authentication.
|
||||
#
|
||||
# To enable authentication for requests in WEBrick you will need a user
|
||||
# database and an authenticator. To start, here's an Htpasswd database for
|
||||
# use with a DigestAuth authenticator:
|
||||
#
|
||||
# config = { :Realm => 'DigestAuth example realm' }
|
||||
#
|
||||
# htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
|
||||
# htpasswd.auth_type = WEBrick::HTTPAuth::DigestAuth
|
||||
# htpasswd.set_passwd config[:Realm], 'username', 'password'
|
||||
# htpasswd.flush
|
||||
#
|
||||
# The +:Realm+ is used to provide different access to different groups
|
||||
# across several resources on a server. Typically you'll need only one
|
||||
# realm for a server.
|
||||
#
|
||||
# This database can be used to create an authenticator:
|
||||
#
|
||||
# config[:UserDB] = htpasswd
|
||||
#
|
||||
# digest_auth = WEBrick::HTTPAuth::DigestAuth.new config
|
||||
#
|
||||
# To authenticate a request call #authenticate with a request and response
|
||||
# object in a servlet:
|
||||
#
|
||||
# def do_GET req, res
|
||||
# @authenticator.authenticate req, res
|
||||
# end
|
||||
#
|
||||
# For digest authentication the authenticator must not be created every
|
||||
# request, it must be passed in as an option via WEBrick::HTTPServer#mount.
|
||||
|
||||
module HTTPAuth
|
||||
module_function
|
||||
|
||||
def _basic_auth(req, res, realm, req_field, res_field, err_type, block)
|
||||
def _basic_auth(req, res, realm, req_field, res_field, err_type,
|
||||
block) # :nodoc:
|
||||
user = pass = nil
|
||||
if /^Basic\s+(.*)/o =~ req[req_field]
|
||||
userpass = $1
|
||||
|
|
@ -32,12 +68,26 @@ module WEBrick
|
|||
raise err_type
|
||||
end
|
||||
|
||||
def basic_auth(req, res, realm, &block)
|
||||
##
|
||||
# Simple wrapper for providing basic authentication for a request. When
|
||||
# called with a request +req+, response +res+, authentication +realm+ and
|
||||
# +block+ the block will be called with a +username+ and +password+. If
|
||||
# the block returns true the request is allowed to continue, otherwise an
|
||||
# HTTPStatus::Unauthorized error is raised.
|
||||
|
||||
def basic_auth(req, res, realm, &block) # :yield: username, password
|
||||
_basic_auth(req, res, realm, "Authorization", "WWW-Authenticate",
|
||||
HTTPStatus::Unauthorized, block)
|
||||
end
|
||||
|
||||
def proxy_basic_auth(req, res, realm, &block)
|
||||
##
|
||||
# Simple wrapper for providing basic authentication for a proxied request.
|
||||
# When called with a request +req+, response +res+, authentication +realm+
|
||||
# and +block+ the block will be called with a +username+ and +password+.
|
||||
# If the block returns true the request is allowed to continue, otherwise
|
||||
# an HTTPStatus::ProxyAuthenticationRequired error is raised.
|
||||
|
||||
def proxy_basic_auth(req, res, realm, &block) # :yield: username, password
|
||||
_basic_auth(req, res, realm, "Proxy-Authorization", "Proxy-Authenticate",
|
||||
HTTPStatus::ProxyAuthenticationRequired, block)
|
||||
end
|
||||
|
|
|
|||
|
|
@ -9,17 +9,43 @@
|
|||
|
||||
module WEBrick
|
||||
module HTTPAuth
|
||||
|
||||
##
|
||||
# Module providing generic support for both Digest and Basic
|
||||
# authentication schemes.
|
||||
|
||||
module Authenticator
|
||||
|
||||
RequestField = "Authorization"
|
||||
ResponseField = "WWW-Authenticate"
|
||||
ResponseInfoField = "Authentication-Info"
|
||||
AuthException = HTTPStatus::Unauthorized
|
||||
AuthScheme = nil # must override by the derived class
|
||||
|
||||
attr_reader :realm, :userdb, :logger
|
||||
##
|
||||
# Method of authentication, must be overriden by the including class
|
||||
|
||||
AuthScheme = nil
|
||||
|
||||
##
|
||||
# The realm this authenticator covers
|
||||
|
||||
attr_reader :realm
|
||||
|
||||
##
|
||||
# The user database for this authenticator
|
||||
|
||||
attr_reader :userdb
|
||||
|
||||
##
|
||||
# The logger for this authenticator
|
||||
|
||||
attr_reader :logger
|
||||
|
||||
private
|
||||
|
||||
##
|
||||
# Initializes the authenticator from +config+
|
||||
|
||||
def check_init(config)
|
||||
[:UserDB, :Realm].each{|sym|
|
||||
unless config[sym]
|
||||
|
|
@ -37,6 +63,9 @@ module WEBrick
|
|||
@auth_scheme = self::class::AuthScheme
|
||||
end
|
||||
|
||||
##
|
||||
# Ensures +req+ has credentials that can be authenticated.
|
||||
|
||||
def check_scheme(req)
|
||||
unless credentials = req[@request_field]
|
||||
error("no credentials in the request.")
|
||||
|
|
@ -69,6 +98,10 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Module providing generic support for both Digest and Basic
|
||||
# authentication schemes for proxies.
|
||||
|
||||
module ProxyAuthenticator
|
||||
RequestField = "Proxy-Authorization"
|
||||
ResponseField = "Proxy-Authenticate"
|
||||
|
|
|
|||
|
|
@ -13,11 +13,32 @@ require 'webrick/httpauth/authenticator'
|
|||
|
||||
module WEBrick
|
||||
module HTTPAuth
|
||||
|
||||
##
|
||||
# Basic Authentication for WEBrick
|
||||
#
|
||||
# Use this class to add basic authentication to a WEBrick servlet.
|
||||
#
|
||||
# Here is an example of how to set up a BasicAuth:
|
||||
#
|
||||
# config = { :Realm => 'BasicAuth example realm' }
|
||||
#
|
||||
# htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
|
||||
# htpasswd.set_passwd config[:Realm], 'username', 'password'
|
||||
# htpasswd.flush
|
||||
#
|
||||
# config[:UserDB] = htpasswd
|
||||
#
|
||||
# basic_auth = WEBrick::HTTPAuth::BasicAuth.new config
|
||||
|
||||
class BasicAuth
|
||||
include Authenticator
|
||||
|
||||
AuthScheme = "Basic"
|
||||
|
||||
##
|
||||
# Used by UserDB to create a basic password entry
|
||||
|
||||
def self.make_passwd(realm, user, pass)
|
||||
pass ||= ""
|
||||
pass.crypt(Utils::random_string(2))
|
||||
|
|
@ -25,11 +46,26 @@ module WEBrick
|
|||
|
||||
attr_reader :realm, :userdb, :logger
|
||||
|
||||
##
|
||||
# Creates a new BasicAuth instance.
|
||||
#
|
||||
# See WEBrick::Config::BasicAuth for default configuration entries
|
||||
#
|
||||
# You must supply the following configuration entries:
|
||||
#
|
||||
# :Realm:: The name of the realm being protected.
|
||||
# :UserDB:: A database of usernames and passwords.
|
||||
# A WEBrick::HTTPAuth::Htpasswd instance should be used.
|
||||
|
||||
def initialize(config, default=Config::BasicAuth)
|
||||
check_init(config)
|
||||
@config = default.dup.update(config)
|
||||
end
|
||||
|
||||
##
|
||||
# Authenticates a +req+ and returns a 401 Unauthorized using +res+ if
|
||||
# the authentication was not correct.
|
||||
|
||||
def authenticate(req, res)
|
||||
unless basic_credentials = check_scheme(req)
|
||||
challenge(req, res)
|
||||
|
|
@ -52,12 +88,19 @@ module WEBrick
|
|||
req.user = userid
|
||||
end
|
||||
|
||||
##
|
||||
# Returns a challenge response which asks for for authentication
|
||||
# information
|
||||
|
||||
def challenge(req, res)
|
||||
res[@response_field] = "#{@auth_scheme} realm=\"#{@realm}\""
|
||||
raise @auth_exception
|
||||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Basic authentication for proxy servers. See BasicAuth for details.
|
||||
|
||||
class ProxyBasicAuth < BasicAuth
|
||||
include ProxyAuthenticator
|
||||
end
|
||||
|
|
|
|||
|
|
@ -29,12 +29,11 @@ module WEBrick
|
|||
#
|
||||
# config = { :Realm => 'DigestAuth example realm' }
|
||||
#
|
||||
# htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
|
||||
# htpasswd.auth_type = WEBrick::HTTPAuth::DigestAuth
|
||||
# htpasswd.set_passwd config[:Realm], 'username', 'password'
|
||||
# htpasswd.flush
|
||||
# htdigest = WEBrick::HTTPAuth::Htdigest.new 'my_password_file'
|
||||
# htdigest.set_passwd config[:Realm], 'username', 'password'
|
||||
# htdigest.flush
|
||||
#
|
||||
# config[:UserDB] = htpasswd
|
||||
# config[:UserDB] = htdigest
|
||||
#
|
||||
# digest_auth = WEBrick::HTTPAuth::DigestAuth.new config
|
||||
#
|
||||
|
|
@ -51,7 +50,7 @@ module WEBrick
|
|||
attr_reader :algorithm, :qop
|
||||
|
||||
##
|
||||
# Used by UserDB to create a password entry
|
||||
# Used by UserDB to create a digest password entry
|
||||
|
||||
def self.make_passwd(realm, user, pass)
|
||||
pass ||= ""
|
||||
|
|
@ -68,8 +67,8 @@ module WEBrick
|
|||
# You must supply the following configuration entries:
|
||||
#
|
||||
# :Realm:: The name of the realm being protected.
|
||||
# :UserDB:: A database of usernames and passwords. See Htpasswd,
|
||||
# Htdigest, Htgroup
|
||||
# :UserDB:: A database of usernames and passwords.
|
||||
# A WEBrick::HTTPAuth::Htdigest instance should be used.
|
||||
|
||||
def initialize(config, default=Config::DigestAuth)
|
||||
check_init(config)
|
||||
|
|
@ -381,6 +380,9 @@ module WEBrick
|
|||
|
||||
end
|
||||
|
||||
##
|
||||
# Digest authentication for proxy servers. See DigestAuth for details.
|
||||
|
||||
class ProxyDigestAuth < DigestAuth
|
||||
include ProxyAuthenticator
|
||||
|
||||
|
|
|
|||
|
|
@ -13,9 +13,26 @@ require 'tempfile'
|
|||
|
||||
module WEBrick
|
||||
module HTTPAuth
|
||||
|
||||
##
|
||||
# Htdigest accesses apache-compatible digest password files. Passwords are
|
||||
# matched to a realm where they are valid. For security, the path for a
|
||||
# digest password database should be stored outside of the paths available
|
||||
# to the HTTP server.
|
||||
#
|
||||
# Htdigest is intended for use with WEBrick::HTTPAuth::DigestAuth and
|
||||
# stores passwords using cryptographic hashes.
|
||||
#
|
||||
# htpasswd = WEBrick::HTTPAuth::Htdigest.new 'my_password_file'
|
||||
# htpasswd.set_passwd 'my realm', 'username', 'password'
|
||||
# htpasswd.flush
|
||||
|
||||
class Htdigest
|
||||
include UserDB
|
||||
|
||||
##
|
||||
# Open a digest password database at +path+
|
||||
|
||||
def initialize(path)
|
||||
@path = path
|
||||
@mtime = Time.at(0)
|
||||
|
|
@ -26,6 +43,9 @@ module WEBrick
|
|||
reload
|
||||
end
|
||||
|
||||
##
|
||||
# Reloads passwords from the database
|
||||
|
||||
def reload
|
||||
mtime = File::mtime(@path)
|
||||
if mtime > @mtime
|
||||
|
|
@ -44,6 +64,10 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Flush the password database. If +output+ is given the database will
|
||||
# be written there instead of to the original path.
|
||||
|
||||
def flush(output=nil)
|
||||
output ||= @path
|
||||
tmp = Tempfile.new("htpasswd", File::dirname(output))
|
||||
|
|
@ -56,6 +80,10 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Retrieves a password from the database for +user+ in +realm+. If
|
||||
# +reload_db+ is true the database will be reloaded first.
|
||||
|
||||
def get_passwd(realm, user, reload_db)
|
||||
reload() if reload_db
|
||||
if hash = @digest[realm]
|
||||
|
|
@ -63,6 +91,9 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Sets a password in the database for +user+ in +realm+ to +pass+.
|
||||
|
||||
def set_passwd(realm, user, pass)
|
||||
@mutex.synchronize{
|
||||
unless @digest[realm]
|
||||
|
|
@ -72,13 +103,19 @@ module WEBrick
|
|||
}
|
||||
end
|
||||
|
||||
##
|
||||
# Removes a password from the database for +user+ in +realm+.
|
||||
|
||||
def delete_passwd(realm, user)
|
||||
if hash = @digest[realm]
|
||||
hash.delete(user)
|
||||
end
|
||||
end
|
||||
|
||||
def each
|
||||
##
|
||||
# Iterate passwords in the database.
|
||||
|
||||
def each # :yields: [user, realm, password_hash]
|
||||
@digest.keys.sort.each{|realm|
|
||||
hash = @digest[realm]
|
||||
hash.keys.sort.each{|user|
|
||||
|
|
|
|||
|
|
@ -11,7 +11,26 @@ require 'tempfile'
|
|||
|
||||
module WEBrick
|
||||
module HTTPAuth
|
||||
|
||||
##
|
||||
# Htgroup accesses apache-compatible group files. Htgroup can be used to
|
||||
# provide group-based authentication for users. Currently Htgroup is not
|
||||
# directly integrated with any authenticators in WEBrick. For security,
|
||||
# the path for a digest password database should be stored outside of the
|
||||
# paths available to the HTTP server.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# htgroup = WEBrick::HTTPAuth::Htgroup.new 'my_group_file'
|
||||
# htgroup.add 'superheroes', %w[spiderman batman]
|
||||
#
|
||||
# htgroup.members('superheroes').include? 'magneto' # => false
|
||||
|
||||
class Htgroup
|
||||
|
||||
##
|
||||
# Open a group database at +path+
|
||||
|
||||
def initialize(path)
|
||||
@path = path
|
||||
@mtime = Time.at(0)
|
||||
|
|
@ -20,6 +39,9 @@ module WEBrick
|
|||
reload
|
||||
end
|
||||
|
||||
##
|
||||
# Reload groups from the database
|
||||
|
||||
def reload
|
||||
if (mtime = File::mtime(@path)) > @mtime
|
||||
@group.clear
|
||||
|
|
@ -34,6 +56,10 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Flush the group database. If +output+ is given the database will be
|
||||
# written there instead of to the original path.
|
||||
|
||||
def flush(output=nil)
|
||||
output ||= @path
|
||||
tmp = Tempfile.new("htgroup", File::dirname(output))
|
||||
|
|
@ -48,11 +74,17 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Retrieve the list of members from +group+
|
||||
|
||||
def members(group)
|
||||
reload
|
||||
@group[group] || []
|
||||
end
|
||||
|
||||
##
|
||||
# Add an Array of +members+ to +group+
|
||||
|
||||
def add(group, members)
|
||||
@group[group] = members(group) | members
|
||||
end
|
||||
|
|
|
|||
|
|
@ -13,9 +13,27 @@ require 'tempfile'
|
|||
|
||||
module WEBrick
|
||||
module HTTPAuth
|
||||
|
||||
##
|
||||
# Htpasswd accesses apache-compatible password files. Passwords are
|
||||
# matched to a realm where they are valid. For security, the path for a
|
||||
# password database should be stored outside of the paths available to the
|
||||
# HTTP server.
|
||||
#
|
||||
# Htpasswd is intended for use with WEBrick::HTTPAuth::BasicAuth.
|
||||
#
|
||||
# To create an Htpasswd database with a single user:
|
||||
#
|
||||
# htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
|
||||
# htpasswd.set_passwd 'my realm', 'username', 'password'
|
||||
# htpasswd.flush
|
||||
|
||||
class Htpasswd
|
||||
include UserDB
|
||||
|
||||
##
|
||||
# Open a password database at +path+
|
||||
|
||||
def initialize(path)
|
||||
@path = path
|
||||
@mtime = Time.at(0)
|
||||
|
|
@ -25,6 +43,9 @@ module WEBrick
|
|||
reload
|
||||
end
|
||||
|
||||
##
|
||||
# Reload passwords from the database
|
||||
|
||||
def reload
|
||||
mtime = File::mtime(@path)
|
||||
if mtime > @mtime
|
||||
|
|
@ -48,6 +69,10 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Flush the password database. If +output+ is given the database will
|
||||
# be written there instead of to the original path.
|
||||
|
||||
def flush(output=nil)
|
||||
output ||= @path
|
||||
tmp = Tempfile.new("htpasswd", File::dirname(output))
|
||||
|
|
@ -60,20 +85,33 @@ module WEBrick
|
|||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Retrieves a password from the database for +user+ in +realm+. If
|
||||
# +reload_db+ is true the database will be reloaded first.
|
||||
|
||||
def get_passwd(realm, user, reload_db)
|
||||
reload() if reload_db
|
||||
@passwd[user]
|
||||
end
|
||||
|
||||
##
|
||||
# Sets a password in the database for +user+ in +realm+ to +pass+.
|
||||
|
||||
def set_passwd(realm, user, pass)
|
||||
@passwd[user] = make_passwd(realm, user, pass)
|
||||
end
|
||||
|
||||
##
|
||||
# Removes a password from the database for +user+ in +realm+.
|
||||
|
||||
def delete_passwd(realm, user)
|
||||
@passwd.delete(user)
|
||||
end
|
||||
|
||||
def each
|
||||
##
|
||||
# Iterate passwords in the database.
|
||||
|
||||
def each # :yields: [user, password]
|
||||
@passwd.keys.sort.each{|user|
|
||||
yield([user, @passwd[user]])
|
||||
}
|
||||
|
|
|
|||
|
|
@ -9,19 +9,42 @@
|
|||
|
||||
module WEBrick
|
||||
module HTTPAuth
|
||||
|
||||
##
|
||||
# User database mixin for HTTPAuth. This mixin dispatches user record
|
||||
# access to the underlying auth_type for this database.
|
||||
|
||||
module UserDB
|
||||
attr_accessor :auth_type # BasicAuth or DigestAuth
|
||||
|
||||
##
|
||||
# The authentication type.
|
||||
#
|
||||
# WEBrick::HTTPAuth::BasicAuth or WEBrick::HTTPAuth::DigestAuth are
|
||||
# built-in.
|
||||
|
||||
attr_accessor :auth_type
|
||||
|
||||
##
|
||||
# Creates an obscured password in +realm+ with +user+ and +password+
|
||||
# using the auth_type of this database.
|
||||
|
||||
def make_passwd(realm, user, pass)
|
||||
@auth_type::make_passwd(realm, user, pass)
|
||||
end
|
||||
|
||||
##
|
||||
# Sets a password in +realm+ with +user+ and +password+ for the
|
||||
# auth_type of this database.
|
||||
|
||||
def set_passwd(realm, user, pass)
|
||||
self[user] = pass
|
||||
end
|
||||
|
||||
##
|
||||
# Retrieves a password in +realm+ for +user+ for the auth_type of this
|
||||
# database. +reload_db+ is a dummy value.
|
||||
|
||||
def get_passwd(realm, user, reload_db=false)
|
||||
# reload_db is dummy
|
||||
make_passwd(realm, user, self[user])
|
||||
end
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in a new issue