workosv2 2.15.0

data/lib/workosv2/sso.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+# typed: true
+
+require 'net/http'
+require 'uri'
+
+module WorkOSV2
+  # The SSO module provides convenience methods for working with the WorkOSV2
+  # SSO platform. You'll need a valid API key, a client ID, and to have
+  # created an SSO connection on your WorkOSV2 dashboard.
+  #
+  # @see https://docs.workos.com/sso/overview
+  module SSO
+    class << self
+      extend T::Sig
+      include Client
+
+      PROVIDERS = WorkOSV2::Types::Provider.values.map(&:serialize).freeze
+
+      # Generate an Oauth2 authorization URL where your users will
+      # authenticate using the configured SSO Identity Provider.
+      #
+      # @param [String] redirect_uri The URI where users are directed
+      #  after completing the authentication step. Must match a
+      #  configured redirect URI on your WorkOSV2 dashboard.
+      # @param [String] client_id The WorkOSV2 client ID for the environment
+      #  where you've configured your SSO connection.
+      # @param [String] domain The domain for the relevant SSO Connection
+      #  configured on your WorkOSV2 dashboard. One of provider, domain,
+      #  connection, or organization is required.
+      #  The domain is deprecated.
+      # @param [String] provider A provider name for an Identity Provider
+      #  configured on your WorkOSV2 dashboard. Only 'GoogleOAuth' and
+      #  'MicrosoftOAuth' are supported.
+      # @param [String] connection The ID for a Connection configured on
+      #  WorkOSV2.
+      # @param [String] organization The ID for an Organization configured
+      #  on WorkOSV2.
+      # @param [String] state An arbitrary state object
+      #  that is preserved and available to the client in the response.
+      # @example
+      #   WorkOSV2::SSO.authorization_url(
+      #     connection: 'conn_123',
+      #     client_id: 'project_01DG5TGK363GRVXP3ZS40WNGEZ',
+      #     redirect_uri: 'https://workos.com/callback',
+      #     state: {
+      #       next_page: '/docs'
+      #     }.to_s
+      #   )
+      #
+      #   => "https://api.workos.com/sso/authorize?connection=conn_123" \
+      #      "&client_id=project_01DG5TGK363GRVXP3ZS40WNGEZ" \
+      #      "&redirect_uri=https%3A%2F%2Fworkos.com%2Fcallback&" \
+      #      "response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdocs%22%7D"
+      #
+      # @return [String]
+      # rubocop:disable Metrics/ParameterLists
+      sig do
+        params(
+          redirect_uri: String,
+          client_id: T.nilable(String),
+          domain: T.nilable(String),
+          domain_hint: T.nilable(String),
+          login_hint: T.nilable(String),
+          provider: T.nilable(String),
+          connection: T.nilable(String),
+          organization: T.nilable(String),
+          state: T.nilable(String),
+        ).returns(String)
+      end
+      def authorization_url(
+        redirect_uri:,
+        client_id: nil,
+        domain: nil,
+        domain_hint: nil,
+        login_hint: nil,
+        provider: nil,
+        connection: nil,
+        organization: nil,
+        state: ''
+      )
+        if domain
+          warn '[DEPRECATION] `domain` is deprecated.
+          Please use `organization` instead.'
+        end
+
+        validate_authorization_url_arguments(
+          provider: provider,
+          domain: domain,
+          connection: connection,
+          organization: organization,
+        )
+
+        query = URI.encode_www_form({
+          client_id: client_id,
+          redirect_uri: redirect_uri,
+          response_type: 'code',
+          state: state,
+          domain: domain,
+          domain_hint: domain_hint,
+          login_hint: login_hint,
+          provider: provider,
+          connection: connection,
+          organization: organization,
+        }.compact)
+
+        "https://#{WorkOSV2::API_HOSTNAME}/sso/authorize?#{query}"
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      sig do
+        params(
+          access_token: String,
+        ).returns(WorkOSV2::Profile)
+      end
+      def get_profile(access_token:)
+        response = execute_request(
+          request: get_request(
+            path: '/sso/profile',
+            auth: true,
+            access_token: access_token,
+          ),
+        )
+
+        WorkOSV2::Profile.new(response.body)
+      end
+
+      # Fetch the profile details for the authenticated SSO user.
+      #
+      # @param [String] code The authorization code provided in the callback URL
+      # @param [String] client_id The WorkOSV2 client ID for the environment
+      #  where you've configured your SSO connection
+      #
+      # @return [WorkOSV2::ProfileAndToken]
+      sig do
+        params(
+          code: String,
+          client_id: T.nilable(String),
+        ).returns(WorkOSV2::ProfileAndToken)
+      end
+      def profile_and_token(code:, client_id: nil)
+        body = {
+          client_id: client_id,
+          client_secret: WorkOSV2.config.key!,
+          grant_type: 'authorization_code',
+          code: code,
+        }
+
+        response = client.request(post_request(path: '/sso/token', body: body))
+        check_and_raise_profile_and_token_error(response: response)
+
+        WorkOSV2::ProfileAndToken.new(response.body)
+      end
+
+      # Retrieve connections.
+      #
+      # @param [Hash] options An options hash
+      # @option options [String] connection_type Authentication service
+      #  provider descriptor.
+      # @option options [String] domain The domain of the connection to be
+      #  retrieved.
+      # @option options [String] organization_id The id of the organization
+      #  of the connections to be retrieved.
+      # @option options [String] limit Maximum number of records to return.
+      # @option options [String] order The order in which to paginate records
+      # @option options [String] before Pagination cursor to receive records
+      #  before a provided Connection ID.
+      # @option options [String] after Pagination cursor to receive records
+      #  before a provided Connection ID.
+      #
+      # @return [Hash]
+      sig do
+        params(
+          options: T::Hash[Symbol, String],
+        ).returns(WorkOSV2::Types::ListStruct)
+      end
+      def list_connections(options = {})
+        response = execute_request(
+          request: get_request(
+            path: '/connections',
+            auth: true,
+            params: options,
+          ),
+        )
+
+        parsed_response = JSON.parse(response.body)
+        connections = parsed_response['data'].map do |connection|
+          ::WorkOSV2::Connection.new(connection.to_json)
+        end
+
+        WorkOSV2::Types::ListStruct.new(
+          data: connections,
+          list_metadata: parsed_response['listMetadata'],
+        )
+      end
+
+      # Get a Connection
+      #
+      # @param [String] id Connection unique identifier
+      #
+      # @example
+      #   WorkOSV2::SSO.get_connection(id: 'conn_02DRA1XNSJDZ19A31F183ECQW9')
+      #   => #<WorkOSV2::Connection:0x00007fb6e4193d20
+      #         @id="conn_02DRA1XNSJDZ19A31F183ECQW9",
+      #         @name="Foo Corp",
+      #         @connection_type="OktaSAML",
+      #         @domains=
+      #          [{:object=>"connection_domain",
+      #            :id=>"domain_01E6PK9N3XMD8RHWF7S66380AR",
+      #            :domain=>"example.com"}]>
+      #
+      # @return [WorkOSV2::Connection]
+      sig { params(id: String).returns(WorkOSV2::Connection) }
+      def get_connection(id:)
+        request = get_request(
+          auth: true,
+          path: "/connections/#{id}",
+        )
+
+        response = execute_request(request: request)
+
+        WorkOSV2::Connection.new(response.body)
+      end
+
+      # Delete a Connection
+      #
+      # @param [String] id Connection unique identifier
+      #
+      # @example
+      #   WorkOSV2::SSO.delete_connection(id: 'conn_02DRA1XNSJDZ19A31F183ECQW9')
+      #   => true
+      #
+      # @return [Bool] - returns `true` if successful
+      sig { params(id: String).returns(T::Boolean) }
+      def delete_connection(id:)
+        request = delete_request(
+          auth: true,
+          path: "/connections/#{id}",
+        )
+
+        response = execute_request(request: request)
+
+        response.is_a? Net::HTTPSuccess
+      end
+
+      private
+
+      sig do
+        params(
+          domain: T.nilable(String),
+          provider: T.nilable(String),
+          connection: T.nilable(String),
+          organization: T.nilable(String),
+        ).void
+      end
+      def validate_authorization_url_arguments(
+        domain:,
+        provider:,
+        connection:,
+        organization:
+      )
+        if [domain, provider, connection, organization].all?(&:nil?)
+          raise ArgumentError, 'Either connection, domain, ' \
+            'provider, or organization is required.'
+        end
+
+        return unless provider && !PROVIDERS.include?(provider)
+
+        raise ArgumentError, "#{provider} is not a valid value." \
+          " `provider` must be in #{PROVIDERS}"
+      end
+
+      sig { params(response: Net::HTTPResponse).void }
+      def check_and_raise_profile_and_token_error(response:)
+        begin
+          body = JSON.parse(response.body)
+          return if body['access_token'] && body['profile']
+
+          message = body['message']
+          error = body['error']
+          error_description = body['error_description']
+          request_id = response['x-request-id']
+        rescue StandardError
+          message = 'Something went wrong'
+        end
+
+        raise APIError.new(
+          message: message,
+          error: error,
+          error_description: error_description,
+          http_status: nil,
+          request_id: request_id,
+        )
+      end
+    end
+  end
+end

data/lib/workosv2/types/audit_log_export_struct.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This AuditLogExportStruct acts as a typed interface
+    # for the AuditLogExport class
+    class AuditLogExportStruct < T::Struct
+      const :object, String
+      const :id, String
+      const :state, String
+      const :url, T.nilable(String)
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/challenge_struct.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This ChallgengeStruct acts as a typed interface
+    # for the Factor class
+    class ChallengeStruct < T::Struct
+      const :id, String
+      const :object, String
+      const :expires_at, String
+      const :code, T.nilable(String)
+      const :authentication_factor_id, String
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/connection_struct.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This ConnectionStruct acts as a typed interface
+    # for the Connection class
+    class ConnectionStruct < T::Struct
+      const :id, String
+      const :name, String
+      const :connection_type, String
+      const :domains, T::Array[T.untyped]
+      const :organization_id, T.nilable(String)
+      const :state, String
+      const :status, String
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/directory_group_struct.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This DirectoryGroupStruct acts as a typed interface
+    # for the DirectoryGroup class
+    class DirectoryGroupStruct < T::Struct
+      const :id, String
+      const :directory_id, String
+      const :organization_id, T.nilable(String)
+      const :idp_id, String
+      const :name, String
+      const :created_at, String
+      const :updated_at, String
+      const :raw_attributes, T::Hash[Symbol, Object]
+    end
+  end
+end

data/lib/workosv2/types/directory_struct.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This DirectoryStruct acts as a typed interface
+    # for the Directory class
+    class DirectoryStruct < T::Struct
+      const :id, String
+      const :name, String
+      const :domain, T.nilable(String)
+      const :type, String
+      const :state, String
+      const :organization_id, T.nilable(String)
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/directory_user_struct.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # The DirectoryUserStruct acts as a typed interface
+    # for the DirectoryUser class
+    class DirectoryUserStruct < T::Struct
+      const :id, String
+      const :directory_id, String
+      const :organization_id, T.nilable(String)
+      const :idp_id, String
+      const :emails, T::Array[T.untyped]
+      const :first_name, T.nilable(String)
+      const :last_name, T.nilable(String)
+      const :job_title, T.nilable(String)
+      const :username, T.nilable(String)
+      const :state, T.nilable(String)
+      const :groups, T::Array[T.untyped]
+      const :custom_attributes, T::Hash[Symbol, T.untyped]
+      const :raw_attributes, T::Hash[Symbol, Object]
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/event_struct.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # The EventStruct acts as a typed interface
+    # for the Event class
+    class EventStruct < T::Struct
+      const :id, String
+      const :event, String
+      const :data, T::Hash[Symbol, Object]
+      const :created_at, String
+    end
+  end
+end

data/lib/workosv2/types/factor_struct.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This FactorStruct acts as a typed interface
+    # for the Factor class
+    class FactorStruct < T::Struct
+      const :id, String
+      const :object, String
+      const :type, String
+      const :totp, T.nilable(T::Hash[Symbol, Object])
+      const :sms, T.nilable(T::Hash[Symbol, Object])
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/intent_enum.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # The IntentEnum is type-safe declarations of a fixed set of values for
+    # intents while generating an Admin Portal link.
+    class Intent < T::Enum
+      enums do
+        AUDIT_LOGS = new('audit_logs')
+        DSYNC = new('dsync')
+        LOG_STREAMS = new('log_streams')
+        SSO = new('sso')
+      end
+    end
+  end
+end

data/lib/workosv2/types/list_struct.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # ListStruct acts as a typed interface to expose lists of data and related
+    # metadata
+    class ListStruct < T::Struct
+      const :data, T::Array[T.untyped]
+      const :list_metadata, T::Hash[String, T.nilable(String)]
+    end
+  end
+end

data/lib/workosv2/types/organization_struct.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This OrganizationStruct acts as a typed interface
+    # for the Organization class
+    class OrganizationStruct < T::Struct
+      const :id, String
+      const :name, String
+      const :allow_profiles_outside_organization, T::Boolean
+      const :domains, T::Array[T.untyped]
+      const :created_at, String
+      const :updated_at, String
+    end
+  end
+end

data/lib/workosv2/types/passwordless_session_struct.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'date'
+
+module WorkOSV2
+  module Types
+    # This PasswordlessSessionStruct acts as a typed interface
+    # for the Passwordless class
+    class PasswordlessSessionStruct < T::Struct
+      const :id, String
+      const :email, String
+      const :expires_at, Date
+      const :link, String
+    end
+  end
+end

data/lib/workosv2/types/profile_struct.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # The ProfileStruct acts as a typed interface
+    # for the Profile class
+    class ProfileStruct < T::Struct
+      const :id, String
+      const :email, String
+      const :first_name, T.nilable(String)
+      const :last_name, T.nilable(String)
+      const :groups, T.nilable(T::Array[String])
+      const :organization_id, T.nilable(String)
+      const :connection_id, String
+      const :connection_type, String
+      const :idp_id, T.nilable(String)
+      const :raw_attributes, T::Hash[Symbol, Object]
+    end
+  end
+end

data/lib/workosv2/types/provider_enum.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # The ProviderEnum is type-safe declarations of a
+    # fixed set of values for SSO Providers.
+    class Provider < T::Enum
+      enums do
+        Google = new('GoogleOAuth')
+        Microsoft = new('MicrosoftOAuth')
+      end
+    end
+  end
+end

data/lib/workosv2/types/verify_challenge_struct.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This VerifyChallengeStruct acts as a typed interface
+    # for the VerifyChallenge class
+    class VerifyChallengeStruct < T::Struct
+      const :challenge, T.nilable(T::Hash[Symbol, Object])
+      const :valid, T::Boolean
+    end
+  end
+end

data/lib/workosv2/types/webhook_struct.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# typed: strict
+
+module WorkOSV2
+  module Types
+    # This WebhookStruct acts as a typed interface
+    # for the Webhook class
+    class WebhookStruct < T::Struct
+      const :id, String
+      const :event, String
+      const :data, T::Hash[Symbol, Object]
+      const :created_at, String
+    end
+  end
+end

data/lib/workosv2/types.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# typed: strong
+
+module WorkOSV2
+  # WorkOSV2 believes strongly in typed languages,
+  # so we're using Sorbet throughout this Ruby gem.
+  module Types
+    require_relative 'types/audit_log_export_struct'
+    require_relative 'types/connection_struct'
+    require_relative 'types/directory_struct'
+    require_relative 'types/directory_group_struct'
+    require_relative 'types/event_struct'
+    require_relative 'types/intent_enum'
+    require_relative 'types/list_struct'
+    require_relative 'types/organization_struct'
+    require_relative 'types/passwordless_session_struct'
+    require_relative 'types/profile_struct'
+    require_relative 'types/provider_enum'
+    require_relative 'types/directory_user_struct'
+    require_relative 'types/webhook_struct'
+    require_relative 'types/factor_struct'
+    require_relative 'types/challenge_struct'
+    require_relative 'types/verify_challenge_struct'
+  end
+end

data/lib/workosv2/verify_challenge.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# typed: false
+
+module WorkOSV2
+  # The VerifyChallenge class provides a lightweight wrapper around
+  # a WorkOSV2 Authentication Challenge resource.
+  class VerifyChallenge
+    include HashProvider
+    extend T::Sig
+
+    attr_accessor :challenge, :valid
+
+    sig { params(json: String).void }
+    def initialize(json)
+      raw = parse_json(json)
+      @challenge = T.let(raw.challenge, Hash)
+      @valid = raw.valid
+    end
+
+    def to_json(*)
+      {
+        challenge: challenge,
+        valid: valid,
+      }
+    end
+
+    private
+
+    sig { params(json_string: String).returns(WorkOSV2::Types::VerifyChallengeStruct) }
+    def parse_json(json_string)
+      hash = JSON.parse(json_string, symbolize_names: true)
+
+      WorkOSV2::Types::VerifyChallengeStruct.new(
+        challenge: hash[:challenge],
+        valid: hash[:valid],
+      )
+    end
+  end
+end

data/lib/workosv2/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# typed: strong
+
+module WorkOSV2
+  VERSION = '2.15.0'
+end