inst_access 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e81a1fd534b4927401037a4865828b0f402ee0b81a18c5d44e4ddeaf67205a8
+  data.tar.gz: d2a3cd8174208a3b943d20f9b57c0126585f7dd6bb1516821f2fa959771b6063
+SHA512:
+  metadata.gz: 6ec033d6636a968926163b1ba44e4168efa78520a108c3ba0809e309d2564fedba1de0c41740a7d545cf424a3bd91225e929588ecf1e62fa31f527091eb01935
+  data.tar.gz: cf5b9d6012d3fec913dffa5195b088baa5c42140c1e78bfb8cdaffb55d623f1d44cfb5d9d91fa066d961e42b8661cddb5ce5a38af92d2e87eb51812537be6ee2

data/lib/inst_access/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'openssl'
+
+module InstAccess
+  class Config
+    attr_reader :signing_key
+
+    def initialize(raw_signing_key, raw_encryption_key = nil)
+      @signing_key = OpenSSL::PKey::RSA.new(raw_signing_key)
+      if raw_encryption_key
+        @encryption_key = OpenSSL::PKey::RSA.new(raw_encryption_key)
+        raise ArgumentError, 'the encryption key should be a public RSA key' if @encryption_key.private?
+      end
+    rescue OpenSSL::PKey::RSAError => e
+      raise ArgumentError, e
+    end
+
+    def encryption_key
+      @encryption_key || raise(ConfigError, 'Encryption key is not configured')
+    end
+  end
+end

data/lib/inst_access/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+module InstAccess
+  class Error < StandardError; end
+
+  class ConfigError < Error; end
+
+  class InvalidToken < Error; end
+
+  class TokenExpired < Error; end
+end

data/lib/inst_access/token.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+module InstAccess
+  class Token
+    ISSUER = 'instructure:inst_access'
+    ENCRYPTION_ALGO = :'RSA-OAEP'
+    ENCRYPTION_METHOD = :'A128CBC-HS256'
+
+    attr_reader :jwt_payload
+
+    def initialize(jwt_payload)
+      @jwt_payload = jwt_payload.symbolize_keys
+    end
+
+    def user_uuid
+      jwt_payload[:sub]
+    end
+
+    def account_uuid
+      jwt_payload[:acct]
+    end
+
+    def canvas_domain
+      jwt_payload[:canvas_domain]
+    end
+
+    def masquerading_user_uuid
+      jwt_payload[:masq_sub]
+    end
+
+    def masquerading_user_shard_id
+      jwt_payload[:masq_shard]
+    end
+
+    def to_token_string
+      jwe = to_jws.encrypt(InstAccess.config.encryption_key, ENCRYPTION_ALGO, ENCRYPTION_METHOD)
+      jwe.to_s
+    end
+
+    # only for testing purposes, or to do local dev w/o running a decrypting
+    # service.  unencrypted tokens should not be released into the wild!
+    def to_unencrypted_token_string
+      to_jws.to_s
+    end
+
+    private
+
+    def to_jws
+      key = InstAccess.config.signing_key
+      raise ConfigError, 'Private signing key needed to produce tokens' unless key.private?
+
+      jwt = JSON::JWT.new(jwt_payload)
+      jwt.sign(key)
+    end
+
+    class << self
+      private :new
+
+      # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity
+      def for_user(
+        user_uuid: nil,
+        account_uuid: nil,
+        canvas_domain: nil,
+        real_user_uuid: nil,
+        real_user_shard_id: nil,
+        user_global_id: nil,
+        real_user_global_id: nil
+      )
+        raise ArgumentError, 'Must provide user uuid and account uuid' if user_uuid.blank? || account_uuid.blank?
+
+        now = Time.now.to_i
+        payload = {
+          iss: ISSUER,
+          iat: now,
+          exp: now + 1.hour.to_i,
+          sub: user_uuid,
+          acct: account_uuid
+        }
+        payload[:canvas_domain] = canvas_domain if canvas_domain
+        payload[:masq_sub] = real_user_uuid if real_user_uuid
+        payload[:masq_shard] = real_user_shard_id if real_user_shard_id
+        payload[:debug_user_global_id] = user_global_id.to_s if user_global_id
+        payload[:debug_masq_global_id] = real_user_global_id.to_s if real_user_global_id
+
+        new(payload)
+      end
+      # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity
+
+      # Takes an unencrypted (but signed) token string
+      def from_token_string(jws)
+        sig_key = InstAccess.config.signing_key
+        jwt = begin
+          JSON::JWT.decode(jws, sig_key)
+        rescue StandardError => e
+          raise InvalidToken, e
+        end
+        raise TokenExpired if jwt[:exp] < Time.now.to_i
+
+        new(jwt.to_hash)
+      end
+
+      def token?(string)
+        jwt = JSON::JWT.decode(string, :skip_verification)
+        jwt[:iss] == ISSUER
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/inst_access.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'active_support'
+require 'json/jwt'
+require 'inst_access/errors'
+require 'inst_access/config'
+require 'inst_access/token'
+
+module InstAccess
+  class << self
+    # signing_key is required.  if you are going to be producing (and therefore
+    # signing) tokens, this needs to be an RSA private key.  if you're just
+    # consuming tokens, it can be the RSA public key corresponding to the
+    # private key that signed them.
+    # encryption_key is only required if you are going to be producing tokens.
+    def configure(signing_key:, encryption_key: nil)
+      @config = Config.new(signing_key, encryption_key)
+    end
+
+    # set a configuration only for the duration of the given block, then revert
+    # it.  useful for testing.
+    def with_config(signing_key:, encryption_key: nil)
+      old_config = @config
+      configure(signing_key: signing_key, encryption_key: encryption_key)
+      yield
+    ensure
+      @config = old_config
+    end
+
+    def config
+      @config || raise(ConfigError, 'InstAccess is not configured!')
+    end
+  end
+end

data/spec/initialize_coverage.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+begin
+  require 'simplecov'
+  require 'simplecov-json'
+
+  SimpleCov.formatters = [
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::JSONFormatter
+  ]
+
+  SimpleCov.start do
+    enable_coverage :branch
+
+    add_filter '/spec/'
+  end
+
+  unless ENV.key?('TEST_ENV_NUMBER') || ENV['DISABLE_MINIMUM_COVERAGE']
+    # SimpleCov supports merging coverage results from parallel test runs,
+    # but it doesn't support a global minimum coverage check when running in
+    # parallel, so builds fail because subsets of the tests return < min%.
+    SimpleCov.minimum_coverage(98)
+    SimpleCov.maximum_coverage_drop(3)
+    SimpleCov.minimum_coverage_by_file(78)
+  end
+rescue LoadError => e
+  puts "Error: #{e}"
+end

data/spec/inst_access/inst_access_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'spec_helper'
+
+describe InstAccess do
+  let(:signing_keypair) { OpenSSL::PKey::RSA.new(2048) }
+  let(:encryption_keypair) { OpenSSL::PKey::RSA.new(2048) }
+  let(:signing_priv_key) { signing_keypair.to_s }
+  let(:signing_pub_key) { signing_keypair.public_key.to_s }
+  let(:encryption_priv_key) { encryption_keypair.to_s }
+  let(:encryption_pub_key) { encryption_keypair.public_key.to_s }
+
+  describe '.configure' do
+    it 'blows up if you try to pass a private key for encryption' do
+      expect do
+        described_class.configure(
+          signing_key: signing_priv_key,
+          encryption_key: encryption_priv_key
+        )
+      end.to raise_error(ArgumentError)
+    end
+
+    it "blows up if you pass it something that isn't an RSA key" do
+      expect do
+        described_class.configure(signing_key: 'asdf123')
+      end.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/inst_access/token_spec.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'spec_helper'
+require 'timecop'
+
+describe InstAccess::Token do
+  let(:signing_keypair) { OpenSSL::PKey::RSA.new(2048) }
+  let(:encryption_keypair) { OpenSSL::PKey::RSA.new(2048) }
+  let(:signing_priv_key) { signing_keypair.to_s }
+  let(:signing_pub_key) { signing_keypair.public_key.to_s }
+  let(:encryption_priv_key) { encryption_keypair.to_s }
+  let(:encryption_pub_key) { encryption_keypair.public_key.to_s }
+
+  let(:a_token) { described_class.for_user(user_uuid: 'user-uuid', account_uuid: 'acct-uuid') }
+  let(:unencrypted_token) do
+    InstAccess.with_config(signing_key: signing_priv_key) do
+      a_token.to_unencrypted_token_string
+    end
+  end
+
+  describe '.token?' do
+    it 'returns false for non-JWTs' do
+      expect(described_class.token?('asdf1234stuff')).to eq(false)
+    end
+
+    it 'returns false for JWTs from a different issuer' do
+      jwt = JSON::JWT.new(iss: 'bridge').to_s
+      expect(described_class.token?(jwt)).to eq(false)
+    end
+
+    it 'returns true for an InstAccess token' do
+      expect(described_class.token?(unencrypted_token)).to eq(true)
+    end
+
+    it 'returns true for an expired InstAccess token' do
+      token = unencrypted_token # instantiate it to set the expiration
+      Timecop.travel(3601) do
+        expect(described_class.token?(token)).to eq(true)
+      end
+    end
+  end
+
+  describe '.for_user' do
+    it 'blows up without a user uuid' do
+      expect do
+        described_class.for_user(user_uuid: '', account_uuid: 'acct-uuid')
+      end.to raise_error(ArgumentError)
+    end
+
+    it 'blows up without an account uuid' do
+      expect do
+        described_class.for_user(user_uuid: 'user-uuid', account_uuid: '')
+      end.to raise_error(ArgumentError)
+    end
+
+    it 'creates an instance for the given uuids' do
+      id = described_class.for_user(user_uuid: 'user-uuid', account_uuid: 'acct-uuid')
+      expect(id.user_uuid).to eq('user-uuid')
+      expect(id.masquerading_user_uuid).to be_nil
+    end
+
+    it 'accepts other details' do
+      id = described_class.for_user(
+        user_uuid: 'user-uuid',
+        account_uuid: 'acct-uuid',
+        canvas_domain: 'z.instructure.com',
+        real_user_uuid: 'masq-id',
+        real_user_shard_id: 5
+      )
+      expect(id.canvas_domain).to eq('z.instructure.com')
+      expect(id.masquerading_user_uuid).to eq('masq-id')
+      expect(id.masquerading_user_shard_id).to eq(5)
+    end
+  end
+
+  context 'without being configured' do
+    it '#to_token_string blows up' do
+      id = described_class.for_user(user_uuid: 'user-uuid', account_uuid: 'acct-uuid')
+      expect do
+        id.to_token_string
+      end.to raise_error(InstAccess::ConfigError)
+    end
+
+    it '.from_token_string blows up' do
+      expect do
+        described_class.from_token_string(unencrypted_token)
+      end.to raise_error(InstAccess::ConfigError)
+    end
+  end
+
+  context 'when configured only for signature verification' do
+    around do |example|
+      InstAccess.with_config(signing_key: signing_pub_key) do
+        example.run
+      end
+    end
+
+    it '#to_token_string blows up' do
+      id = described_class.for_user(user_uuid: 'user-uuid', account_uuid: 'acct-uuid')
+      expect do
+        id.to_token_string
+      end.to raise_error(InstAccess::ConfigError)
+    end
+
+    it '.from_token_string decodes the given token' do
+      id = described_class.from_token_string(unencrypted_token)
+      expect(id.user_uuid).to eq('user-uuid')
+    end
+
+    it '.from_token_string blows up if the token is expired' do
+      token = unencrypted_token # instantiate it to set the expiration
+      Timecop.travel(3601) do
+        expect do
+          described_class.from_token_string(token)
+        end.to raise_error(InstAccess::TokenExpired)
+      end
+    end
+
+    it '.from_token_string blows up if the token has a bad signature' do
+      # reconfigure with the wrong signing key so the signature doesn't match
+      InstAccess.with_config(signing_key: encryption_pub_key) do
+        expect do
+          described_class.from_token_string(unencrypted_token)
+        end.to raise_error(InstAccess::InvalidToken)
+      end
+    end
+  end
+
+  context 'when configured for token generation' do
+    around do |example|
+      InstAccess.with_config(
+        signing_key: signing_priv_key, encryption_key: encryption_pub_key
+      ) do
+        example.run
+      end
+    end
+
+    it '#to_token_string signs and encrypts the payload, returning a JWE' do
+      id_token = a_token.to_token_string
+      # JWEs have 5 base64-encoded sections, each separated by a dot
+      expect(id_token).to match(/[\w-]+\.[\w-]+\.[\w-]+\.[\w-]+\.[\w-]+/)
+      # normally another service would need to decrypt this, but we'll do it
+      # here ourselves to ensure it's been encrypted properly
+      jws = JSON::JWT.decode(id_token, encryption_keypair)
+      jwt = JSON::JWT.decode(jws.plain_text, signing_keypair)
+      expect(jwt[:sub]).to eq('user-uuid')
+    end
+
+    it '.from_token_string still decodes the given token' do
+      id = described_class.from_token_string(unencrypted_token)
+      expect(id.user_uuid).to eq('user-uuid')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#
+# Copyright (C) 2021 - present Instructure, Inc.
+#
+# This file is part of Canvas.
+#
+# Canvas is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, version 3 of the License.
+#
+# Canvas is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+
+require 'initialize_coverage'
+require 'byebug'
+require 'inst_access'
+
+RSpec.configure do |config|
+  config.order = 'random'
+end

data/test.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -e
+docker-compose run --rm inst_access bundle insall
+docker-compose run --rm inst_access bundle exec rspec

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification
+name: inst_access
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Ziwisky
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-11-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: json-jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.13.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: byebug
+  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: rspec
+  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: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.8.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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: simplecov-json
+  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: timecop
+  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:
+- mziwisky@instructure.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/inst_access.rb
+- lib/inst_access/config.rb
+- lib/inst_access/errors.rb
+- lib/inst_access/token.rb
+- spec/initialize_coverage.rb
+- spec/inst_access/inst_access_spec.rb
+- spec/inst_access/token_spec.rb
+- spec/spec_helper.rb
+- test.sh
+homepage: http://github.com/instructure/inst_access
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+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: Generation, parsing, and validation of Instructure access tokens
+test_files:
+- spec/initialize_coverage.rb
+- spec/inst_access/inst_access_spec.rb
+- spec/inst_access/token_spec.rb
+- spec/spec_helper.rb