authrocket 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '046029ce77d53804b8dd7e0a43ef4e6a0fbceb80'
-  data.tar.gz: c04d04e266dbf858013a805e31cab4dda05e6d93
+  metadata.gz: '006539bcc19e88ba57fe083333ba916e1c78cf85'
+  data.tar.gz: ced8fb000cdd3228b7682741c2d53a4241574846
 SHA512:
-  metadata.gz: 46b7098211e40024714acdffc0ec5ed7be522b3e26d4594410a2da1ab83da844d305c5ce763fd29a88b7f51d45007113f6db43e6cf58e050e27447ea2da2e6d4
-  data.tar.gz: 2d59534c2be7acf53699096c784d3a1f2cb9e68d4c75b16daf9a39f4cc1420433102485973d3bcfbce0b8aa7b4e9e357fb99d1fec3dcfeb56c6ad5e86a3cf10d
+  metadata.gz: 37784e02f496e49a7c5a5215cc6e4c9affcc9786026c0d8a7283baa1a93506b89c8bac5ddf2b9626883ef85f761c5cb9454ec9b742eff45a31407da09a61a160
+  data.tar.gz: 4406c773bf27963934be6ed067c6993b5ec49e8a93bcb8eafdef5f9dcee7c67cb14777cf016b9081192e62f4524b2e62596625ff7f2c02dae5c3841718438224

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+#### 2.4.0
+
+- Add Rails Engine for expedited setup
+
 #### 2.3.1
 
 - Properly self-configure when only using :jwt_secret

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2017 Notioneer, Inc.
+Copyright (c) 2014-2018 Notioneer, Inc.
 
 MIT License
 

data/README.md

@@ -5,124 +5,224 @@
 This gem works with both Rails and plain Ruby. It will auto-detect Rails and enable Rails-specific features as appropriate.
 
 
-## Usage
 
-For installation, add `gem 'authrocket'` to your Gemfile. More details are below.
+## Usage - Rails
 
+AuthRocket includes a streamlined Rails integration that automatically provides login and logout actions, and all relevant handling. For a new app, we highly recommend this.
 
-### Configuration
+Note: The streamlined integration requires Rails 4.2+.
 
-By default, AuthRocket automatically loads your credentials from environment variables. For such hosting environments, including Heroku, just configure these:
+To your Gemfile, add:
+
+    gem 'authrocket', require: 'authrocket/rails'
+
+Then ensure the following environment variables are set:
+
+    AUTHROCKET_LOGIN_URL  = https://sample.e1.loginrocket.com/
+    AUTHROCKET_JWT_SECRET = jsk_SAMPLE
+
+If you plan to access the AuthRocket API as well, you'll need these variables too:
 
     AUTHROCKET_API_KEY    = ko_SAMPLE
     AUTHROCKET_URL        = https://api-e1.authrocket.com/v1
     AUTHROCKET_REALM      = rl_SAMPLE   # optional
-    AUTHROCKET_JWT_SECRET = jsk_SAMPLE  # optional
+    
+Finally, add a `before_action` command to any/all controllers or actions that should require a login.
+
+For example, to protect your entire app:
+
+    class ApplicationController < ActionController::Base
+      before_action :require_valid_token
+    end
+
+Selectively exempt certain actions or controllers using the standard `skip_before_action` method:
+
+    class ContactUsController < ActionController::Base
+      skip_before_action :require_valid_token, only: [:new, :create]
+    end
+
+Helpers are provided to create login, signup, and logout links:
+
+    <%= link_to 'Login', ar_login_url %>
+    <%= link_to 'Signup', ar_signup_url %>
+    <%= link_to 'Logout', logout_path %>
+
+Both the current session and user are available to your controllers and views:
+
+    current_session # => AuthRocket::Session
+    current_user    # => AuthRocket::User
+
+Membership and Org data is accessible through those helpers as well. Be sure to tell AuthRocket to include Membership and/or Org data in the JWT (Realm -> Settings -> Sessions & JWT).
+
+    current_user.memberships
+    current_user.memberships.first.org
+    current_user.orgs
+
+See below for customization details.
+
+
+
+## Usage - everywhere else
+
+If you aren't using Rails, or if the streamlined integration above is too opinionated, use the gem without the extra Rails integration.
+
+In your Gemfile, add:
+
+    gem 'authrocket'
+
+Then set the following environment variables:
+
+    # If accessing the AuthRocket API:
+    AUTHROCKET_API_KEY    = ko_SAMPLE
+    AUTHROCKET_URL        = https://api-e1.authrocket.com/v1 # must match your account's provisioned cluster
+    AUTHROCKET_REALM      = rl_SAMPLE   # optional
+    #
+    # If using JWT-verification of AuthRocket's login tokens:
+    AUTHROCKET_JWT_SECRET = jsk_SAMPLE
+
+If you're using either Hosted LoginRocket or authrocket.js to manage logins, see Verifing login tokens below. If you plan to use the API to directly authenticate, see the [API docs](https://authrocket.com/docs/api).
+
+
 
-`AUTHROCKET_URL` must be updated based on what cluster your account is provisioned on.
+## Configuration
 
-`AUTHROCKET_REALM` is optional. If you're using a single Realm, it's easiest to add it here as an application-wide default. If you're using multiple Realms with your app, we recommend leaving it out here and setting it as you go.
+By default, AuthRocket automatically loads credentials from environment variables. This is optimal for any 12-factor deployment. Supported variables are:
 
-`AUTHROCKET_JWT_SECRET` is optional. It only should be included if you've also specified a single realm via AUTHROCKET_REALM *and* you're using hosted logins or authrocket.js. The tokens returned by both are JWT-compatible and can be verified in-app using a matching secret.
+`AUTHROCKET_API_KEY = ko_SAMPLE`
+Your AuthRocket API key. Required to use the API (but not if only performing JWT verification of login tokens).
 
-It's possible to configure AuthRocket using a Rails initializer (or other initializaiton code) too.
+`AUTHROCKET_JWT_SECRET = jsk_SAMPLE`
+Used to perform JWT signing verification of login tokens. Not required if validating all tokens using the API instead. This is a realm-specific value, so like `AUTHROCKET_REALM`, set it on a per-use basis if using multiple realms.
+
+`AUTHROCKET_LOGIN_URL = https://sample.e1.loginrocket.com/`
+The LoginRocket URL for your Connected App. Only used by the streamlined Rails integration (for redirects), but still available to use otherwise. If your app uses multiple realms, you'll need to handle this on your own. If you're using a custom domain, this will be that domain and will not contain 'loginrocket.com'.
+
+`AUTHROCKET_REALM = rl_SAMPLE`
+Sets an application-wide default realm ID. If you're using a single realm, this is definitely easiest. Certain multi-tenant apps might using multiple realms. In this case, don't set this globally, but include it as part of the `:credentials` set for each API method.
+
+`AUTHROCKET_URL = https://api-e1.authrocket.com/v1`
+The URL of the AuthRocket API server. This may vary depending on which cluster your account is provisioned on.
+
+
+It's also possible to configure AuthRocket using a Rails initializer (or other initialization code). 
 
     AuthRocket::Api.credentials = {
       api_key: 'ko_SAMPLE',
-      url: 'https://api-e1.authrocket.com/v1',
+      jwt_secret: 'jsk_SAMPLE',
+      loginrocket_url: 'https://sample.e1.loginrocket.com/',
       realm: 'rl_SAMPLE',
-      jwt_secret: 'jsk_SAMPLE'
+      url: 'https://api-e1.authrocket.com/v1'
     }
 
 
-### Hosted Logins
 
-AuthRocket has a few options to handle logins. One option is to let AuthRocket handle the login process completely, which is what's shown here. Your app only needs to verify the final login token. This example is specific to Rails, but adapt accordingly for Sinatra or any other framework.
+## Customizing the Rails integration
 
-To get started, login to AuthRocket and add a Login Policy (under Logins/Signups) for your chosen Realm (create your first Realm if you haven't already). 
+The built-in Rails integration tries to handle as much for you as possible. However, there may be times when you wish to modify the default behavior.
 
-Be sure to enable Hosted Logins (a separate step) and specify a Login Handler URL. For development purposes, we'll point the Login Handler URL to your local app. Assuming your Rails app is running on port 3000, you'd enter `http://localhost:3000/login`.
 
-After enabling Hosted Logins, take note of the LoginRocket URL. You'll need this below.
+#### The default post-login path
 
-Let's add a couple methods to your Application Controller, substituting the correct value for `LOGIN_URL`:
+After a user logs in (or signs up), they are returned to either the last page they tried to access (if known) or to `'/'` (the default path).
 
-    class ApplicationController < ActionController::Base
-      before_filter :require_user
-      # This protects *all* of your app. If that's not what
-      #   you want, then just add this to the controllers
-      #   that need to be protected.
+This default path may be changed using an initializer.
 
-      private
+Create/edit `config/initializers/authrocket.rb` and add:
 
-      LOGIN_URL = 'https://sample.e1.loginrocket.com/'
-      # This should be your app's own LoginRocket URL, as
-      #   shown in the Login Policy details.
+```ruby
+AuthRocket::Api.default_login_path = '/manage'
+```
 
-      def require_user
-        unless current_user
-          redirect_to LOGIN_URL
-        end
-      end
 
-      helper_method :current_user
-      def current_user
-        @_current_user ||= AuthRocket::Session.from_token(session[:ar_token]).try(:user)
-      end
-    end
+#### /login and /logout routes
+
+The default routes for login and logout are `/login` and `/logout`, respectively. To override them, add an initializer for AuthRocket (eg: `config/initializers/authrocket.rb`) and add:
+
+    AuthRocket::Api.use_default_routes = false
 
-Create a Login or Session controller if you don't have one already:
+Then add your own routes to `config/routes.rb`:
 
-    rails g controller logins
+    get 'mylogin' => 'logins#login'
+    get 'mylogout' => 'logins#logout'
 
-Then add login and logout methods:
 
-    class LoginsController < ApplicationController
-      skip_before_filter :require_user
+#### The login controller
 
+AuthRocket's default login controller automatically sets up the session (by storing the login token in `session[:ar_token]`) and makes a best effort at returning the user to where they were when the login request was triggered.
+
+If you require more customization than provided by modifying the default post-login path, as outlined above, you may create your own LoginsController and inherit from AuthRocket's controller:
+
+    class LoginsController < AuthRocket::ArController
       def login
-        if params[:token]
-          if AuthRocket::Session.from_token(params[:token])
-            session[:ar_token] = params[:token]
-            redirect_to root_path
-            return
-          end
+        super
+        if current_session
+          # @redir will be present if the user's previous URL was able to be
+          # saved. If not, then provide a fallback (eg: root_path,
+          # manager_path, etc).
+          redirect_to @redir || dashboard_path
         end
-        require_user
+        # else if login failed, a redirect to LoginRocket happens automatically
       end
 
       def logout
-        session[:ar_token] = nil
+        super
+        # Change the path and/or the message.
         redirect_to root_path, notice: 'You have been logged out.'
       end
     end
 
-Finally, update `config/routes.rb`:
+If you wish to replace all of the login logic, create a new, different controller that doesn't inherit from `AuthRocket::ArController` (and also override the routes, as per above). You may wish to look at `ArController` as a reference.
 
-    get '/login' => 'logins#login'
-    get '/logout' => 'logins#logout'
 
-That's it. You're all done!
 
+## Verifying login tokens
 
-### Other Methods
+If you're not using the streamlined Rails integration, you'll need to verify the login tokens (unless you're using the API to authenticate directly).
 
-For full details on the AuthRocket API, including examples for Ruby, see our [documentation](http://authrocket.com/docs).
 
+#### JWT verification
 
-## Installation
+AuthRocket's login tokens use the JWT standard and are cryptographically signed. Verifying the signature is extremely fast. Here's are a couple examples of using this:
 
-Add this line to your application's Gemfile:
+    def current_user
+      @_current_user ||= AuthRocket::Session.from_token(session[:ar_token]).try(:user)
+    end
 
-    gem 'authrocket'
+`from_token` returns `nil` if the token is missing, expired, or otherwise invalid.
 
-And then execute:
 
-    $ bundle
+#### API verification
 
-Or install it yourself as:
+AuthRocket also supports Managed Sessions, which enables you to enforce logouts, even across apps (single sign-out!). In this instance, the session is regularly verified using the AuthRocket API.
+
+    def current_user
+      @_current_user ||= AuthRocket::Session.retrieve(session[:ar_token]).try(:user)
+    end
+
+For better performance (and to avoid API rate limits), you may want to cache the results of the API call for 3-15 minutes.
+
+
+#### Initial login
+
+Each of the above are designed for ongoing use. The initial login isn't going to be much different though. Here's an example login action:
+
+    def login
+      if params[:token]
+        if AuthRocket::Session.from_token(params[:token])
+          session[:ar_token] = params[:token]
+          redirect_to '/'
+          return
+        end
+      end
+      redirect_to AuthRocket::Api.credentials[:loginrocket_url]
+    end
+
+
+
+## Reference
+
+For full details on the AuthRocket API, including examples for Ruby, see our [documentation](https://authrocket.com/docs).
 
-    $ gem install authrocket
 
 
 ## Contributing
@@ -134,6 +234,7 @@ Or install it yourself as:
 5. Create new Pull Request
 
 
+
 ## License
 
 MIT

data/app/controllers/auth_rocket/ar_controller.rb

@@ -0,0 +1,44 @@
+class AuthRocket::ArController < ::ApplicationController
+
+  before_action :require_valid_token, only: []
+    # ensure :require_valid_token is known so it can be skipped
+  skip_before_action :require_valid_token
+    # in case it's globally applied to ApplicationController
+
+  def login
+    if params[:token]
+      if s = AuthRocket::Session.from_token(params[:token])
+        @_current_session = s
+        session[:ar_token] = params[:token]
+      end
+    end
+    if current_session
+      @redir = sanitize_redir || session[:last_url]
+      session[:last_url] = nil
+      # redirect in the child
+    else
+      require_valid_token
+    end
+  end
+
+  def logout
+    if current_session && current_session.id =~ /^kss_/ && AuthRocket::Api.credentials[:api_key]
+      AuthRocket::Session.delete current_session.id
+    end
+    session[:ar_token] = nil
+    # redirect in the child
+  end
+
+
+  private
+
+  # sanitize by making it path-only
+  def sanitize_redir(redir=params[:redir])
+    return if redir.blank?
+    u = defined?(Addressable) ? Addressable::URI.parse(redir) : URI.parse(redir)
+    if u
+      [u.path, u.query].compact.join('?')
+    end
+  end
+
+end

data/app/controllers/logins_controller.rb

@@ -0,0 +1,15 @@
+class LoginsController < AuthRocket::ArController
+
+  def login
+    super
+    if current_session
+      redirect_to @redir || AuthRocket::Api.default_login_path
+    end
+  end
+
+  def logout
+    super
+    redirect_to '/', notice: 'You have been logged out.'
+  end
+
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+Rails.application.routes.draw do
+
+  if AuthRocket::Api.use_default_routes
+    get 'login' => 'logins#login'
+    get 'logout' => 'logins#logout'
+  end
+
+end

data/lib/authrocket/api/api_config.rb

@@ -21,6 +21,12 @@ module AuthRocket
         realm:   ENV['AUTHROCKET_REALM'],
         jwt_secret: ENV['AUTHROCKET_JWT_SECRET']
       }
+    else
+      self.credentials = {}
+    end
+
+    if ENV['AUTHROCKET_LOGIN_URL']
+      self.credentials[:loginrocket_url] = ENV['AUTHROCKET_LOGIN_URL']
     end
 
     self.debug = false
@@ -35,6 +41,13 @@ module AuthRocket
     self.auth_header_prefix = 'X-Authrocket'
 
     self.credentials_error_message = %Q{Missing API credentials or URL. Set default credentials using "AuthRocket::Api.credentials = {api_key: YOUR_API_KEY, url: AR_REGION_URL}"}
+
+
+    mattr_accessor :use_default_routes
+    self.use_default_routes = true
+
+    mattr_accessor :default_login_path
+    self.default_login_path = '/'
   end
 
 

data/lib/authrocket/api/client.rb

@@ -5,7 +5,7 @@ module AuthRocket
     module ClassMethods
 
       def parse_credentials(creds)
-        creds.with_indifferent_access.except :jwt_secret
+        creds.with_indifferent_access.except :loginrocket_url, :jwt_secret
       end
 
     end

data/lib/authrocket/api/version.rb

@@ -1,3 +1,3 @@
 module AuthRocket
-  VERSION = '2.3.1'
+  VERSION = '2.4.0'
 end

data/lib/authrocket/rails.rb

@@ -0,0 +1,5 @@
+require_relative '../authrocket'
+
+%w(engine).each do |f|
+  require_relative "rails/#{f}"
+end

data/lib/authrocket/rails/controller_helper.rb

@@ -0,0 +1,47 @@
+module AuthRocket::ControllerHelper
+  extend ActiveSupport::Concern
+
+  included do
+    if respond_to?(:helper_method)
+      helper_method :current_session
+      helper_method :current_user
+      helper_method :ar_login_url
+      helper_method :ar_signup_url
+    end
+  end
+
+
+  def require_valid_token
+    unless current_session
+      session[:last_url] = request.get? ? url_for(params.to_unsafe_h.except(:domain, :host, :port, :prototcol, :subdomain, :token)) : url_for
+      redirect_to ar_login_url + "?redir=#{ERB::Util.url_encode(session[:last_url])}"
+    end
+  end
+
+
+  def current_session
+    @_current_session ||= AuthRocket::Session.from_token(session[:ar_token])
+  end
+
+  def current_user
+    current_session.try(:user)
+  end
+
+
+  def ar_login_url
+    @_login_url = loginrocket_url('login')
+  end
+
+  def ar_signup_url
+    @_signup_url = loginrocket_url('signup')
+  end
+
+  def loginrocket_url(path=nil)
+    raise "Missing env AUTHROCKET_LOGIN_URL or credentials[:loginrocket_url]" if AuthRocket::Api.credentials[:loginrocket_url].blank?
+    s = AuthRocket::Api.credentials[:loginrocket_url].dup
+    s.concat('/') unless s.ends_with?('/')
+    s.concat(path) if path
+    s.freeze
+  end
+
+end

data/lib/authrocket/rails/engine.rb

@@ -0,0 +1,13 @@
+module AuthRocket
+  class Engine < ::Rails::Engine
+
+    initializer "authrocket.helpers" do
+      require_relative 'controller_helper'
+
+      ActiveSupport.on_load(:action_controller) do
+        include AuthRocket::ControllerHelper
+      end
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authrocket
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - AuthRocket Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-23 00:00:00.000000000 Z
+date: 2018-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ncore
@@ -79,7 +79,10 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- app/controllers/auth_rocket/ar_controller.rb
+- app/controllers/logins_controller.rb
 - authrocket.gemspec
+- config/routes.rb
 - lib/authrocket.rb
 - lib/authrocket/api/api_config.rb
 - lib/authrocket/api/client.rb
@@ -95,6 +98,9 @@ files:
 - lib/authrocket/membership.rb
 - lib/authrocket/notification.rb
 - lib/authrocket/org.rb
+- lib/authrocket/rails.rb
+- lib/authrocket/rails/controller_helper.rb
+- lib/authrocket/rails/engine.rb
 - lib/authrocket/realm.rb
 - lib/authrocket/session.rb
 - lib/authrocket/user.rb