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

Instance Method Details

#authenticate(request, realm, &password_procedure) ⇒ Object

Returns false on a valid response, true otherwise



195
196
197
 
# File 'lib/action_controller/metal/http_authentication.rb', line 195

def authenticate(request, realm, &password_procedure)
  request.authorization && validate_digest_response(request, realm, &password_procedure)
end

#authentication_header(controller, realm) ⇒ Object 



253
254
255
256
257
258
 
# File 'lib/action_controller/metal/http_authentication.rb', line 253

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 



260
261
262
263
264
265
 
# File 'lib/action_controller/metal/http_authentication.rb', line 260

def authentication_request(controller, realm, message = nil)
  message ||= "HTTP Digest: Access denied.\n"
  authentication_header(controller, realm)
  controller.status = 401
  controller.response_body = message
end

#decode_credentials(header) ⇒ Object 



246
247
248
249
250
251
 
# File 'lib/action_controller/metal/http_authentication.rb', line 246

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 



242
243
244
 
# File 'lib/action_controller/metal/http_authentication.rb', line 242

def decode_credentials_header(request)
  decode_credentials(request.authorization)
end

#encode_credentials(http_method, credentials, password, password_is_ha1) ⇒ Object 



237
238
239
240
 
# File 'lib/action_controller/metal/http_authentication.rb', line 237

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.



227
228
229
230
231
 
# File 'lib/action_controller/metal/http_authentication.rb', line 227

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 



233
234
235
 
# File 'lib/action_controller/metal/http_authentication.rb', line 233

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.



305
306
307
308
309
310
 
# File 'lib/action_controller/metal/http_authentication.rb', line 305

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



324
325
326
 
# File 'lib/action_controller/metal/http_authentication.rb', line 324

def opaque(secret_key)
  ::Digest::MD5.hexdigest(secret_key)
end

#secret_token(request) ⇒ Object 



267
268
269
270
271
 
# File 'lib/action_controller/metal/http_authentication.rb', line 267

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.



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/action_controller/metal/http_authentication.rb', line 202

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.



317
318
319
320
321
 
# File 'lib/action_controller/metal/http_authentication.rb', line 317

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