Module: ActionController::HttpAuthentication::Digest
- Extended by:
- Digest
- Included in:
- Digest
- Defined in:
- lib/action_controller/metal/http_authentication.rb
Overview
Makes it dead easy to do HTTP Digest authentication.
Simple Digest example
require 'digest/md5'
class PostsController < ApplicationController
REALM = "SuperSecret"
USERS = {"dhh" => "secret", #plain text password
"dap" => Digest::MD5.hexdigest(["dap",REALM,"secret"].join(":"))} #ha1 digest password
before_action :authenticate, except: [:index]
def index
render plain: "Everyone can see me!"
end
def edit
render plain: "I'm only accessible if you know the password"
end
private
def authenticate
authenticate_or_request_with_http_digest(REALM) do |username|
USERS[username]
end
end
end
Notes
The authenticate_or_request_with_http_digest
block must return the user’s password or the ha1 digest hash so the framework can appropriately hash to check the user’s credentials. Returning nil
will cause authentication to fail.
Storing the ha1 hash: MD5(username:realm:password), is better than storing a plain password. If the password file or database is compromised, the attacker would be able to use the ha1 hash to authenticate as the user at this realm
, but would not have the user’s password to try using at other sites.
In rare instances, web servers or front proxies strip authorization headers before they reach your application. You can debug this situation by logging all environment variables, and check for HTTP_AUTHORIZATION, amongst others.
Defined Under Namespace
Modules: ControllerMethods
Instance Method Summary collapse
-
#authenticate(request, realm, &password_procedure) ⇒ Object
Returns false on a valid response, true otherwise.
- #authentication_header(controller, realm) ⇒ Object
- #authentication_request(controller, realm, message = nil) ⇒ Object
- #decode_credentials(header) ⇒ Object
- #decode_credentials_header(request) ⇒ Object
- #encode_credentials(http_method, credentials, password, password_is_ha1) ⇒ Object
-
#expected_response(http_method, uri, credentials, password, password_is_ha1 = true) ⇒ Object
Returns the expected response for a request of
http_method
touri
with the decodedcredentials
and the expectedpassword
Optional parameterpassword_is_ha1
is set totrue
by default, since best practice is to store ha1 digest instead of a plain-text password. - #ha1(credentials, password) ⇒ Object
-
#nonce(secret_key, time = Time.now) ⇒ Object
Uses an MD5 digest based on time to generate a value to be used only once.
-
#opaque(secret_key) ⇒ Object
Opaque based on digest of secret key.
- #secret_token(request) ⇒ Object
-
#validate_digest_response(request, realm, &password_procedure) ⇒ Object
Returns false unless the request credentials response value matches the expected value.
-
#validate_nonce(secret_key, request, value, seconds_to_timeout = 5 * 60) ⇒ Object
Might want a shorter timeout depending on whether the request is a PATCH, PUT, or POST, and if the client is a browser or web service.
Instance Method Details
#authenticate(request, realm, &password_procedure) ⇒ Object
Returns false on a valid response, true otherwise
197 198 199 |
# File 'lib/action_controller/metal/http_authentication.rb', line 197 def authenticate(request, realm, &password_procedure) request. && validate_digest_response(request, realm, &password_procedure) end |
#authentication_header(controller, realm) ⇒ Object
255 256 257 258 259 260 |
# File 'lib/action_controller/metal/http_authentication.rb', line 255 def authentication_header(controller, realm) secret_key = secret_token(controller.request) nonce = self.nonce(secret_key) opaque = opaque(secret_key) controller.headers["WWW-Authenticate"] = %(Digest realm="#{realm}", qop="auth", algorithm=MD5, nonce="#{nonce}", opaque="#{opaque}") end |
#authentication_request(controller, realm, message = nil) ⇒ Object
262 263 264 265 266 267 |
# File 'lib/action_controller/metal/http_authentication.rb', line 262 def authentication_request(controller, realm, = nil) ||= "HTTP Digest: Access denied.\n" authentication_header(controller, realm) controller.status = 401 controller.response_body = end |
#decode_credentials(header) ⇒ Object
248 249 250 251 252 253 |
# File 'lib/action_controller/metal/http_authentication.rb', line 248 def decode_credentials(header) ActiveSupport::HashWithIndifferentAccess[header.to_s.gsub(/^Digest\s+/, "").split(",").map do |pair| key, value = pair.split("=", 2) [key.strip, value.to_s.gsub(/^"|"$/, "").delete("'")] end] end |
#decode_credentials_header(request) ⇒ Object
244 245 246 |
# File 'lib/action_controller/metal/http_authentication.rb', line 244 def decode_credentials_header(request) decode_credentials(request.) end |
#encode_credentials(http_method, credentials, password, password_is_ha1) ⇒ Object
239 240 241 242 |
# File 'lib/action_controller/metal/http_authentication.rb', line 239 def encode_credentials(http_method, credentials, password, password_is_ha1) credentials[:response] = expected_response(http_method, credentials[:uri], credentials, password, password_is_ha1) "Digest " + credentials.sort_by { |x| x[0].to_s }.map { |v| "#{v[0]}='#{v[1]}'" }.join(", ") end |
#expected_response(http_method, uri, credentials, password, password_is_ha1 = true) ⇒ Object
Returns the expected response for a request of http_method
to uri
with the decoded credentials
and the expected password
Optional parameter password_is_ha1
is set to true
by default, since best practice is to store ha1 digest instead of a plain-text password.
229 230 231 232 233 |
# File 'lib/action_controller/metal/http_authentication.rb', line 229 def expected_response(http_method, uri, credentials, password, password_is_ha1 = true) ha1 = password_is_ha1 ? password : ha1(credentials, password) ha2 = ::Digest::MD5.hexdigest([http_method.to_s.upcase, uri].join(":")) ::Digest::MD5.hexdigest([ha1, credentials[:nonce], credentials[:nc], credentials[:cnonce], credentials[:qop], ha2].join(":")) end |
#ha1(credentials, password) ⇒ Object
235 236 237 |
# File 'lib/action_controller/metal/http_authentication.rb', line 235 def ha1(credentials, password) ::Digest::MD5.hexdigest([credentials[:username], credentials[:realm], password].join(":")) end |
#nonce(secret_key, time = Time.now) ⇒ Object
Uses an MD5 digest based on time to generate a value to be used only once.
A server-specified data string which should be uniquely generated each time a 401 response is made. It is recommended that this string be base64 or hexadecimal data. Specifically, since the string is passed in the header lines as a quoted string, the double-quote character is not allowed.
The contents of the nonce are implementation dependent. The quality of the implementation depends on a good choice. A nonce might, for example, be constructed as the base 64 encoding of
time-stamp H(time-stamp ":" ETag ":" private-key)
where time-stamp is a server-generated time or other non-repeating value, ETag is the value of the HTTP ETag header associated with the requested entity, and private-key is data known only to the server. With a nonce of this form a server would recalculate the hash portion after receiving the client authentication header and reject the request if it did not match the nonce from that header or if the time-stamp value is not recent enough. In this way the server can limit the time of the nonce’s validity. The inclusion of the ETag prevents a replay request for an updated version of the resource. (Note: including the IP address of the client in the nonce would appear to offer the server the ability to limit the reuse of the nonce to the same client that originally got it. However, that would break proxy farms, where requests from a single user often go through different proxies in the farm. Also, IP address spoofing is not that hard.)
An implementation might choose not to accept a previously used nonce or a previously used digest, in order to protect against a replay attack. Or, an implementation might choose to use one-time nonces or digests for POST, PUT, or PATCH requests and a time-stamp for GET requests. For more details on the issues involved see Section 4 of this document.
The nonce is opaque to the client. Composed of Time, and hash of Time with secret key from the Rails session secret generated upon creation of project. Ensures the time cannot be modified by client.
307 308 309 310 311 312 |
# File 'lib/action_controller/metal/http_authentication.rb', line 307 def nonce(secret_key, time = Time.now) t = time.to_i hashed = [t, secret_key] digest = ::Digest::MD5.hexdigest(hashed.join(":")) ::Base64.strict_encode64("#{t}:#{digest}") end |
#opaque(secret_key) ⇒ Object
Opaque based on digest of secret key
326 327 328 |
# File 'lib/action_controller/metal/http_authentication.rb', line 326 def opaque(secret_key) ::Digest::MD5.hexdigest(secret_key) end |
#secret_token(request) ⇒ Object
269 270 271 272 273 |
# File 'lib/action_controller/metal/http_authentication.rb', line 269 def secret_token(request) key_generator = request.key_generator http_auth_salt = request.http_auth_salt key_generator.generate_key(http_auth_salt) end |
#validate_digest_response(request, realm, &password_procedure) ⇒ Object
Returns false unless the request credentials response value matches the expected value. First try the password as a ha1 digest password. If this fails, then try it as a plain text password.
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 |
# File 'lib/action_controller/metal/http_authentication.rb', line 204 def validate_digest_response(request, realm, &password_procedure) secret_key = secret_token(request) credentials = decode_credentials_header(request) valid_nonce = validate_nonce(secret_key, request, credentials[:nonce]) if valid_nonce && realm == credentials[:realm] && opaque(secret_key) == credentials[:opaque] password = password_procedure.call(credentials[:username]) return false unless password method = request.get_header("rack.methodoverride.original_method") || request.get_header("REQUEST_METHOD") uri = credentials[:uri] [true, false].any? do |trailing_question_mark| [true, false].any? do |password_is_ha1| _uri = trailing_question_mark ? uri + "?" : uri expected = expected_response(method, _uri, credentials, password, password_is_ha1) expected == credentials[:response] end end end end |
#validate_nonce(secret_key, request, value, seconds_to_timeout = 5 * 60) ⇒ Object
Might want a shorter timeout depending on whether the request is a PATCH, PUT, or POST, and if the client is a browser or web service. Can be much shorter if the Stale directive is implemented. This would allow a user to use new nonce without prompting the user again for their username and password.
319 320 321 322 323 |
# File 'lib/action_controller/metal/http_authentication.rb', line 319 def validate_nonce(secret_key, request, value, seconds_to_timeout = 5 * 60) return false if value.nil? t = ::Base64.decode64(value).split(":").first.to_i nonce(secret_key, t) == value && (t - Time.now.to_i).abs <= seconds_to_timeout end |