omniauth-doximity-oauth2 0.1.0 → 1.0.0

data/README.md

@@ -1,29 +1,143 @@
-# Omniauth::Doximity::Oauth2
+# Omniauth::DoximityOauth2
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/omniauth/doximity/oauth2`. To experiment with that code, run `bin/console` for an interactive prompt.
+OmniAuth strategy for Doximity.
 
-TODO: Delete this and the text above, and describe your gem
+Sign up for Doximity's API to get your OAuth credentials at: https://www.doximity.com/developers/api_signup
 
-## Installation
+For more details on what tools we have available, read our developer docs: https://www.doximity.com/developers/documentation
 
-Install the gem and add to the application's Gemfile by executing:
+## Installation
 
-    $ bundle add omniauth-doximity-oauth2
+Add to your `Gemfile`:
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+```ruby
+gem 'omniauth-doximity-oauth2'
+```
 
-    $ gem install omniauth-doximity-oauth2
+Then `bundle install`.
 
 ## Usage
 
-TODO: Write usage instructions here
+Here's an example for adding the middleware to a Rails app in `config/initializers/omniauth.rb`:
+
+```ruby
+DOXIMITY_OMNIAUTH_SETUP = lambda do |env|
+  env['omniauth.strategy'].options[:client_id] = ENV["DOXIMITY_CLIENT_ID"]
+  env['omniauth.strategy'].options[:client_secret] = ENV["DOXIMITY_CLIENT_SECRET"]
+  env['omniauth.strategy'].options[:scope] = "openid profile:read:basic profile:read:email"
+end
+
+Rails.application.config.middleware.use OmniAuth::Builder do
+  configure do |config|
+    config.path_prefix = '/auth'
+  end
+  provider :doximity_oauth2, setup: DOXIMITY_OMNIAUTH_SETUP
+end
+```
+
+Talk with the Doximity API team about what scopes you need for your application, and make sure to edit your OmniAuth initializer to request them.
+
+Update your `config/routes.rb` to support Doximity OmniAuth callbacks on your session controller:
+
+```ruby
+Rails.application.routes.draw do
+  get "/auth/:provider/callback" => "sessions#create"
+  post "/signout" => "sessions#destroy"
+  get "/auth/failure" => "sessions#failure"
+end
+```
+
+Then, create a sign-in button that posts to `/auth/doximity`. Use one of the Sign in with Doximity logos, available here: https://www.doximity.com/developers/documentation#logos-for-use-by-third-party-developers
+
+```ruby
+<%= link_to "Sign in with Doximity", "/auth/doximity", method: :post do %>
+  <%= image_tag "https://assets.doxcdn.com/image/upload/v1/apps/doximity/api/api-button-sign-in-with-doximity.png", alt: "Sign in with Doximity button"%>
+<% end %>
+```
+
+Note that in OmniAuth versions 2 and above, links to sign in should use the POST method. Read more [here](https://github.com/omniauth/omniauth/wiki/Resolving-CVE-2015-9284)
+
+In your callback controller, you will have a few resources available to you after the user approves your application and logs in.
+
+```ruby
+class SessionsController < ApplicationController
+  def create
+    session[:user_uuid] = request.env["omniauth.auth"]["uid"]
+    redirect_to request.env["omniauth.origin"] || "/", :notice => "Signed in!"
+  end
 
-## Development
+  def destroy
+    session.delete(:user_uuid)
+    redirect_to "/"
+  end
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+  def failure
+    redirect_to request.env["omniauth.origin"] || "/", :alert => "Authentication error: #{params[:message].humanize}"
+  end
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+You can also add an `origin` param to your `/auth/doximity` post, which will be provided in the `request.env["omniauth.origin"]` variable after the success or failure callback.
+
+## Configuration
+
+You can configure several options, inside the configuration lambda:
+
+* `[:scope]`: A comma-separated list of permissions you want to request from the user.Caveats:
+  * The `openid` scope is suggested. Alternatively, if the `openid` scope is not requested `omniauth-doximity` will make an additional request to retrieve information about the signed in user using your other scopes. Your app may be subject to rate limiting depending on your usage.
+  * Without any scopes, you will still be able to log in the user and retrieve a unique UUIDv4 to distinguish them from other users.
+
+* `[:name]`: The name of the strategy. The default name is `doximity` but it can be changed to any string. The `:provider` part of OmniAuth  URLs will also change to `/auth/{{ name }}`.
+
+* `[:client_options][:site]`: Override the Doximity OAuth provider website. You may be provided with a development site to use while setting up your integration, which you would set here.
+
+* `[:pkce]`: A boolean denoting whether to follow the PKCE OAuth spec. Default `true`. Note that if set to false, your OmniAuth credentials hash will not include a `refresh` token. Your OAuth application also may require PKCE to use OmniAuth.
+
+## Auth Hash
+
+Here's an example of an authentication hash available in the callback by accessing `request.env['omniauth.auth']`:
+
+```ruby
+{
+  "provider" => "doximity",
+  "uid" => "cc485bd2-b25a-4677-b05c-e98febf7789d",
+  "info" => {
+    "name" => "Test User",
+    "given_name" => "Test",
+    "family_name" => "User",
+    "primary_email" => "md@doximity.com",
+    "emails" => ["md@doximity.com"],
+    "profile_photo_url" => "http://res.cloudinary.com/doximity-development/image/upload/l_text:Helvetica_130_bold:AT,co_rgb:FFFFFF,t_profile_photo_320x320/profile-placeholder-registered-5.jpg",
+    "credentials" => "Other",
+    "specialty" => "Optometrist"
+  },
+  "credentials" => {
+    "token" => "gMej-ecC9Wzy4KkUCypYQ1J_8mQ1Yo9RXJYwU2kCyPKciuuOIxHflFlLP0PLlJmwnjPwlNa7nkQeeOcz-zyC6w==",
+    "refresh_token" => "go-40T6xPOzSOd09NTElQ0tGi-BU5hluljET8wa3syzxBqsG5BP0PJW_CsbDhmm49T081jhsIMnP-OQG8McYYPdOENc027K87gGSurOquANzx8qlo4hTJ903LNGpTZ6VcV1Ci0jomvJdH1NsCq5nLxeCy4dBctTZEMA-c3pOVZ0=",
+    "expires_at" => 1650335410,
+    "expires" => true,
+    "access_token" => "gMej-ecC9Wzy4KkUCypYQ1J_8mQ1Yo9RXJYwU2kCyPKciuuOIxHflFlLP0PLlJmwnjPwlNa7nkQeeOcz-zyC6w==",
+    "scope" => "profile:read:email profile:read:basic openid",
+    "token_type" => "bearer"
+  }, "extra" => {
+    "raw_subject_info" => {
+      "acr" => 2, "at_hash" => "uVfpy56HzI3J_dZR2kyxrQ", "aud" => ["https://auth.doximity.com", "6bd7e37e80fd06819ca13b268adea5fbe57446a9f9e1982f9483813d7272acf1"], "auth_time" => 1650333376, "azp" => "6bd7e37e80fd06819ca13b268adea5fbe57446a9f9e1982f9483813d7272acf1", "credentials" => "Other", "emails" => ["md@doximity.com"], "exp" => 1650335384, "family_name" => "User", "given_name" => "Test", "iat" => 1650333610, "iss" => "https://auth.doximity.com", "name" => "Test User", "primary_email" => "md@doximity.com", "profile_photo_url" => "http://res.cloudinary.com/doximity-development/image/upload/l_text:Helvetica_130_bold:AT,co_rgb:FFFFFF,t_profile_photo_320x320/profile-placeholder-registered-5.jpg", "sid" => "9", "specialty" => "Optometrist", "sub" => "cc485bd2-b25a-4677-b05c-e98febf7789d"
+    }, "raw_credential_info" => {
+      "token_type" => "bearer", "scope" => "profile:read:email profile:read:basic openid", "id_token" => "{{JWT omitted for brevity}}", "access_token" => "gMej-ecC9Wzy4KkUCypYQ1J_8mQ1Yo9RXJYwU2kCyPKciuuOIxHflFlLP0PLlJmwnjPwlNa7nkQeeOcz-zyC6w==", "refresh_token" => "go-40T6xPOzSOd09NTElQ0tGi-BU5hluljET8wa3syzxBqsG5BP0PJW_CsbDhmm49T081jhsIMnP-OQG8McYYPdOENc027K87gGSurOquANzx8qlo4hTJ903LNGpTZ6VcV1Ci0jomvJdH1NsCq5nLxeCy4dBctTZEMA-c3pOVZ0=", "expires_at" => 1650335410
+    }
+  }
+}
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/omniauth-doximity-oauth2.
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+6. Sign the CLA if you haven't yet. See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## License
+
+The gem is licensed under an Apache 2 license. Contributors are required to sign a contributor license agreement. See [LICENSE.txt](./LICENSE.txt) and [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.

data/Rakefile

@@ -1,4 +1,23 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-task default: %i[]
+require File.join("bundler", "gem_tasks")
+require File.join("rspec", "core", "rake_task")
+require "sdoc"
+
+FileList["tasks/*.rake"].each { |task| load task }
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.markup = "tomdoc"
+  rdoc.options << "--format=sdoc"
+  rdoc.options << "--github --encoding=UTF-8"
+  rdoc.rdoc_dir = "doc"
+  rdoc.rdoc_files.exclude("vendor", "tmp")
+  rdoc.rdoc_files.include("README.md", "lib", "*.rb")
+  rdoc.template = "rails"
+  rdoc.title = "omniauth-doximity Documentation"
+end

data/lib/omniauth/strategies/doximity_oauth2.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "omniauth/strategies/oauth2"
+require "omniauth-doximity-oauth2/errors"
+require "active_support/core_ext/hash/indifferent_access"
+require "uri"
+require "rack/utils"
+require "jwt"
+require "faraday"
+require "multi_json"
+
+module OmniAuth
+  module Strategies
+    # Doximity OmniAuth strategy.
+    class DoximityOauth2 < OmniAuth::Strategies::OAuth2
+      DEFAULT_SCOPE = "openid profile:read:basic"
+
+      option :name, "doximity"
+
+      option :pkce, true
+
+      option :authorize_options, [:scope]
+
+      option :client_options, {
+        site: "https://auth.doximity.com",
+        authorize_url: "/oauth/authorize",
+        token_url: "/oauth/token",
+        jwks_url: "/.well-known/jwks.json"
+      }
+
+      option :auth_token_params, {
+        mode: :header
+      }
+
+      uid { raw_subject_info["sub"] }
+
+      info do
+        prune({
+                name: raw_subject_info["name"],
+                given_name: raw_subject_info["given_name"],
+                middle_name: raw_subject_info["middle_name"],
+                family_name: raw_subject_info["family_name"],
+                primary_email: raw_subject_info["primary_email"],
+                emails: raw_subject_info["emails"],
+                profile_photo_url: raw_subject_info["profile_photo_url"],
+                credentials: raw_subject_info["credentials"],
+                specialty: raw_subject_info["specialty"],
+                permissions: raw_subject_info["permissions"]
+              })
+      end
+
+      extra do
+        prune({
+                raw_subject_info: raw_subject_info,
+                raw_credential_info: raw_credential_info
+              })
+      end
+
+      credentials do
+        prune({
+                access_token: raw_credential_info["access_token"],
+                refresh_token: raw_credential_info["refresh_token"],
+                expires_at: raw_credential_info["expires_at"],
+                scope: raw_credential_info["scope"],
+                token_type: raw_credential_info["token_type"]
+              })
+      end
+
+      def raw_subject_info
+        @raw_subject_info ||= parse_id_token(access_token["id_token"] || access_token.get("/oauth/userinfo").body) || {}
+      end
+
+      def raw_credential_info
+        @raw_credential_info ||= access_token.to_hash.with_indifferent_access
+      end
+
+      def authorize_params
+        super.tap do |params|
+          options[:authorize_options].each do |v|
+            params[v.to_sym] = request.params[v] if request.params[v]
+          end
+
+          params[:scope] = get_scope(params)
+        end
+      end
+
+      private
+
+      def get_scope(params)
+        raw_scope = params[:scope] || DEFAULT_SCOPE
+        scope_list = raw_scope.split(" ").map { |item| item.split(",") }.flatten
+        scope_list.join(" ")
+      end
+
+      def parse_id_token(token)
+        _, header = JWT.decode(token, nil, false)
+
+        keys = request_keys
+
+        public_key_params = keys.find { |key| key["kid"] == header["kid"] }
+        rsa_key = create_rsa_key(public_key_params["n"], public_key_params["e"])
+
+        body, = JWT.decode(token, rsa_key.public_key, true, { algorithm: header["alg"] })
+        body
+      rescue JWT::VerificationError => e
+        raise OmniAuth::DoximityOauth2::JWTVerificationError(e, token)
+      end
+
+      def callback_url
+        options[:callback_url] || full_host + script_name + callback_path
+      end
+
+      def prune(hash)
+        hash.delete_if do |_, val|
+          prune(val) if val.is_a?(Hash)
+          val.nil? || (val.respond_to?(:empty?) && val.empty?)
+        end
+      end
+
+      def request_keys
+        url = options[:client_options][:site] + options[:client_options][:jwks_url]
+        response = Faraday.get(url)
+
+        raise OmniAuth::DoximityOauth2::JWKSRequestError(url, response) if response.status != 200
+
+        MultiJson.load(response.body)["keys"]
+      end
+
+      def create_rsa_key(n, e)
+        key = OpenSSL::PKey::RSA.new
+        key.set_key(OpenSSL::BN.new(Base64.urlsafe_decode64(n), 2), OpenSSL::BN.new(Base64.urlsafe_decode64(e), 2), nil)
+      end
+    end
+  end
+end

data/lib/omniauth-doximity-oauth2/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Omniauth
+  module DoximityOauth2
+    # Error for failed request to get public keys, for JWK verification
+    class JWKSRequestError < StandardError
+      MESSAGE = "Failed to request public keys for user info verification"
+      attr_reader :url, :response
+
+      def initialize(url, response)
+        @url = url
+        @response = response
+        super(MESSAGE)
+      end
+    end
+
+    # Error for failed JWK verifications
+    class JWTVerificationError < StandardError
+      MESSAGE = "Failed to verify user info JWT"
+      attr_reader :token, :error
+
+      def initialize(error, token)
+        @token = token
+        super(error.message)
+      end
+    end
+  end
+end

data/lib/omniauth-doximity-oauth2/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Omniauth
+  module DoximityOauth2
+    VERSION = "1.0.0"
+  end
+end

data/lib/omniauth-doximity-oauth2.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "omniauth-doximity-oauth2/version"
+require "omniauth/strategies/doximity_oauth2"

data/omniauth-doximity-oauth2.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'English'
+require File.expand_path('lib/omniauth-doximity-oauth2/version', __dir__)
+
+Gem::Specification.new do |spec|
+  spec.name          = "omniauth-doximity-oauth2"
+  spec.version       = Omniauth::DoximityOauth2::VERSION
+  spec.authors       = ["William Harvey"]
+  spec.email         = ["wharvey@doximity.com"]
+  spec.description   = 'OmniAuth strategy for Doximity, supporting OIDC, and using PKCE'
+  spec.summary       = 'OmniAuth strategy for Doximity'
+  spec.homepage      = "https://github.com/doximity/omniauth-doximity-oauth2.git"
+  spec.license       = "Apache-2.0"
+
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "https://github.com/doximity/omniauth-doximity-oauth2/blob/master/CHANGELOG.md"
+
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activesupport"
+  spec.add_runtime_dependency "faraday"
+  spec.add_runtime_dependency "jwt"
+  spec.add_runtime_dependency "multi_json"
+  spec.add_runtime_dependency "omniauth-oauth2"
+  spec.add_runtime_dependency "openssl"
+
+  spec.add_development_dependency "bundler", "~> 2.3.12"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rubocop"
+  spec.add_development_dependency "rubocop-rails"
+  spec.add_development_dependency "sdoc"
+end

data/spec/omniauth/strategies/doximity_oauth2_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "json"
+require "omniauth-doximity-oauth2"
+require "stringio"
+
+describe OmniAuth::Strategies::DoximityOauth2 do
+  let(:request) { double("Request", params: {}, cookies: {}, env: {}) }
+  let(:app) do
+    lambda do
+      [200, {}, ["Hello."]]
+    end
+  end
+
+  subject do
+    OmniAuth::Strategies::DoximityOauth2.new(app, "appid", "secret", @options || {}).tap do |strategy|
+      allow(strategy).to receive(:request) do
+        request
+      end
+    end
+  end
+
+  before do
+    OmniAuth.config.test_mode = true
+  end
+
+  after do
+    OmniAuth.config.test_mode = false
+  end
+
+  describe "#client_options" do
+    it "has correct site" do
+      expect(subject.client.site).to eq("https://auth.doximity.com")
+    end
+
+    it "has correct authorize_url" do
+      expect(subject.client.options[:authorize_url]).to eq("/oauth/authorize")
+    end
+
+    it "has correct token_url" do
+      expect(subject.client.options[:token_url]).to eq("/oauth/token")
+    end
+
+    it "has correct jwks_url" do
+      expect(subject.client.options[:jwks_url]).to eq("/.well-known/jwks.json")
+    end
+
+    describe "overrides" do
+      context "as strings" do
+        it "should allow overriding the site" do
+          @options = { client_options: { "site" => "https://example.com" } }
+          expect(subject.client.site).to eq("https://example.com")
+        end
+
+        it "should allow overriding the authorize_url" do
+          @options = { client_options: { "authorize_url" => "/example" } }
+          expect(subject.client.options[:authorize_url]).to eq("/example")
+        end
+
+        it "should allow overriding the token_url" do
+          @options = { client_options: { "token_url" => "/example" } }
+          expect(subject.client.options[:token_url]).to eq("/example")
+        end
+
+        it "should allow overriding the jwks_url" do
+          @options = { client_options: { "jwks_url" => "/example" } }
+          expect(subject.client.options[:jwks_url]).to eq("/example")
+        end
+      end
+
+      context "as symbols" do
+        it "should allow overriding the site" do
+          @options = { client_options: { site: "https://example.com" } }
+          expect(subject.client.site).to eq("https://example.com")
+        end
+
+        it "should allow overriding the authorize_url" do
+          @options = { client_options: { authorize_url: "/example" } }
+          expect(subject.client.options[:authorize_url]).to eq("/example")
+        end
+
+        it "should allow overriding the token_url" do
+          @options = { client_options: { token_url: "/example" } }
+          expect(subject.client.options[:token_url]).to eq("/example")
+        end
+
+        it "should allow overriding the jwks_url" do
+          @options = { client_options: { jwks_url: "/example" } }
+          expect(subject.client.options[:jwks_url]).to eq("/example")
+        end
+      end
+    end
+  end
+
+  describe "#authorize_options" do
+    %i[scope].each do |k|
+      it "should support #{k}" do
+        @options = { k => "http://someval" }
+        expect(subject.authorize_params[k.to_s]).to eq("http://someval")
+      end
+    end
+
+    describe "scope" do
+      it "should leave base scopes as is" do
+        @options = { scope: "profile:read:basic" }
+        expect(subject.authorize_params["scope"]).to eq("profile:read:basic")
+      end
+
+      it "should join scopes" do
+        @options = { scope: "profile:read:basic,profile:read:email" }
+        expect(subject.authorize_params["scope"]).to eq("profile:read:basic profile:read:email")
+      end
+
+      it "should deal with whitespace when joining scopes" do
+        @options = { scope: "profile:read:basic, profile:read:email" }
+        expect(subject.authorize_params["scope"]).to eq("profile:read:basic profile:read:email")
+      end
+
+      it "should set default scope to openid profile:read:basic" do
+        expect(subject.authorize_params["scope"]).to eq("openid profile:read:basic")
+      end
+
+      it "should support space delimited scopes" do
+        @options = { scope: "profile:read:basic profile:read:email" }
+        expect(subject.authorize_params["scope"]).to eq("profile:read:basic profile:read:email")
+      end
+    end
+  end
+end

data/spec/rubocop_spec.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper"
+
+describe "Rubocop" do
+  it "should pass with no offenses detected" do
+    expect(`rubocop`).to include("no offenses detected")
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require File.join("bundler", "setup")
+require "rspec"

data/tasks/ci.rake

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+namespace :ci do
+  desc "Run tests"
+  task :specs do
+    sh "bundle exec rspec --color spec --format progress"
+  end
+
+  desc "Run rubocop"
+  task :rubocop do
+    sh "bundle exec rubocop --display-cop-names --extra-details --display-style-guide"
+  end
+
+  desc "Build documentation"
+  task doc: :rdoc
+end