slack_sign_in 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab3441efeb6969dabc184dd1410341c307a0160f22bab3b72162a59c80adfd83
+  data.tar.gz: 07fe6499c9c387dacdba2723b3270a7f59ab37d078831a788b561701c0a49e8d
+SHA512:
+  metadata.gz: 66b5d9e3dc895c00ebe4da4e06b72edbd87fe12ca8232230bef3ebd9b6f0b710d2407c9b20aa2bb32e64dc6c6128389156f8ad2bde6fb38948ce22ed0f47b0c1
+  data.tar.gz: 6edbf7498bda10084266dd77c456a35c8f3c52274976420181905f3cd6e25d5e61684c3857ee9335663a001b9f8b6dc78ec0539dfb300e71672c2047a9264662

data/README.md

@@ -0,0 +1,251 @@
+# Slack Sign-In for Rails
+
+The goal of this gem is to get you up and running with Slack sign-ins:
+
+  - with minimal configuration
+  - as quickly as possible
+  - without sacrificing on long-term stability and maintainability
+
+The creation of this gem was heavily inspired by the awesome
+[basecamp/google_sign_in](https://github.com/basecamp/google_sign_in) project,
+both in its aspirations and in its implementation. If you need to add Google
+sign-in to your Rails project, definitely check it out!
+
+This project adheres to the Contributor Covenant
+[code of conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to
+uphold this code. Please report unacceptable behavior to
+research@teecom.com.
+
+## Installation
+
+Add `slack_sign_in` to your Rails app's Gemfile and run `bundle install`:
+
+```ruby
+gem "slack_sign_in"
+```
+
+*Note:* This gem requires Rails 5.2 or newer.
+
+## Creating a Slack App
+
+Before getting started, you'll likely need to set up a Slack application:
+
+  1. Go to the [Slack applications list](https://api.slack.com/apps)
+
+  2. Either click **Create New App**, or select an existing application
+
+  3. Take note of your app's **Client ID** and **Client Secret**
+
+     <details>
+       <summary>Slack app credentials visual guide :framed_picture:</summary>
+
+       ![Slack App Credentials](./doc/images/app_credentials.png)
+     </details>
+
+  4. Under the **OAuth & Permissions** tab, add your app's callback URLs to the
+     list of **Redirect URLs** section.
+
+     This gem adds a single OAuth callback to your Rails application at
+     `/slack_sign_in/callback`. For a production application, you might add a
+     redirect URL of:
+
+     ```
+     https://www.example.com/slack_sign_in/callback
+     ```
+
+     To sign in with Slack in development, you would likely also add a redirect
+     URL for your local environment. Something like:
+
+     ```
+     http://localhost:3000/slack_sign_in/callback
+     ```
+
+     <details>
+       <summary>Slack app redirect URLs visual guide :framed_picture:</summary>
+
+       ![Slack App Redirect URLs](./doc/images/redirect_urls.png)
+     </details>
+
+## Configuration
+
+With your Slack application set up, the next step is to configure your Rails
+app to use it. Run `rails credentials:edit` to edit your app's
+[encrypted credentials](https://guides.rubyonrails.org/security.html#custom-credentials)
+and add the following:
+
+```yaml
+slack_sign_in:
+  client_id: "[Your client ID here]"
+  client_secret: "[Your client secret here]"
+```
+
+You're all set to use Slack sign-in now. The gem will automatically use these
+client credentials! :tada:
+
+Alternatively, you can provide the Slack credentials through an initializer
+and environment variables:
+
+```ruby
+# config/initializers/slack_sign_in.rb
+Rails.application.configure do
+  config.slack_sign_in.client_id = ENV.fetch("SLACK_CLIENT_ID")
+  config.slack_sign_in.client_secret = ENV.fetch("SLACK_CLIENT_SECRET")
+end
+```
+
+**:warning: Important:** Take care to protect your client secret. It's a secret
+after all!
+
+### Scopes
+
+By default, this gem will request the following scopes from Slack:
+
+  - `identity.basic`
+  - `identity.email`
+  - `identity.avatar`
+
+If these scopes don't suit your particular need, you can configure the gem to
+use any of the
+[supported Slack scopes](https://api.slack.com/docs/sign-in-with-slack#identity_scopes)
+through an initializer:
+
+```ruby
+# config/initializers/slack_sign_in.rb
+Rails.application.configure do
+  config.slack_sign_in.scopes = %w(identity.basic identity.team)
+end
+```
+
+### Mounting Root
+
+By default, this gem will mount its routes at `/slack_sign_in`. If this doesn't
+suit your needs, it can be configured through an initializer:
+
+```ruby
+# config/initializers/slack_sign_in.rb
+Rails.application.configure do
+  config.slack_sign_in.root = "sso/slack"
+end
+```
+
+In this example, the gem would add a callback URL of `/sso/slack/callback`
+rather than the default of `/slack_sign_in/callback`.
+
+## Usage
+
+This gem provides a `slack_sign_in_link` helper that generates a link that will
+kick off the sign-in process:
+
+```erb
+<%= slack_sign_in_link proceed_to: create_session_url %>
+
+<%= slack_sign_in_link "Sign In!", proceed_to: create_session_url %>
+
+<%= slack_sign_in_link proceed_to: create_session_url do %>
+  <div style="background: blue; padding: 10px; display: inline-block;">
+    <%= slack_sign_in_image %>
+  </div>
+<% end %>
+```
+
+<details>
+  <summary>Sign in link visuals :framed_picture:</summary>
+
+  ![Sign in links](./doc/images/sign_in_links.png)
+</details>
+
+Regardless of whether you use the default link, a text link, or a block link,
+the `proceed_to` argument is always required. After authenticating with Slack,
+we'll redirect to this URL with information on the authorization's success or
+failure for your application to handle.
+
+In most cases, that might look something like this:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # ...
+  get "sessions/create", to: "sessions#create", as: :create_session
+end
+```
+
+```ruby
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  include SlackSignIn::Authorization
+
+  def create
+    if slack_authorization.successful?
+      render plain: slack_authorization.identity.name
+    else
+      render plain: slack_authorization.error
+    end
+  end
+end
+```
+
+#### The `SlackSignIn::Authorization` Concern
+
+The `SlackSignIn::Authorization` concern is the primary interface for accessing
+information about the Slack sign-in process. It exposes a single method,
+`slack_authorization`, which will give you a
+[`SlackSignIn::Result`](#slacksigninresult) for the recently completed Slack
+sign-in flow.
+
+In the majority of cases, you should be able to use the
+`SlackSignIn::Authorization` concern along with the `slack_authorization`
+method to accomplish what you want. In some cases, you may need direct access to
+the full Slack response, though.
+
+Before redirecting to the specified `proceed_to` URL, this gem will either set
+`flash[:slack_sign_in]["success"]` to the Slack response, or 
+`flash[:slack_sign_in]["error"]` to an
+[OAuth authorizaton code grant error](https://tools.ietf.org/html/rfc6749#section-4.1.2.1).
+If you need direct access to the Slack response information, this is how you can
+get it.
+
+#### `SlackSignIn::Result`
+
+The `SlackSignIn::Result` class provides an interface for handling the result of
+a Slack sign-in attempt. It exposes three instance methods:
+
+  1. `successful?` - to determine whether the sign-in attempt succeeded or not
+
+  2. `identity` - either `nil` or a [`SlackSignIn::Identity`](#slacksigninidentity)
+     instance with user identity information from Slack
+
+  3. `error` - either `nil` or an
+     [OAuth authorizaton code grant error](https://tools.ietf.org/html/rfc6749#section-4.1.2.1)
+
+#### `SlackSignIn::Identity`
+
+The `SlackSignIn::Identity` class decodes user identity information from Slack.
+It exposes this information through a handful of instance methods:
+
+  - `unique_id` - a unique identifier from Slack that can be used to look up
+    people
+
+  - `team_id` - the ID of the team used while signing in
+
+  - `user_id` - the ID of the user who signed in
+
+  - `name` - the name of the user who signed in
+
+  - `email` - the email of the user who signed in
+
+  - `avatar(size: 48)` - the avatar of the user who signed in
+    (in a specific size). Typically the sizes provided by slack are
+    `24x24`, `32x32`, `48x48`, `72x72`, `192x192`, and `512x512`.
+
+## Contributing
+
+For information on how to contribute to this project, check out the
+[contributing guidelines](./CONTRIBUTING.md).
+
+## Questions?
+
+If you have any questions about, or if any of the documentation is unclear,
+please feel free to reach out through a
+[new issue](https://github.com/TEECOM/slack_sign_in/issues/new?labels=documentation%20:writing_hand:).
+
+:smiley_cat:

data/Rakefile

@@ -0,0 +1,18 @@
+begin
+  require "bundler/setup"
+  require "bundler/gem_tasks"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/concerns/slack_sign_in/authorization.rb

@@ -0,0 +1,9 @@
+module SlackSignIn::Authorization
+  extend ActiveSupport::Concern
+
+  private
+
+  def slack_authorization
+    @_result ||= SlackSignIn::Result.new(flash[:slack_sign_in])
+  end
+end

data/app/controllers/slack_sign_in/application_controller.rb

@@ -0,0 +1,17 @@
+module SlackSignIn
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    private
+
+    def client
+      @_client ||= OAuth2::Client.new(
+        SlackSignIn.client_id,
+        SlackSignIn.client_secret,
+        authorize_url: SlackSignIn::AUTHORIZE_URL,
+        token_url: SlackSignIn::TOKEN_URL,
+        redirect_uri: callback_url,
+      )
+    end
+  end
+end

data/app/controllers/slack_sign_in/authorizations_controller.rb

@@ -0,0 +1,23 @@
+class SlackSignIn::AuthorizationsController < SlackSignIn::ApplicationController
+  def create
+    redirect_to slack_login_url, flash: {proceed_to: proceed_to, state: state}
+  end
+
+  private
+
+  def slack_login_url
+    client.auth_code.authorize_url(scope: scopes, state: state)
+  end
+
+  def scopes
+    SlackSignIn.scopes.join(" ")
+  end
+
+  def proceed_to
+    params.require(:proceed_to)
+  end
+
+  def state
+    @_state ||= SecureRandom.base64(24)
+  end
+end

data/app/controllers/slack_sign_in/callbacks_controller.rb

@@ -0,0 +1,39 @@
+class SlackSignIn::CallbacksController < SlackSignIn::ApplicationController
+  def show
+    return head(:bad_request) if proceed_to_missing?
+
+    redirect_to proceed_to_url, flash: {slack_sign_in: slack_sign_in_result}
+  end
+
+  private
+
+  def proceed_to_missing?
+    proceed_to_url.blank?
+  end
+
+  def proceed_to_url
+    flash[:proceed_to]
+  end
+
+  def slack_sign_in_result
+    if valid_request? && params[:code].present?
+      {success: identity_information}
+    else
+      {error: error_for(params[:error])}
+    end
+  rescue OAuth2::Error => error
+    {error: error_for(error.code)}
+  end
+
+  def valid_request?
+    flash[:state].present? && params[:state] == flash[:state]
+  end
+
+  def identity_information
+    client.auth_code.get_token(params[:code]).params
+  end
+
+  def error_for(error)
+    error || "invalid_request"
+  end
+end

data/app/helpers/slack_sign_in/link_helper.rb

@@ -0,0 +1,27 @@
+module SlackSignIn::LinkHelper
+  def slack_sign_in_link(text = nil, proceed_to:, **options, &block)
+    options = options.merge(method: :post)
+    auth_url = slack_sign_in.authorization_path(proceed_to: proceed_to)
+
+    if text
+      link_to(text, auth_url, options)
+    elsif block_given?
+      link_to(auth_url, options, &block)
+    else
+      link_to(auth_url, options) { slack_sign_in_image }
+    end
+  end
+
+  def slack_sign_in_image
+    image_tag(
+      "https://platform.slack-edge.com/img/sign_in_with_slack.png",
+      alt: "Sign in with Slack",
+      height: 40,
+      width: 172,
+      srcset: {
+        "https://platform.slack-edge.com/img/sign_in_with_slack.png" => "1x",
+        "https://platform.slack-edge.com/img/sign_in_with_slack@2x.png" => "2x",
+      },
+    )
+  end
+end

data/app/models/slack_sign_in/identity.rb

@@ -0,0 +1,33 @@
+class SlackSignIn::Identity
+  def initialize(params)
+    @params = params
+  end
+
+  def unique_id
+    "#{team_id}-#{user_id}"
+  end
+
+  def team_id
+    params["team_id"]
+  end
+
+  def user_id
+    params["user_id"]
+  end
+
+  def name
+    params.dig("user", "name")
+  end
+
+  def email
+    params.dig("user", "email")
+  end
+
+  def avatar(size: 48)
+    params.dig("user", "image_#{size}")
+  end
+
+  private
+
+  attr_reader :params
+end

data/app/models/slack_sign_in/result.rb

@@ -0,0 +1,23 @@
+class SlackSignIn::Result
+  def initialize(result)
+    @result = result || {"error" => "invalid_request"}
+  end
+
+  def successful?
+    result.key? "success"
+  end
+
+  def identity
+    return unless successful?
+
+    SlackSignIn::Identity.new(result["success"])
+  end
+
+  def error
+    result["error"]
+  end
+
+  private
+
+  attr_reader :result
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+SlackSignIn::Engine.routes.draw do
+  resource :authorization, only: :create
+  resource :callback, only: :show
+end

data/lib/slack_sign_in.rb

@@ -0,0 +1,11 @@
+require "slack_sign_in/engine"
+
+module SlackSignIn
+  DEFAULT_SCOPES = %w[identity.basic identity.email identity.avatar]
+
+  AUTHORIZE_URL = "https://slack.com/oauth/authorize"
+  TOKEN_URL = "https://slack.com/api/oauth.access"
+
+  mattr_accessor :client_id, :client_secret
+  mattr_accessor :scopes
+end

data/lib/slack_sign_in/engine.rb

@@ -0,0 +1,33 @@
+require "oauth2"
+
+module SlackSignIn
+  class Engine < ::Rails::Engine
+    isolate_namespace SlackSignIn
+
+    config.slack_sign_in = ActiveSupport::OrderedOptions.new
+
+    initializer "slack_sign_in.config" do |app|
+      config.after_initialize do
+        SlackSignIn.client_id = config.slack_sign_in.client_id || app.credentials.dig(:slack_sign_in, :client_id)
+        SlackSignIn.client_secret = config.slack_sign_in.client_secret || app.credentials.dig(:slack_sign_in, :client_secret)
+        SlackSignIn.scopes = config.slack_sign_in.scopes || SlackSignIn::DEFAULT_SCOPES
+      end
+    end
+
+    initializer "slack_sign_in.helpers" do
+      ActiveSupport.on_load :action_controller_base do
+        helper SlackSignIn::Engine.helpers
+      end
+    end
+
+    initializer "slack_sign_in.mount" do |app|
+      app.routes.prepend do
+        mount SlackSignIn::Engine, at: app.config.slack_sign_in.root || "slack_sign_in"
+      end
+    end
+
+    initializer "slack_sign_in.parameter_filters" do |app|
+      app.config.filter_parameters << :code
+    end
+  end
+end

data/lib/slack_sign_in/version.rb

@@ -0,0 +1,3 @@
+module SlackSignIn
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: slack_sign_in
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Schaefer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standardrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- tommy.schaefer@teecom.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/controllers/concerns/slack_sign_in/authorization.rb
+- app/controllers/slack_sign_in/application_controller.rb
+- app/controllers/slack_sign_in/authorizations_controller.rb
+- app/controllers/slack_sign_in/callbacks_controller.rb
+- app/helpers/slack_sign_in/link_helper.rb
+- app/models/slack_sign_in/identity.rb
+- app/models/slack_sign_in/result.rb
+- config/routes.rb
+- lib/slack_sign_in.rb
+- lib/slack_sign_in/engine.rb
+- lib/slack_sign_in/version.rb
+homepage: https://github.com/teecom/slack_sign_in
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Sign in (or up) with Slack for Rails applications
+test_files: []