Add Digest authentication

rails · Jan 29, 2009 · 6932ae4 · 6932ae4
1 parent fbd2cd6
commit 6932ae4
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 7 deletions.
diff --git a/railties/doc/guides/html/actioncontroller_basics.html b/railties/doc/guides/html/actioncontroller_basics.html
@@ -88,7 +88,14 @@ <h2>Chapters</h2>
             </ul>
           </li>
           <li>
-          <a href="#_http_basic_authentication">HTTP Basic Authentication</a>
+          <a href="#_http_authentications">HTTP Authentications</a>
+            <ul>
+
+              <li><a href="#_http_basic_authentication">HTTP Basic Authentication</a></li>
+
+              <li><a href="#_http_digest_authentication">HTTP Digest Authentication</a></li>
+
+            </ul>
           </li>
           <li>
           <a href="#_streaming_and_file_downloads">Streaming and File Downloads</a>
@@ -803,9 +810,23 @@ <h4 id="_setting_custom_headers">9.2.1. Setting Custom Headers</h4>
 http://www.gnu.org/software/src-highlite -->
 <pre><tt>response<span style="color: #990000">.</span>headers<span style="color: #990000">[</span><span style="color: #FF0000">"Content-Type"</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"application/pdf"</span></tt></pre></div></div>
 </div>
-<h2 id="_http_basic_authentication">10. HTTP Basic Authentication</h2>
+<h2 id="_http_authentications">10. HTTP Authentications</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser&#8217;s HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, <tt>authenticate_or_request_with_http_basic</tt>.</p></div>
+<div class="paragraph"><p>Rails comes with two built-in HTTP authentication mechanisms :</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Basic Authentication
+</p>
+</li>
+<li>
+<p>
+Digest Authentication
+</p>
+</li>
+</ul></div>
+<h3 id="_http_basic_authentication">10.1. HTTP Basic Authentication</h3>
+<div class="paragraph"><p>HTTP Basic authentication is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser&#8217;s HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, <tt>authenticate_or_request_with_http_basic</tt>.</p></div>
 <div class="listingblock">
 <div class="content"><!-- Generator: GNU source-highlight 2.9
 by Lorenzo Bettini
@@ -817,7 +838,7 @@ <h2 id="_http_basic_authentication">10. HTTP Basic Authentication</h2>
 
   before_filter <span style="color: #990000">:</span>authenticate
 
-private
+  private
 
   <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> authenticate
     authenticate_or_request_with_http_basic <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>username<span style="color: #990000">,</span> password<span style="color: #990000">|</span>
@@ -827,6 +848,29 @@ <h2 id="_http_basic_authentication">10. HTTP Basic Authentication</h2>
 
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
 <div class="paragraph"><p>With this in place, you can create namespaced controllers that inherit from AdminController. The before filter will thus be run for all actions in those controllers, protecting them with HTTP Basic authentication.</p></div>
+<h3 id="_http_digest_authentication">10.2. HTTP Digest Authentication</h3>
+<div class="paragraph"><p>HTTP Digest authentication is superior to the Basic authentication as it does not require the client to send unencrypted password over the network. Using Digest authentication with Rails is quite easy and only requires using one method, <tt>authenticate_or_request_with_http_digest</tt>.</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AdminController <span style="color: #990000">&lt;</span> ApplicationController
+
+  USERS <span style="color: #990000">=</span> <span style="color: #FF0000">{</span> <span style="color: #FF0000">"lifo"</span> <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"world"</span> <span style="color: #FF0000">}</span>
+
+  before_filter <span style="color: #990000">:</span>authenticate
+
+  private
+
+  <span style="font-weight: bold"><span style="color: #0000FF">def</span></span> authenticate
+    authenticate_or_request_with_http_digest <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>username<span style="color: #990000">|</span>
+      USERS<span style="color: #990000">[</span>username<span style="color: #990000">]</span>
+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+  <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
+
+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
+<div class="paragraph"><p>As seen in the example above, <tt>authenticate_or_request_with_http_digest</tt> block takes only one argument - the username. And the block returns the password. Returning <tt>false</tt> or <tt>nil</tt> from the <tt>authenticate_or_request_with_http_digest</tt> will cause authentication failure.</p></div>
 </div>
 <h2 id="_streaming_and_file_downloads">11. Streaming and File Downloads</h2>
 <div class="sectionbody">

diff --git a/railties/doc/guides/source/actioncontroller_basics/http_auth.txt b/railties/doc/guides/source/actioncontroller_basics/http_auth.txt
@@ -1,6 +1,13 @@
-== HTTP Basic Authentication ==
+== HTTP Authentications ==
 
-Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, `authenticate_or_request_with_http_basic`.
+Rails comes with two built-in HTTP authentication mechanisms :
+
+ * Basic Authentication
+ * Digest Authentication
+
+=== HTTP Basic Authentication ===
+
+HTTP Basic authentication is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, `authenticate_or_request_with_http_basic`.
 
 [source, ruby]
 -------------------------------------
@@ -10,7 +17,7 @@ class AdminController < ApplicationController
 
   before_filter :authenticate
 
-private
+  private
 
   def authenticate
     authenticate_or_request_with_http_basic do |username, password|
@@ -22,3 +29,29 @@ end
 -------------------------------------
 
 With this in place, you can create namespaced controllers that inherit from AdminController. The before filter will thus be run for all actions in those controllers, protecting them with HTTP Basic authentication.
+
+=== HTTP Digest Authentication ===
+
+HTTP Digest authentication is superior to the Basic authentication as it does not require the client to send unencrypted password over the network. Using Digest authentication with Rails is quite easy and only requires using one method, +authenticate_or_request_with_http_digest+.
+
+[source, ruby]
+-------------------------------------
+class AdminController < ApplicationController
+
+  USERS = { "lifo" => "world" }
+
+  before_filter :authenticate
+
+  private
+
+  def authenticate
+    authenticate_or_request_with_http_digest do |username|
+      USERS[username]
+    end
+  end
+
+end
+-------------------------------------
+
+
+As seen in the example above, +authenticate_or_request_with_http_digest+ block takes only one argument - the username. And the block returns the password. Returning +false+ or +nil+ from the +authenticate_or_request_with_http_digest+ will cause authentication failure.