workos 5.18.0 → 5.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7bcbc31ee2fd99bc75f92dd89397a5acb223fcd12f7ce5d24e396b966240cb1
-  data.tar.gz: 7f21e67f61a6d63c746e50dd3e6753acea90ab39d765bdd0c4f9566b5b0135e5
+  metadata.gz: dc1f97c76fdf489cb3be51bd9026dc515195c34aaf9810379bfe4773029aafc1
+  data.tar.gz: 2176f6680ae6a7c46ca77824c7dcf2fbe91ca244986a05f7039a1d40265db881
 SHA512:
-  metadata.gz: f48581ece4c6ee347403cdc865b4bb6ed0637ad7fec62ecd7926016f709988cd9106d37f8a138bbddf15a8fa0aa95fa65c3d496356fb6bcb56ce70163f1c0004
-  data.tar.gz: ed1e358de54b404eca9ef2036dae4a4a777b519d4c00583a789221cb08393e5d4a8fbe79dfc5fe1ed632522ae02734fb1b3145a649fa6c1e0813b2d25fab4719
+  metadata.gz: 6bda209314485831a8237e381566472c5815dea3b727db277e2a06c3db1c06191da54dc59292ec37bd4415291ca78c7593ae4a78cad82775ce6ffb8eae6d0931
+  data.tar.gz: fd199d57bd3e29e0bea6b21840597ae255db869c9815b6a06348a90c3d70532606732c999c8bef3caa2ba2900914c20b222b526c7e1a9b61c836f30f5e55d694

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    workos (5.18.0)
+    workos (5.20.0)
       encryptor (~> 3.0)
       jwt (~> 2.8)
 

data/lib/workos/authentication_response.rb

@@ -12,7 +12,8 @@ module WorkOS
                   :access_token,
                   :refresh_token,
                   :authentication_method,
-                  :sealed_session
+                  :sealed_session,
+                  :oauth_tokens
 
     # rubocop:disable Metrics/AbcSize
     def initialize(authentication_response_json, session = nil)
@@ -27,6 +28,7 @@ module WorkOS
                            reason: impersonator_json[:reason],)
         end
       @authentication_method = json[:authentication_method]
+      @oauth_tokens = json[:oauth_tokens] ? WorkOS::OAuthTokens.new(json[:oauth_tokens].to_json) : nil
       @sealed_session =
         if session && session[:seal_session]
           WorkOS::Session.seal_data({
@@ -49,6 +51,7 @@ module WorkOS
         refresh_token: refresh_token,
         authentication_method: authentication_method,
         sealed_session: sealed_session,
+        oauth_tokens: oauth_tokens&.to_json,
       }
     end
   end

data/lib/workos/oauth_tokens.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module WorkOS
+  # The OAuthTokens class represents the third party provider OAuth tokens returned in the authentication response.
+  # This class is not meant to be instantiated in user space, and is instantiated internally but exposed.
+  class OAuthTokens
+    include HashProvider
+
+    attr_accessor :access_token, :refresh_token, :scopes, :expires_at
+
+    def initialize(json)
+      hash = JSON.parse(json, symbolize_names: true)
+
+      @access_token = hash[:access_token]
+      @refresh_token = hash[:refresh_token]
+      @scopes = hash[:scopes]
+      @expires_at = hash[:expires_at]
+    end
+
+    def to_json(*)
+      {
+        access_token: access_token,
+        refresh_token: refresh_token,
+        scopes: scopes,
+        expires_at: expires_at,
+      }
+    end
+  end
+end

data/lib/workos/user_management.rb

@@ -71,6 +71,7 @@ module WorkOS
       # field of the IdP sign-in page for the user, if you know their username ahead of time.
       # @param [String] domain_hint Can be used to pre-fill the domain field when
       # initiating authentication with Microsoft OAuth, or with a GoogleSAML connection type.
+      # @param [Array<String>] provider_scopes An array of additional OAuth scopes to request from the provider.
       # @example
       #   WorkOS::UserManagement.authorization_url(
       #     connection_id: 'conn_123',
@@ -96,7 +97,8 @@ module WorkOS
         provider: nil,
         connection_id: nil,
         organization_id: nil,
-        state: ''
+        state: '',
+        provider_scopes: nil
       )
 
         validate_authorization_url_arguments(
@@ -115,6 +117,7 @@ module WorkOS
           provider: provider,
           connection_id: connection_id,
           organization_id: organization_id,
+          provider_scopes: provider_scopes,
         }.compact)
 
         "https://#{WorkOS.config.api_hostname}/user_management/authorize?#{query}"
@@ -278,9 +281,20 @@ module WorkOS
       # @param [String] client_id The WorkOS client ID for the environment
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
-      def authenticate_with_password(email:, password:, client_id:, ip_address: nil, user_agent: nil)
+      def authenticate_with_password(
+        email:,
+        password:,
+        client_id:,
+        ip_address: nil,
+        user_agent: nil,
+        session: nil
+      )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -296,7 +310,7 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
 
       # Authenticate a user using OAuth or an organization's SSO connection.
@@ -317,9 +331,7 @@ module WorkOS
         user_agent: nil,
         session: nil
       )
-        if session && (session[:seal_session] == true) && session[:cookie_password].nil?
-          raise ArgumentError, 'cookie_password is required when sealing session'
-        end
+        validate_session(session)
 
         response = execute_request(
           request: post_request(
@@ -357,9 +369,7 @@ module WorkOS
         user_agent: nil,
         session: nil
       )
-        if session && (session[:seal_session] == true) && session[:cookie_password].nil?
-          raise ArgumentError, 'cookie_password is required when sealing session'
-        end
+        validate_session(session)
 
         response = execute_request(
           request: post_request(
@@ -388,16 +398,22 @@ module WorkOS
       # @param [String] link_authorization_code Used to link an OAuth profile to an existing user,
       # after having completed a Magic Code challenge.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
+      # rubocop:disable Metrics/ParameterLists
       def authenticate_with_magic_auth(
         code:,
         email:,
         client_id:,
         ip_address: nil,
         user_agent: nil,
-        link_authorization_code: nil
+        link_authorization_code: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -414,8 +430,9 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Authenticate a user into an organization they are a member of.
       #
@@ -424,6 +441,8 @@ module WorkOS
       # @param [String] pending_authentication_token The pending authentication token
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
       def authenticate_with_organization_selection(
@@ -431,8 +450,11 @@ module WorkOS
         organization_id:,
         pending_authentication_token:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -448,7 +470,7 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
 
       # Authenticate a user using TOTP.
@@ -461,16 +483,22 @@ module WorkOS
       # authentication request.
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
+      # rubocop:disable Metrics/ParameterLists
       def authenticate_with_totp(
         code:,
         client_id:,
         pending_authentication_token:,
         authentication_challenge_id:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -487,8 +515,9 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Authenticate a user using Email Verification Code.
       #
@@ -498,6 +527,8 @@ module WorkOS
       # authentication attempt due to an unverified email address.
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
       def authenticate_with_email_verification(
@@ -505,8 +536,11 @@ module WorkOS
         client_id:,
         pending_authentication_token:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -522,7 +556,7 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
 
       # Get the logout URL for a session
@@ -1082,6 +1116,12 @@ module WorkOS
 
       private
 
+      def validate_session(session)
+        return unless session && (session[:seal_session] == true) && session[:cookie_password].nil?
+
+        raise ArgumentError, 'cookie_password is required when sealing session'
+      end
+
       def validate_authorization_url_arguments(
         provider:,
         connection_id:,

data/lib/workos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WorkOS
-  VERSION = '5.18.0'
+  VERSION = '5.20.0'
 end

data/lib/workos.rb

@@ -63,6 +63,7 @@ module WorkOS
   autoload :Invitation, 'workos/invitation'
   autoload :MagicAuth, 'workos/magic_auth'
   autoload :MFA, 'workos/mfa'
+  autoload :OAuthTokens, 'workos/oauth_tokens'
   autoload :Organization, 'workos/organization'
   autoload :Organizations, 'workos/organizations'
   autoload :OrganizationMembership, 'workos/organization_membership'

data/spec/lib/workos/user_management_spec.rb

@@ -36,6 +36,32 @@ describe WorkOS::UserManagement do
           'edit%22%7D&provider=authkit',
         )
       end
+
+      context 'with provider_scopes' do
+        it 'returns a valid authorization URL that includes provider_scopes' do
+          url = WorkOS::UserManagement.authorization_url(
+            provider: 'GoogleOAuth',
+            provider_scopes: %w[custom-scope-1 custom-scope-2],
+            client_id: 'workos-proj-123',
+            redirect_uri: 'foo.com/auth/callback',
+            state: {
+              next_page: '/dashboard/edit',
+            }.to_s,
+          )
+
+          expect(url).to eq(
+            'https://api.workos.com/user_management/authorize?' \
+            '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' \
+            '&provider=GoogleOAuth' \
+            '&provider_scopes=custom-scope-1' \
+            '&provider_scopes=custom-scope-2',
+          )
+        end
+      end
     end
 
     context 'with a connection selector' do
@@ -453,6 +479,40 @@ describe WorkOS::UserManagement do
         end
       end
 
+      context 'when oauth_tokens is present in the api response' do
+        it 'returns an oauth_tokens object' do
+          VCR.use_cassette('user_management/authenticate_with_code/valid_with_oauth_tokens') do
+            authentication_response = WorkOS::UserManagement.authenticate_with_code(
+              code: '01H93ZZHA0JBHFJH9RR11S83YN',
+              client_id: 'client_123',
+              ip_address: '200.240.210.16',
+              user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/108.0.0.0 Safari/537.36',
+            )
+
+            expect(authentication_response.oauth_tokens).to be_a(WorkOS::OAuthTokens)
+            expect(authentication_response.oauth_tokens.access_token).to eq('oauth_access_token')
+            expect(authentication_response.oauth_tokens.refresh_token).to eq('oauth_refresh_token')
+            expect(authentication_response.oauth_tokens.scopes).to eq(%w[read write])
+            expect(authentication_response.oauth_tokens.expires_at).to eq(1_234_567_890)
+          end
+        end
+      end
+
+      context 'when oauth_tokens is not present in the api response' do
+        it 'returns nil oauth_tokens' do
+          VCR.use_cassette('user_management/authenticate_with_code/valid') do
+            authentication_response = WorkOS::UserManagement.authenticate_with_code(
+              code: '01H93ZZHA0JBHFJH9RR11S83YN',
+              client_id: 'client_123',
+              ip_address: '200.240.210.16',
+              user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/108.0.0.0 Safari/537.36',
+            )
+
+            expect(authentication_response.oauth_tokens).to be_nil
+          end
+        end
+      end
+
       context 'when the user is being impersonated' do
         it 'contains the impersonator metadata' do
           VCR.use_cassette('user_management/authenticate_with_code/valid_with_impersonator') do

data/spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid_with_oauth_tokens.yml

@@ -0,0 +1,82 @@
+---
+http_interactions:
+  - request:
+      method: post
+      uri: https://api.workos.com/user_management/authenticate
+      body:
+        encoding: UTF-8
+        string:
+          '{"code":"01H93ZZHA0JBHFJH9RR11S83YN","client_id":"client_123","client_secret":"<API_KEY>","ip_address":"200.240.210.16","user_agent":"Mozilla/5.0
+          (Macintosh; Intel Mac OS X 10_15_7) Chrome/108.0.0.0 Safari/537.36","grant_type":"authorization_code"}'
+      headers:
+        Content-Type:
+          - application/json
+        Accept-Encoding:
+          - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+        Accept:
+          - "*/*"
+        User-Agent:
+          - WorkOS; ruby/3.0.2; arm64-darwin21; v2.16.0
+    response:
+      status:
+        code: 200
+        message: OK
+      headers:
+        Date:
+          - Wed, 30 Aug 2023 19:51:51 GMT
+        Content-Type:
+          - application/json; charset=utf-8
+        Transfer-Encoding:
+          - chunked
+        Connection:
+          - keep-alive
+        Cf-Ray:
+          - 7fef921deeca091f-SEA
+        Cf-Cache-Status:
+          - DYNAMIC
+        Etag:
+          - W/"13b-pHataL1lHEvsW5EO4vq5QgAdcWw"
+        Strict-Transport-Security:
+          - max-age=15552000; includeSubDomains
+        Vary:
+          - Origin, Accept-Encoding
+        Via:
+          - 1.1 spaces-router (devel)
+        Access-Control-Allow-Credentials:
+          - "true"
+        Content-Security-Policy:
+          - "default-src 'self';base-uri 'self';block-all-mixed-content;font-src 'self'
+            https: data:;frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src
+            'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"
+        Expect-Ct:
+          - max-age=0
+        Referrer-Policy:
+          - no-referrer
+        X-Content-Type-Options:
+          - nosniff
+        X-Dns-Prefetch-Control:
+          - "off"
+        X-Download-Options:
+          - noopen
+        X-Frame-Options:
+          - SAMEORIGIN
+        X-Permitted-Cross-Domain-Policies:
+          - none
+        X-Request-Id:
+          - 630bec5a-5a13-4311-a0b7-958889a3bbb2
+        X-Xss-Protection:
+          - "0"
+        Set-Cookie:
+          - __cf_bm=o5KBdIAUFZp0azSQnnd1GlQcIlcPCz95uFg6hFNnKM8-1693425111-0-ARSauqdojZdKD6Z7vp12JBrxCp6wE1s0JzEhaN0XE2DqME76OnJiDJugj2TsbNGXtqWaH3By7XHUXVZDf+AdFxU=;
+            path=/; expires=Wed, 30-Aug-23 20:21:51 GMT; domain=.workos.com; HttpOnly;
+            Secure; SameSite=None
+          - __cfruid=3e9a5d359ba92753e7626245fef8b2f1ee096477-1693425111; path=/; domain=.workos.com;
+            HttpOnly; Secure; SameSite=None
+        Server:
+          - cloudflare
+      body:
+        encoding: ASCII-8BIT
+        string: '{"user":{"object":"user","id":"user_01H93ZY4F80YZRRS6N59Z2HFVS","email":"test@workos.app","email_verified":false,"first_name":"Lucille","last_name":"Bluth","created_at":"2023-08-30T19:50:13.214Z","updated_at":"2023-08-30T19:50:13.214Z","user_type":"managed","sso_profile_id":"prof_01H93ZTVWYPAT4RKDSPFPPXH0J"},"access_token":"<ACCESS_TOKEN>","refresh_token":"<REFRESH_TOKEN>","oauth_tokens":{"access_token":"oauth_access_token","refresh_token":"oauth_refresh_token","scopes":["read","write"],"expires_at":1234567890}}'
+      http_version:
+    recorded_at: Wed, 30 Aug 2023 19:51:51 GMT
+recorded_with: VCR 5.0.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workos
 version: !ruby/object:Gem::Version
-  version: 5.18.0
+  version: 5.20.0
 platform: ruby
 authors:
 - WorkOS
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-22 00:00:00.000000000 Z
+date: 2025-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: encryptor
@@ -158,6 +158,7 @@ files:
 - lib/workos/invitation.rb
 - lib/workos/magic_auth.rb
 - lib/workos/mfa.rb
+- lib/workos/oauth_tokens.rb
 - lib/workos/organization.rb
 - lib/workos/organization_membership.rb
 - lib/workos/organizations.rb
@@ -300,6 +301,7 @@ files:
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/invalid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid_with_impersonator.yml
+- spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid_with_oauth_tokens.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_email_verification/invalid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_email_verification/valid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_magic_auth/invalid.yml
@@ -523,6 +525,7 @@ test_files:
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/invalid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid_with_impersonator.yml
+- spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_code/valid_with_oauth_tokens.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_email_verification/invalid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_email_verification/valid.yml
 - spec/support/fixtures/vcr_cassettes/user_management/authenticate_with_magic_auth/invalid.yml