workos 1.5.1 → 2.1.0

data/lib/workos/webhooks.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'openssl'
+
+module WorkOS
+  # The Webhooks module provides convenience methods for working with the WorkOS webhooks.
+  # You'll need to extract the signature header and payload from the webhook request
+  # sig_header = request.headers['WorkOS-Signature']
+  # payload = request.body.read
+  #
+  # The secret is the Webhook Secret from your WorkOS Dashboard
+  # The tolerance is for the timestamp validation
+  #
+  module Webhooks
+    class << self
+      extend T::Sig
+
+      DEFAULT_TOLERANCE = 180
+
+      # Initializes an Event object from a JSON payload
+      # rubocop:disable Layout/LineLength
+      #
+      # @param [String] payload The payload from the webhook sent by WorkOS. This is the RAW_POST_DATA of the request.
+      # @param [String] sig_header The signature from the webhook sent by WorkOS.
+      # @param [String] secret The webhook secret from the WorkOS dashboard.
+      # @param [Integer] tolerance The time tolerance in seconds for the webhook.
+      #
+      # @example
+      #   WorkOS::Webhooks.construct_event(
+      #     payload: "{"id": "wh_123","data":{"id":"directory_user_01FAEAJCR3ZBZ30D8BD1924TVG","state":"active","emails":[{"type":"work","value":"blair@foo-corp.com","primary":true}],"idp_id":"00u1e8mutl6wlH3lL4x7","object":"directory_user","username":"blair@foo-corp.com","last_name":"Lunceford","first_name":"Blair","directory_id":"directory_01F9M7F68PZP8QXP8G7X5QRHS7","raw_attributes":{"name":{"givenName":"Blair","familyName":"Lunceford","middleName":"Elizabeth","honorificPrefix":"Ms."},"title":"Developer Success Engineer","active":true,"emails":[{"type":"work","value":"blair@foo-corp.com","primary":true}],"groups":[],"locale":"en-US","schemas":["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],"userName":"blair@foo-corp.com","addresses":[{"region":"CO","primary":true,"locality":"Steamboat Springs","postalCode":"80487"}],"externalId":"00u1e8mutl6wlH3lL4x7","displayName":"Blair Lunceford","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":{"manager":{"value":"2","displayName":"Kathleen Chung"},"division":"Engineering","department":"Customer Success"}}},"event":"dsync.user.created"}",
+      #     sig_header: 't=1626125972272, v1=80f7ab7efadc306eb5797c588cee9410da9be4416782b497bf1e1bf4175fb928',
+      #     secret: 'LJlTiC19GmCKWs8AE0IaOQcos',
+      #   )
+      #
+      #   => #<WorkOS::Webhook:0x00007fa64b980910 @event="dsync.user.created", @data={:id=>"directory_user_01FAEAJCR3ZBZ30D8BD1924TVG", :state=>"active", :emails=>[{:type=>"work", :value=>"blair@foo-corp.com", :primary=>true}], :idp_id=>"00u1e8mutl6wlH3lL4x7", :object=>"directory_user", :username=>"blair@foo-corp.com", :last_name=>"Lunceford", :first_name=>"Blair", :directory_id=>"directory_01F9M7F68PZP8QXP8G7X5QRHS7", :raw_attributes=>{:name=>{:givenName=>"Blair", :familyName=>"Lunceford", :middleName=>"Elizabeth", :honorificPrefix=>"Ms."}, :title=>"Developer Success Engineer", :active=>true, :emails=>[{:type=>"work", :value=>"blair@foo-corp.com", :primary=>true}], :groups=>[], :locale=>"en-US", :schemas=>["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"], :userName=>"blair@foo-corp.com", :addresses=>[{:region=>"CO", :primary=>true, :locality=>"Steamboat Springs", :postalCode=>"80487"}], :externalId=>"00u1e8mutl6wlH3lL4x7", :displayName=>"Blair Lunceford", :"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"=>{:manager=>{:value=>"2", :displayName=>"Kathleen Chung"}, :division=>"Engineering", :department=>"Customer Success"}}}>
+      #
+      # @return [WorkOS::Webhook]
+      # rubocop:enable Layout/LineLength
+      sig do
+        params(
+          payload: String,
+          sig_header: String,
+          secret: String,
+          tolerance: Integer,
+        ).returns(WorkOS::Webhook)
+      end
+      def construct_event(
+        payload:,
+        sig_header:,
+        secret:,
+        tolerance: DEFAULT_TOLERANCE
+      )
+        verify_header(payload: payload, sig_header: sig_header, secret: secret, tolerance: tolerance)
+        WorkOS::Webhook.new(payload)
+      end
+
+      private
+
+      sig do
+        params(
+          payload: String,
+          sig_header: String,
+          secret: String,
+          tolerance: Integer,
+        ).returns(T::Boolean)
+      end
+      # rubocop:disable Metrics/MethodLength
+      def verify_header(
+        payload:,
+        sig_header:,
+        secret:,
+        tolerance: DEFAULT_TOLERANCE
+      )
+        begin
+          timestamp, signature_hash = get_timestamp_and_signature_hash(sig_header: sig_header)
+        rescue StandardError
+          raise WorkOS::SignatureVerificationError.new(
+            message: 'Unable to extract timestamp and signature hash from header',
+          )
+        end
+
+        if signature_hash.empty?
+          raise WorkOS::SignatureVerificationError.new(
+            message: 'No signature hash found with expected scheme v1',
+          )
+        end
+
+        if timestamp < Time.now - tolerance
+          raise WorkOS::SignatureVerificationError.new(
+            message: 'Timestamp outside the tolerance zone',
+          )
+        end
+
+        expected_sig = compute_signature(timestamp: timestamp, payload: payload, secret: secret)
+        unless secure_compare(str_a: expected_sig, str_b: signature_hash)
+          raise WorkOS::SignatureVerificationError.new(
+            message: 'Signature hash does not match the expected signature hash for payload',
+          )
+        end
+
+        true
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      sig do
+        params(
+          sig_header: String,
+        ).returns(T::Array[T.untyped])
+      end
+      def get_timestamp_and_signature_hash(
+        sig_header:
+      )
+        timestamp, signature_hash = sig_header.split(', ')
+
+        if timestamp.nil? || signature_hash.nil?
+          raise WorkOS::SignatureVerificationError.new(
+            message: 'Unable to extract timestamp and signature hash from header',
+          )
+        end
+
+        timestamp = timestamp.sub('t=', '')
+        signature_hash = signature_hash.sub('v1=', '')
+
+        [Time.at(timestamp.to_i), signature_hash]
+      end
+
+      sig do
+        params(
+          timestamp: Time,
+          payload: String,
+          secret: String,
+        ).returns(String)
+      end
+      def compute_signature(
+        timestamp:,
+        payload:,
+        secret:
+      )
+        unhashed_string = "#{timestamp.to_i}.#{payload}"
+        digest = OpenSSL::Digest.new('sha256')
+        OpenSSL::HMAC.hexdigest(digest, secret, unhashed_string)
+      end
+
+      # Constant time string comparison to prevent timing attacks
+      # Code borrowed from ActiveSupport
+      sig do
+        params(
+          str_a: String,
+          str_b: String,
+        ).returns(T::Boolean)
+      end
+      def secure_compare(
+        str_a:,
+        str_b:
+      )
+        return false unless str_a.bytesize == str_b.bytesize
+
+        l = T.unsafe(str_a.unpack("C#{str_a.bytesize}"))
+
+        res = 0
+        str_b.each_byte { |byte| res |= byte ^ l.shift }
+
+        res.zero?
+      end
+    end
+  end
+end

data/lib/workos.rb

@@ -42,11 +42,14 @@ module WorkOS
   autoload :ProfileAndToken, 'workos/profile_and_token'
   autoload :SSO, 'workos/sso'
   autoload :DirectoryUser, 'workos/directory_user'
+  autoload :Webhook, 'workos/webhook'
+  autoload :Webhooks, 'workos/webhooks'
 
   # Errors
   autoload :APIError, 'workos/errors'
   autoload :AuthenticationError, 'workos/errors'
   autoload :InvalidRequestError, 'workos/errors'
+  autoload :SignatureVerificationError, 'workos/errors'
 
   # Remove WORKOS_KEY at some point in the future. Keeping it here now for
   # backwards compatibility.

data/spec/lib/workos/directory_sync_spec.rb

@@ -15,7 +15,7 @@ describe WorkOS::DirectorySync do
         VCR.use_cassette 'directory_sync/list_directories/with_no_options' do
           directories = described_class.list_directories
 
-          expect(directories.data.size).to eq(3)
+          expect(directories.data.size).to eq(10)
           expect(directories.list_metadata).to eq(expected_metadata)
         end
       end
@@ -46,7 +46,7 @@ describe WorkOS::DirectorySync do
     context 'with search option' do
       it 'forms the proper request to the API' do
         request_args = [
-          '/directories?search=Foo',
+          '/directories?search=Testing',
           'Content-Type' => 'application/json'
         ]
 
@@ -57,10 +57,11 @@ describe WorkOS::DirectorySync do
 
         VCR.use_cassette 'directory_sync/list_directories/with_search' do
           directories = described_class.list_directories(
-            search: 'Foo',
+            search: 'Testing',
           )
 
-          expect(directories.data.size).to eq(1)
+          expect(directories.data.size).to eq(2)
+          expect(directories.data[0].name).to include('Testing')
         end
       end
     end
@@ -68,7 +69,7 @@ describe WorkOS::DirectorySync do
     context 'with the before option' do
       it 'forms the proper request to the API' do
         request_args = [
-          '/directories?before=before-id',
+          '/directories?before=directory_01FGCPNV312FHFRCX0BYWHVSE1',
           'Content-Type' => 'application/json'
         ]
 
@@ -79,10 +80,10 @@ describe WorkOS::DirectorySync do
 
         VCR.use_cassette 'directory_sync/list_directories/with_before' do
           directories = described_class.list_directories(
-            before: 'before-id',
+            before: 'directory_01FGCPNV312FHFRCX0BYWHVSE1',
           )
 
-          expect(directories.data.size).to eq(3)
+          expect(directories.data.size).to eq(6)
         end
       end
     end
@@ -90,7 +91,7 @@ describe WorkOS::DirectorySync do
     context 'with the after option' do
       it 'forms the proper request to the API' do
         request_args = [
-          '/directories?after=after-id',
+          '/directories?after=directory_01FGCPNV312FHFRCX0BYWHVSE1',
           'Content-Type' => 'application/json'
         ]
 
@@ -100,9 +101,9 @@ describe WorkOS::DirectorySync do
           and_return(expected_request)
 
         VCR.use_cassette 'directory_sync/list_directories/with_after' do
-          directories = described_class.list_directories(after: 'after-id')
+          directories = described_class.list_directories(after: 'directory_01FGCPNV312FHFRCX0BYWHVSE1')
 
-          expect(directories.data.size).to eq(3)
+          expect(directories.data.size).to eq(4)
         end
       end
     end
@@ -142,6 +143,38 @@ describe WorkOS::DirectorySync do
     end
   end
 
+  describe '.get_directory' do
+    context 'with a valid id' do
+      it 'gets the directory details' do
+        VCR.use_cassette('directory_sync/get_directory_with_valid_id') do
+          directory = WorkOS::DirectorySync.get_directory(
+            id: 'directory_01FK17DWRHH7APAFXT5B52PV0W',
+          )
+
+          expect(directory.id).to eq('directory_01FK17DWRHH7APAFXT5B52PV0W')
+          expect(directory.name).to eq('Testing Active Attribute')
+          expect(directory.domain).to eq('example.me')
+          expect(directory.type).to eq('azure scim v2.0')
+          expect(directory.state).to eq('linked')
+          expect(directory.organization_id).to eq('org_01F6Q6TFP7RD2PF6J03ANNWDKV')
+        end
+      end
+    end
+
+    context 'with an invalid id' do
+      it 'raises an error' do
+        VCR.use_cassette('directory_sync/get_directory_with_invalid_id') do
+          expect do
+            WorkOS::DirectorySync.get_directory(id: 'invalid')
+          end.to raise_error(
+            WorkOS::APIError,
+            "Status 404, Directory not found: 'invalid'. - request ID: ",
+          )
+        end
+      end
+    end
+  end
+
   describe '.list_groups' do
     context 'with no options' do
       it 'raises an error' do

data/spec/lib/workos/sso_spec.rb

@@ -109,7 +109,145 @@ describe WorkOS::SSO do
       end
     end
 
-    context 'with neither connection, domain, or provider' do
+    context 'with a domain' do
+      let(:args) do
+        {
+          domain: 'foo.com',
+          client_id: 'workos-proj-123',
+          redirect_uri: 'foo.com/auth/callback',
+          state: {
+            next_page: '/dashboard/edit',
+          }.to_s,
+        }
+      end
+      it 'returns a valid URL' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url)).to be_a URI
+      end
+
+      it 'returns the expected hostname' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).host).to eq(WorkOS::API_HOSTNAME)
+      end
+
+      it 'returns the expected query string' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).query).to eq(
+          'client_id=workos-proj-123&redirect_uri=foo.com%2Fauth%2Fcallback' \
+          '&response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdashboard%2F' \
+          'edit%22%7D&domain=foo.com',
+        )
+      end
+    end
+
+    context 'with a domain_hint' do
+      let(:args) do
+        {
+          connection: 'connection_123',
+          domain_hint: 'foo.com',
+          client_id: 'workos-proj-123',
+          redirect_uri: 'foo.com/auth/callback',
+          state: {
+            next_page: '/dashboard/edit',
+          }.to_s,
+        }
+      end
+      it 'returns a valid URL' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url)).to be_a URI
+      end
+
+      it 'returns the expected hostname' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).host).to eq(WorkOS::API_HOSTNAME)
+      end
+
+      it 'returns the expected query string' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).query).to eq(
+          'client_id=workos-proj-123&redirect_uri=foo.com%2Fauth%2Fcallback' \
+          '&response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdashboard%2' \
+          'Fedit%22%7D&domain_hint=foo.com&connection=connection_123',
+        )
+      end
+    end
+
+    context 'with a login_hint' do
+      let(:args) do
+        {
+          connection: 'connection_123',
+          login_hint: 'foo@workos.com',
+          client_id: 'workos-proj-123',
+          redirect_uri: 'foo.com/auth/callback',
+          state: {
+            next_page: '/dashboard/edit',
+          }.to_s,
+        }
+      end
+      it 'returns a valid URL' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url)).to be_a URI
+      end
+
+      it 'returns the expected hostname' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).host).to eq(WorkOS::API_HOSTNAME)
+      end
+
+      it 'returns the expected query string' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).query).to eq(
+          'client_id=workos-proj-123&redirect_uri=foo.com%2Fauth%2Fcallback' \
+          '&response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdashboard%2' \
+          'Fedit%22%7D&login_hint=foo%40workos.com&connection=connection_123',
+        )
+      end
+    end
+
+    context 'with an organization' do
+      let(:args) do
+        {
+          organization: 'org_123',
+          client_id: 'workos-proj-123',
+          redirect_uri: 'foo.com/auth/callback',
+          state: {
+            next_page: '/dashboard/edit',
+          }.to_s,
+        }
+      end
+      it 'returns a valid URL' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url)).to be_a URI
+      end
+
+      it 'returns the expected hostname' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).host).to eq(WorkOS::API_HOSTNAME)
+      end
+
+      it 'returns the expected query string' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).query).to eq(
+          'client_id=workos-proj-123&redirect_uri=foo.com%2Fauth%2Fcallback' \
+          '&response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdashboard%2F' \
+          'edit%22%7D&organization=org_123',
+        )
+      end
+    end
+
+    context 'with neither connection, domain, provider, or organization' do
       let(:args) do
         {
           client_id: 'workos-proj-123',
@@ -124,7 +262,7 @@ describe WorkOS::SSO do
           described_class.authorization_url(**args)
         end.to raise_error(
           ArgumentError,
-          'Either connection, domain, or provider is required.',
+          'Either connection, domain, provider, or organization is required.',
         )
       end
     end
@@ -164,6 +302,7 @@ describe WorkOS::SSO do
           id: 'prof_01EEJTY9SZ1R350RB7B73SNBKF',
           idp_id: '116485463307139932699',
           last_name: 'Loblaw',
+          organization_id: 'org_01FG53X8636WSNW2WEKB2C31ZB',
           raw_attributes: {
             email: 'bob.loblaw@workos.com',
             family_name: 'Loblaw',
@@ -233,6 +372,7 @@ describe WorkOS::SSO do
           id: 'prof_01DRA1XNSJDZ19A31F183ECQW5',
           idp_id: '00u1klkowm8EGah2H357',
           last_name: 'Demo',
+          organization_id: 'org_01FG53X8636WSNW2WEKB2C31ZB',
           raw_attributes: {
             email: 'demo@workos-okta.com',
             first_name: 'WorkOS',

data/spec/lib/workos/webhooks_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+# typed: false
+
+require 'json'
+require 'openssl'
+
+describe WorkOS::Webhooks do
+  describe '.construct_event' do
+    before(:each) do
+      @payload = File.read("#{SPEC_ROOT}/support/webhook_payload.txt")
+      @secret = 'secret'
+      @timestamp = Time.at(Time.now.to_i * 1000)
+      unhashed_string = "#{@timestamp.to_i}.#{@payload}"
+      digest = OpenSSL::Digest.new('sha256')
+      @signature_hash = OpenSSL::HMAC.hexdigest(digest, @secret, unhashed_string)
+      @expectation = {
+        id: 'directory_user_01FAEAJCR3ZBZ30D8BD1924TVG',
+        state: 'active',
+        emails: [{
+          type: 'work',
+          value: 'blair@foo-corp.com',
+          primary: true,
+        }],
+        idp_id: '00u1e8mutl6wlH3lL4x7',
+        object: 'directory_user',
+        username: 'blair@foo-corp.com',
+        last_name: 'Lunceford',
+        first_name: 'Blair',
+        directory_id: 'directory_01F9M7F68PZP8QXP8G7X5QRHS7',
+        raw_attributes: {
+          name: {
+            givenName: 'Blair',
+            familyName: 'Lunceford',
+            middleName: 'Elizabeth',
+            honorificPrefix: 'Ms.',
+          },
+          title: 'Developer Success Engineer',
+          active: true,
+          emails: [{
+            type: 'work',
+            value: 'blair@foo-corp.com',
+            primary: true,
+          }],
+          groups: [],
+          locale: 'en-US',
+          schemas: [
+            'urn:ietf:params:scim:schemas:core:2.0:User',
+            'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User'
+          ],
+          userName: 'blair@foo-corp.com',
+          addresses: [{
+            region: 'CO',
+            primary: true,
+            locality: 'Steamboat Springs',
+            postalCode: '80487',
+          }],
+          externalId: '00u1e8mutl6wlH3lL4x7',
+          displayName: 'Blair Lunceford',
+          "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
+            manager: {
+              value: '2',
+              displayName: 'Kathleen Chung',
+            },
+            division: 'Engineering',
+            department: 'Customer Success',
+          },
+        },
+      }
+    end
+
+    context 'with the correct payload, sig_header, and secret' do
+      it 'returns a webhook event' do
+        webhook = described_class.construct_event(
+          payload: @payload,
+          sig_header: "t=#{@timestamp.to_i}, v1=#{@signature_hash}",
+          secret: @secret,
+        )
+
+        expect(webhook.data).to eq(@expectation)
+        expect(webhook.event).to eq('dsync.user.created')
+        expect(webhook.id).to eq('wh_123')
+      end
+    end
+
+    context 'with the correct payload, sig_header, secret, and tolerance' do
+      it 'returns a webhook event' do
+        webhook = described_class.construct_event(
+          payload: @payload,
+          sig_header: "t=#{@timestamp.to_i}, v1=#{@signature_hash}",
+          secret: @secret,
+          tolerance: 300,
+        )
+
+        expect(webhook.data).to eq(@expectation)
+        expect(webhook.event).to eq('dsync.user.created')
+        expect(webhook.id).to eq('wh_123')
+      end
+    end
+
+    context 'with an empty header' do
+      it 'raises an error' do
+        expect do
+          described_class.construct_event(
+            payload: @payload,
+            sig_header: '',
+            secret: @secret,
+          )
+        end.to raise_error(
+          WorkOS::SignatureVerificationError,
+          'Unable to extract timestamp and signature hash from header',
+        )
+      end
+    end
+
+    context 'with an empty signature hash' do
+      it 'raises an error' do
+        expect do
+          described_class.construct_event(
+            payload: @payload,
+            sig_header: "t=#{@timestamp.to_i}, v1=",
+            secret: @secret,
+          )
+        end.to raise_error(
+          WorkOS::SignatureVerificationError,
+          'No signature hash found with expected scheme v1',
+        )
+      end
+    end
+
+    context 'with an incorrect signature hash' do
+      it 'raises an error' do
+        expect do
+          described_class.construct_event(
+            payload: @payload,
+            sig_header: "t=#{@timestamp.to_i}, v1=99999",
+            secret: @secret,
+          )
+        end.to raise_error(
+          WorkOS::SignatureVerificationError,
+          'Signature hash does not match the expected signature hash for payload',
+        )
+      end
+    end
+
+    context 'with an incorrect payload' do
+      it 'raises an error' do
+        expect do
+          described_class.construct_event(
+            payload: 'invalid',
+            sig_header: "t=#{@timestamp.to_i}, v1=#{@signature_hash}",
+            secret: @secret,
+          )
+        end.to raise_error(
+          WorkOS::SignatureVerificationError,
+          'Signature hash does not match the expected signature hash for payload',
+        )
+      end
+    end
+
+    context 'with an incorrect webhook secret' do
+      it 'raises an error' do
+        expect do
+          described_class.construct_event(
+            payload: @payload,
+            sig_header: "t=#{@timestamp.to_i}, v1=#{@signature_hash}",
+            secret: 'invalid',
+          )
+        end.to raise_error(
+          WorkOS::SignatureVerificationError,
+          'Signature hash does not match the expected signature hash for payload',
+        )
+      end
+    end
+
+    context 'with a timestamp outside tolerance' do
+      it 'raises an error' do
+        expect do
+          described_class.construct_event(
+            payload: @payload,
+            sig_header: "t=9999, v1=#{@signature_hash}",
+            secret: @secret,
+          )
+        end.to raise_error(
+          WorkOS::SignatureVerificationError,
+          'Timestamp outside the tolerance zone',
+        )
+      end
+    end
+  end
+end