@@ -2,7 +2,6 @@ h1. MerbAuth - Merb Merb::Authentication h2. An extensible architecture for authentication -* Stupidly Simple * Speaks fluent HTTP, even the errors * Pluggable Architecture (so that you can use any authentication algorithms you like) * Cascading Merb::Authentication (if one method fails, another is attempted, then another. When no methods succeed, authentication fails) @@ -18,7 +17,7 @@ h2. What is it The merb-auth gem is the default implementation of merb-auth-core and merb-auth-more for the default Merb Stack. Included are: -merb-auth-slice-password # A basic slice that provides everything you need for basic password logins +merb-auth-slice-password # A basic slice that provides login and logout functionality Strategies: :default_password_form # Form based login via a "login" field and "password" field @@ -37,54 +36,58 @@ Gem Style From Source <pre><code> -git clone http://github.com/wycats/merb-more.git -cd merb-more/merb-auth +git clone http://github.com/wycats/merb.git +cd merb/merb-auth sudo rake install </code></pre> h2. Basic Setup -h3. Application Setup +h3. Application Setup (Stack) -h4. Setup your user +When you generate your application with @merb-gen app my_app@ your almost ready to go. -Setup your User resource -$ merb-gen resource users +You'll need something to protect @merb-gen resource foos@ -Ensure you have a login property -property :login, String +You'll need to make your database: @rake db:automigrate@ -Make sure you have the following in your migrations (if required) -crypted_password - String -salt - String - - -h4. Setup your configuration - -Include merb-auth in your application config/init.rb +Also you need a user <pre><code> - dependency "merb-auth" + $ merb -i + >> u = User.new(:login => "homer") + >> u.password = u.password_confirmation = "sekrit" + >> u.save </code></pre> -Setup the routing: config/router.rb +No you should setup authentication for the things you want to protect: <pre><code> - Merb::Router.prepare do - merb_auth_routes(:name_prefix => nil, :path_prefix => nil) + # config/router.rb + authenticate do + resources :foos end -</code></pre> +</pre></code> + +You can protect your controller at an action level also -Protect Your Controller <pre><code> - class MyController < Application - before :ensure_authenticated - - #... - end -</pre></code> + # app/controllers/foos.rb + before :ensure_authenticated +</code></pre> + +Fire It Up! +@merb@ +h3. Customize your setup +In the Merb.root/merb/merb-auth directory there are a couple of files that +are generated for you by the stack generator. These are @setup.rb@ and @strategies.rb@ +By default these setup merb-auth to work with the default stack. To customize it, +modify these two files to get the results you want. Serialize in and out of the session, +change the user model for use with the default strategies. +You can of course not use the default strategies and declare your own, or mix and match them. +Configure your routes in the config/router.rb file. \ No newline at end of file merb-auth/README.textile @@ -7,7 +7,8 @@ MerbAuth does not try to dictate what you should use as a user model, or how it should authenticate. Instead it focuses on the logic required to check that an object passes authentication, and store authenticated objects in the session. This is in fact the guiding principle of MerbAuth. The Session is -used as the place for authentication, with a sprinkling of controller helpers. +used as the place for authentication, with a sprinkling of controller helpers. +You can choose to protect a controller action, or a route / group of routes. This makes sense to talk about an authenticated session. For example, inside your controller: @@ -25,6 +26,9 @@ your controller: * session.abandon! sets the session to unauthenticated, and clears all session data +* session.authenticate! + authenticates the session against the active strategies + MerbAuth makes use of Merb's exception handling facilities which return correct HTTP status codes when a 200 OK would be inappropriate. To fail a login, or to force a login at any point in your controller code, simply raise an @@ -69,7 +73,7 @@ to the params hash, session etc. To pass authentication, simply return a non-nil non-false value from the @run!@ method. Any false or nil value will cause -that strategy to fail. Then the next strategy will be tried :) wait... what? +that strategy to fail. Then the next strategy will be tried. You can add as many strategies as you like and they will be tried one after another until either one is found that works (login), or none of them have @@ -93,26 +97,23 @@ h3. Customizing the user_class Notice the @user_class@ method in the above strategy examples. This is a convenience method on a strategy to provide you with the user_class to use for this strategy. You can overwrite -this method on a per strategy basis to use different user model types. +this method on a per strategy basis to use different user model types. You do not _have_ to use this method +and it's only there to keep track of the "default" user class. (if any) By default the strategy#user_class method will defer to Merb::Authentication#user_class. You can set which is the "default class" that Merb::Authentication will use in the provided strategies by -setting the class inside your model declaration. +setting it in Merb.root/merb/merb-auth/setup.rb <pre><code> - class Person - include DataMapper::Resource - - Merb::Authentication.user_class = self - #... - end + Merb::Authentication.user_class = Person + </code></pre> -This will cascade throughout the default strategies, and your own strategies vai that -Merb::Authentication::Strategy#user_class method. +This will cascade throughout the default strategies, and your own strategies using the user class +that you defined. In this case Person. -There is no default class set for Activation by default +There is no default class set for Merb::Authentication.user_class by default h3. Strategies and Inheritance @@ -138,7 +139,7 @@ To activate a registered strategy: Merb::Authentication.activate!(:defualt_password_form) </code></pre> -You can easily mix this in with your own strategies. In you lib/authentication/strategies.rb +You can easily mix this in with your own strategies. In you Merb.root/merb-auth/strategies.rb <pre><code> class MyStrategy < Merb::Authentication::Strategy def run! @@ -155,7 +156,7 @@ You can easily mix this in with your own strategies. In you lib/authentication/s end </code></pre> -This will collect them in order of decleration. i.e.: +This will collect them in order of declaration. i.e.: MyStrategy, Merb::Authentication::Strategies::Basic::OpenID, AnotherStrategy h3. Customizing the order of the strategies @@ -185,7 +186,8 @@ of #run! Merb::Authenticated::Strategies::Basic::Form, Merb::Authenticated::Strategies::Basic::BasicAuth, Merb::Authenticated::Strategies::Basic::OpenID, - ] + ], + :only => [:index] before :machine_only, :only => [:create] def index @@ -212,13 +214,14 @@ h3. Where should Strategies be defined? You should store your strategies in <pre><code> - lib - `-- authentication + merb + `-- merb-auth |-- setup.rb `-- strategies.rb </code></pre> This is a good place to put everything together so you can see what you're doing at a glance. +It is also auto included by merb-auth-core when you're using it. h3. What Strategies are there? @@ -309,27 +312,26 @@ There's at least 4 ways to provide feedback to users for failed logins. h3. Additional checks / actions to perform after the user is found Sometimes you may need to perform additional operations on the user object -before or after you grab it out of the database when authenticating it. The -Merb::Authentication class implements Extlib::Hook so you can just setup hooks to -deal with this. +after you have found a valid user in the strategy. There is a hook method +Merb::Authentication.after_authentication which is designed for this. Here's an example of checking that a user object is active after it's been found: - after :authenticate! do |instance, *args| - raise Merb::Controller::Unauthenticated, "User Not Active" unless instance.user.active? + Merb::Authentication.after_authentication do |user, request, params| + user.active? ? user : nil end + +Pass the user model on if everything is still ok. Return nil if you decide in the +after_authentication hook that the user should in fact not be allowed to be authenticated. -bq. Notice that to fail the check we raised an Unauthenticated exception. The -session is available in that block as <code>session</code> - -Really that's all there is to it. By default this plugin doesn't actually +By default this plugin doesn't actually authenticate anything ;) It's up to you to get your model going, and add an -authentication strategy. Just remember that to login, you just use -@session.authenticate(request)@ inside a controller. To logout use +authentication strategy. + +To logout use @session.abandon!@ and to force a login at any time use @raise Unauthenticated, "You Aren't Cool Enough"@ -Be aware that strategies may throw :halt for use as a before filter... h3. Contributors merb-auth/merb-auth-core/README.textile @@ -1,5 +1,25 @@ Merb::Router.extensions do - + # Use this method in your router to ensure that the user is authenticated + # + # This will run through any strategies that you have setup, or that you declare + # as an argument to the authenticate method. + # + # ===Example + # + # authenticate(OpenID) do + # resource :posts + # + # authenticate do + # match("/").to(:controller => "home") + # end + # end + # + # This is a simple example that shows protecting the entire set of routes for + # the posts resource with the OpenID strategy. + # + # The match on "/" is protected, _first_ by the OpenID strategy, + # then by the dfeeault set of stratgies. Strategies are applied from the + # outer block first, working to the inner blocks. def authenticate(*strategies, &block) p = Proc.new do |request, params| if request.session.authenticated? merb-auth/merb-auth-core/lib/merb-auth-core/router_helper.rb @@ -10,7 +10,7 @@ Strategies are really simple to implement, but we've made some basic ones availa The built in ones are basic but should be enough to get you going for most things. -To specify them, simply require them. For example,in lib/auth-strategies.rb +To specify them, simply require them. For example,in Merb.root/merb/merb-auth/strategies.rb <pre><code> Merb::Authentication.activate!(:default_password_form) @@ -33,7 +33,7 @@ h3. "User" mixins To assist with your authenticating needs, there is user mixins available to enhance your user model for basic cases. These really are just for the basic case, so if you need something extra you should -overwrite the methods, or implement (and share ;) ;) ) your requirements. +overwrite the methods, or implement your requirements. To use these, require the specific mixin, and then include it into your "User" class. merb-auth/merb-auth-more/README.textile @@ -1,23 +1,22 @@ MerbAuthSlicePassword ================== A slice for the Merb framework that uses the merb-auth-core authentication -framework. This provides basic form based login as well as basic auth login. -To see how to customize the authentication process, see merb-auth-core. +framework. This slice provides a basic login and logout function. By default +it also include the form based password logins and basic authentication. -To use this slice you should supply a User type model that logs in via an -identifier and password. i.e. "email" and "password", or "login" & "password" +To see how to customize it see the merb-auth-core -Additionally your model should implement a class level method, -authenticate(login, password) This should return the user object, or if not -found should return false or nil +To use this slice setup some strategies and make sure you have everything required there. +Usually a "User" model of some kind. -For example +To overwrite the login form, you should just create a view file in +app/views/exceptions/unauthenticated.html.erb in the host app. -User.authenticate("fred", "sekrit") #=> The user object for the "fred" login -or nil / false if not found - -You can use the salted_user mixin from merb-auth-more for use with this slice. +By default the slice will load the password_form and the basic_auth strategies. +To prevent the slice from loading strategeis use: +MerbAutheSliceDefault[:no_default_strategies] = true +<pre> ------------------------------------------------------------------------------ |-- LICENSE @@ -59,7 +58,7 @@ You can use the salted_user mixin from merb-auth-more for use with this slice. `-- main.rb - +</pre> 1. Rake tasks to package/install the gem - edit this to modify the manifest. 2. The slice application: controllers, models, helpers, views. 3. The default layout, as specified in Merb::Slices::config[:mauth_password_slice][:layout] @@ -177,4 +176,4 @@ and other runtime code from within the host application. To create your own Slice run this (somewhere outside of your merb app): -$ merb-gen slice <your-lowercase-slice-name> +$ merb-gen slice <your-lowercase-slice-name> \ No newline at end of file merb-auth/merb-auth-slice-password/README.textile 82e2e446643232200309179c37f3e5d859d009b9 Daniel Neighman has.sox@gmail.com http://github.com/wycats/merb/commit/e182e24191fcd49e489b08746cd939a81ed6e9c1 e182e24191fcd49e489b08746cd939a81ed6e9c1 2008-10-17T15:08:11-07:00 2008-10-17T15:08:11-07:00 Part of a rebase 475aca91a51bf2fa52777ca88777c0a8eca28e34 Daniel Neighman has.sox@gmail.com