[TASK] finish essential authentication guide, update devise guide

Author: Nils Henning

docs/guides/2-essential/11_authentication_devise.md

@@ -136,7 +136,7 @@ class Admin::App < Matestack::Ui::App
 
   def logout_action_config
     {
-      method: :delete,
+      method: :get,
       path: destroy_admin_session_path,
       success: {
         redirect: {
@@ -180,7 +180,7 @@ While it's similar to the `Demo::App`, the `Admin::App` does have some differenc
 if admin_signed_in?
 ```
 
-There is also a logout button, using an `action` compoent.
+There is also a logout button, using an `action` component.
 
 We could now use the `Admin::App` as layout, but we need to set it with `matestack_app` in the corresponding controller and we need to include our new registry with `include Admin::Component::Registry`. 
 
@@ -581,7 +581,7 @@ class Admin::PersonsController < Admin::BaseController
 end
 ```
 
-We added all required actions according to our routes. Did you notice our controller now inherits from a `Admin::BaseController`? We need to create it in the next step, but why did we create one? Because all routes and corresponding actions belonging to the admin should not be visible without logging in as admin. Therefore we implement a `before_action` hook which calls devise `authenticate_admin!` helper, making sure that every action can only be called by a logged in admin. We could do this in our persons controller, but as we might add other controllers later they only need to inherit from our base controller and are also protected. Let's create the base controller in `app/controllers/admin/base_controller.rb`.
+We added all required actions according to our routes. Did you notice our controller now inherits from `Admin::BaseController`? We need to create it in the next step, but why did we create one? Because all routes and corresponding actions belonging to the admin should not be visible without logging in as admin. Therefore we implement a `before_action` hook which calls devise `authenticate_admin!` helper, making sure that every action can only be called by a logged in admin. We could do this in our persons controller, but as we might add other controllers later they only need to inherit from our base controller and are also protected. Let's create the base controller in `app/controllers/admin/base_controller.rb`.
 
 ```ruby
 class Admin::BaseController < ApplicationController
@@ -592,8 +592,9 @@ class Admin::BaseController < ApplicationController
 end
 ```
 
-In order for devise to use our sign in page, we need to create a custom session controller. Also we need to override the create and delete action of devise session controller, because we would else get errors or unwanted behavior. If we don't override the `create` action devise will trigger a full website reload and rerendering our sign in page, which means we couldn't handle login errors dynamically. The `delete` action needs to be overriden because devise usual redirect will not work with matestack. See below on how to create the session controller for devise and don't forget to update the routes in order to tell devise to use the correct controller.
+In order for devise to use our sign in page, we need to create a custom session controller. We also specify a path admins should be redirected to after sign out.
 
+See below on how to create the session controller for devise.
 
 `app/controllers/admin/sessions_controller.rb`
 ```ruby
@@ -607,21 +608,45 @@ class Admin::SessionsController < Devise::SessionsController
     render Admin::Pages::Sessions::SignIn
   end
 
-  def create
-    self.resource = warden.authenticate(auth_options)
-    return render json: {}, status: 401 unless resource
-    sign_in(resource_name, resource)
-    respond_with resource, location: after_sign_in_path_for(resource)
+  private
+
+  def after_sign_out_path_for(resource_or_scope)
+    new_admin_session_path
   end
 
-  def destroy
-    signed_out = (Devise.sign_out_all_scopes ? sign_out : sign_out(resource_name))
-    redirect_to new_admin_session_path, status: :see_other #https://api.rubyonrails.org/classes/ActionController/Redirecting.html
+end
+```
+
+We also need to create a custom failure app to return the expected response for login attempts with wrong credentials.
+
+`lib/devise/json_failure_app.rb`
+```ruby
+class JsonFailureApp < Devise::FailureApp
+
+  def respond
+    return super unless request.content_type == 'application/json'
+    self.status = 401
+    self.content_type = :json
   end
 
 end
 ```
 
+And tell devise to use it by requiring it in the initializer and updating the config. We also need to update the `sign_out_via` configuration parameter to use http GET requests for sign out instead of DELETE.
+
+`config/intializers/devise.rb`
+```ruby
+require "#{Rails.root}/lib/devise/json_failure_app"
+
+#...
+
+config.warden do |manager|
+  manager.failure_app = JsonFailureApp
+end
+```
+
+Finally remember to update the routes in order to tell devise to use the correct controller.
+
 `config/routes.rb`
 ```ruby
 Rails.application.routes.draw do
@@ -644,6 +669,8 @@ Rails.application.routes.draw do
 end
 ```
 
+If you want more information on why these changes and configurations are necessary take a look at our [devise guide](/docs/guides/5-authorization_authentication/devise.md).
+
 But if you try to start your application locally, visiting the admin pages doesn't work yet - what's going on?
 
 ### Styling, Layout & JavaScript
@@ -853,10 +880,12 @@ git commit -m "Add admin login to DemoApp, add default :role to Person model, re
 
 What exactly is going on under the hood with all the admin sign in stuff, you may wonder?
 
-Here's a quick overview: Instead over implementing loads of (complex) functionality with a load of implications and edge cases, we use the `Devise` gem for a rock-solid authentication. It takes care of hashing, salting and storing the password, and through the `Devise::SessionsController`, of managing the session cookie. All that's left for us to do is check for the existence of said cookie by using the `authenticate_admin!` helper. If the required cookie is not present, the controller responds with an error code.
+Here's a quick overview: Instead of implementing loads of (complex) functionality with a load of implications and edge cases, we use the `Devise` gem for a rock-solid authentication. It takes care of hashing, salting and storing the password and managing session cookies. All that's left for us to do is check for authentication of admins by using the `authenticate_admin!` helper.
 
 `Devise` could do a lot more, but as this is a basic guide, we will leave it with that. For even more fine-grained control over access rights (authorization) within your application (e.g. by introducing a superadmin or having regional and national manager roles), we recommend to take a look at two other popular Ruby/Rails gems, [Pundit](https://github.com/varvet/pundit) and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
 
+If you want to know more about using devise with matestack, checkout our [devise guide](/docs/guides/5-authorization_authentication/devise.md).
+
 ## Creating a admin
 
 In order to use the admin app we need to create an admin with credentials which we can now use to sign in.

docs/guides/5-authorization_authentication/devise.md

@@ -4,6 +4,14 @@ Devise is one of the most popular gems for authentication. Find out more about D
 
 In order to integrate it fully in matestack apps and pages we need to adjust a few things. This guide explains what exactly needs to be adjusted.
 
+## Table of contents
+
+1. [Setting up devise](#setting-up-devise)
+1. [Devise models](#devise-models)
+1. [Devise helpers](#devise-helpers)
+1. [Devise sign in](#devise-sign-in)
+1. [Devise sign out](#devise-sign-out)
+
 ## Setting up Devise
 
 We install devise by following devise [installation guide](https://github.com/plataformatec/devise/#getting-started).
@@ -19,7 +27,7 @@ config.action_mailer.default_url_options = {
 }
 ```
 
-## Devise Model
+## Devise models
 
 Generating a devise model or updating an existing one works as usual. Just use devise generator to create a model. If you already have a model which you want to extend for use with devise take a look at the devise documentation on how to do so.
 
@@ -30,7 +38,7 @@ rails generate devise user
 
 And ensure `devise_for :user` is added to the `app/config/routes.rb`
 
-## Devise Helpers
+## Devise helpers
 
 Again nothing unusual here. We can access devise helper methods inside our controllers, apps, pages and components like we would normally do. In case of our user model this means we could access `current_user` or `user_signed_in?` in apps, pages and components.
 
@@ -59,26 +67,26 @@ class ExampleController < ApplicationController
 end
 ```
 
-## Devise Login
+## Devise sign in
 
-Using the default devise login views should work without a problem, but they will not be integrated inside a matestack app. Let's assume we have a profile matestack app called `Profile::App`. If we want to take advantage of matestacks transitions features (not reloading our app layout between page transitions) we can not use devise views, because we would need to redirect to them and therefore need to reload the whole page. Requiring us for example to implement our navigation twice. In our `Profile::App` and also in the our devise sign in view.
+Using the default devise sign in views should work without a problem, but they will not be integrated with a matestack app. Let's assume we have a profile matestack app called `Profile::App`. If we want to take advantage of matestacks transitions features (not reloading our app layout between page transitions) we can not use devise views, because we would need to redirect to them and therefore need to reload the whole page. Requiring us for example to implement our navigation twice. In our `Profile::App` and also in our devise sign in view.
 
-Therefore we need to adjust a few things and create some pages. First we need a custom sign in page containing a form with email and password inputs.
+Therefore we need to adjust a few things and create some pages. First we create a custom sign in page containing a form with email and password inputs.
 
 `app/matestack/profile/pages/sessions/sign_in.rb`
 ```ruby 
 class Profile::Pages::Sessions::SignIn < Matestack::Ui::Page
 
   def response
-    heading text: 'Login'
+    heading text: 'Sign in'
     form form_config do
       form_input label: 'Email', key: :email, type: :email 
       form_input label: 'Password', key: :password, type: :password 
       form_submit do
-        button text: 'Login'
+        button text: 'Sign in'
       end
     end
-    toggl show_on: 'login_failure' do
+    toggl show_on: 'sign_in_failure' do
       'Your email or password is not valid.'
     end
   end
@@ -95,16 +103,18 @@ class Profile::Pages::Sessions::SignIn < Matestack::Ui::Page
       }
     },
     failure: {
-      emit: 'login_failure'
+      emit: 'sign_in_failure'
     }
   end
 
 end
 ```
 
-This page displays a form with a email and password input. The default required parameters for a devise login. It also contains a `toggle` component which gets shown when the event `login_failure` is emitted. This event gets emitted in case our form submit was unsuccessful as we specified it in our `form_config` hash. If the form is successful our app will make a transition to the page the server would redirect to.
+This page displays a form with an email and password input. The default required parameters for a devise sign in. It also contains a `toggle` component which gets shown when the event `sign_in_failure` is emitted. This event gets emitted in case our form submit was unsuccessful as we specified it in our `form_config` hash. If the form is successful our app will make a transition to the page the server would redirect to. 
+
+Remember to use `redirect` instead of `transition`, if you have conditional content depending on a logged in user inside your app. You have to use `redirect` because the app needs to be reloaded, which happens only with `redirect`.
 
-In order to render our sign in page when someone tries to access a route which needs authentication or someone visits the sign in page we must override devise session controller in order to render this page. We do this by configuring our routes to use a custom controller.
+In order to render our sign in page when someone tries to access a route which needs authentication or visits the sign in page we must override devise session controller in order to render our page. We do this by configuring our routes to use a custom controller.
 
 `app/config/routes.rb`
 ```ruby
@@ -117,7 +127,7 @@ Rails.application.routes.draw do
 end
 ```
 
-Override the `new` action in order to render our sign in page.
+Override the `new` action in order to render our sign in page and set the correct matestack app in the controller. Also remember to include the components registry. This is necessary if you use custom components in your app or page, because without it matestack can't resolve them.
 
 `app/controllers/users/sessions_controller.rb`
 ```ruby
@@ -135,43 +145,70 @@ class Users::SessionController < Devise::SessionController
 end
 ```
 
-Finally we need to override the create method in order to fully leverage matestacks potential. Matestack expects to retrieve a json response with a html error code if the sign in has failed due to matestacks form error handling. To achieve this we need to override the `create` method as you can see below:
+Now our sign in is nearly complete. Logging in with correct credentials works fine, but logging in with incorrect credentials triggers a page reload and doesn't show our error message. 
+
+Devise usually responds with a 401 for wrong credentials but intercepts this response and redirects to the new action. This means our `form` component recieves the response of the `new` action, which would have a success status. Therefore it redirects you resulting in a rerendering of the sign in page. So our `form` component needs to recieve a error code in order to work as expected. To achieve this we need to provide a custom failure app.
+
+Create the custom failure app under `lib/devise/json_failure_app.rb` containing following code:
 
 ```ruby
-def create
-  self.resource = warden.authenticate(auth_options)
-  return render json: {}, status: 401 unless resource
-  sign_in(resource_name, resource)
-  respond_with resource, location: after_sign_in_path_for(resource)
+class JsonFailureApp < Devise::FailureApp
+
+  def respond
+    return super unless request.content_type == 'application/json'
+    self.status = 401
+    self.content_type = :json
+  end
+
 end
 ```
 
-We stayed as close to devise implementation as possible. The important part is line 3 where we return a json response with error code 401 if warden couldn't authenticate the resource.
+We only want to overwrite the behavior of the failure app for request with `application/json` as content type, setting the status to a 401 unauthorized error and the content_type to json.
 
-**Wrap Up**
-That's it. Now you have a working fully integrated login with devise and matestack. All we needed to do was to create a sign in page, update our routes to use a custom session controller and override two methods in this controller. 
+There is only one thing left, telling devise to use our custom failure app. Therefore add/update the following lines in `config/initializers/devise.rb`.
 
-## Devise logout
+```ruby
+require "#{Rails.root}/lib/devise/json_failure_app"
 
-----
-TODO devise logout, registration etc.
-----
+config.warden do |manager|
+  manager.failure_app = JsonFailureApp
+end
+```
 
+That's it. When we now try to sign in with incorrect credentials the `form` component triggers the `sign_in_failure` event, which sets off our `toggle` component resulting in displaying the error message.
 
+**Wrap Up**
+That's it. Now you have a working sign in with devise fully integrated into matestack. All we needed to do was creating a sign in page, updating our routes to use a custom session controller, overriding the new action, creating a custom failure app and updating the devise config.
 
 
-## Example
+## Devise sign out
 
-This is just your average Rails user controller. The `before_action` gets called on initial pageload and on every subsequent AJAX request the client sends.
+Creating a sign out button in matestack is very straight forward. We use matestacks [`action` component](/docs/api/2-components/action.md) to create a sign out button. See the example below:
 
 ```ruby
-class UserController < ApplicationController
-  before_action :authenticate_user! # Devise authentication
-  matestack_app UserApp
+action sign_out_config do
+  button text: 'Sign out'
+end
+```
+```ruby
+def sign_out_config 
+  {
+     method: :get,
+     path: destroy_admin_session_path,
+     success: {
+       transition: {
+         follow_response: true
+       }
+     }
+  }
+end
+```
 
-  def show
-    render UserApp::Pages::Show # matestack page responder
-  end
+Notice the `method: :get` in the configuration hash. We use a http GET request to sign out, because the browser will follow the redirect send from devise session controller and then matestack tries to load the page where we have been redirected to. When we would use a DELETE request the action we would be redirected to from the browser will be also requested with a http DELETE request, which will result in a rails routing error. Therefore we use GET and need to configure devise accordingly by changing the `sign_out_via` configuration parameter.
 
-end
+```ruby
+# The default HTTP method used to sign out a resource. Default is :delete.
+  config.sign_out_via = :get
 ```
+
+That's all we have to do.