Add providerScopes and oauthTokens support to SSO API (#1345)

## Summary
- Add `providerScopes` parameter to SSO authorization URL options
- Add `oauthTokens` field to SSO profile and token responses
- Comprehensive test coverage for new functionality

## Changes Made
- Updated `SSOAuthorizationURLOptions` interface to include optional
`providerScopes` parameter
- Modified `getAuthorizationUrl` method to serialize provider scopes as
space-separated string
- Added `oauthTokens` field to `ProfileAndToken` and
`ProfileAndTokenResponse` interfaces
- Updated profile and token serializer to handle oauth tokens
deserialization
- Added tests for provider scopes in authorization URLs
- Added tests for oauth tokens in profile responses

## Test Plan
- [x] All existing tests pass
- [x] New tests added for provider scopes functionality
- [x] New tests added for oauth tokens functionality
- [x] Linter passes
- [x] TypeScript compilation successful

Related to ENT-3768

Author: jonatascastro12

src/sso/interfaces/authorization-url-options.interface.ts

@@ -10,6 +10,7 @@ export interface SSOAuthorizationURLOptions {
   domainHint?: string;
   loginHint?: string;
   provider?: string;
+  providerScopes?: string[];
   redirectUri: string;
   state?: string;
 }

src/sso/interfaces/profile-and-token.interface.ts

@@ -1,14 +1,20 @@
 import { UnknownRecord } from '../../common/interfaces/unknown-record.interface';
+import {
+  OauthTokens,
+  OauthTokensResponse,
+} from '../../user-management/interfaces/oauth-tokens.interface';
 import { Profile, ProfileResponse } from './profile.interface';
 
 export interface ProfileAndToken<CustomAttributesType extends UnknownRecord> {
   accessToken: string;
   profile: Profile<CustomAttributesType>;
+  oauthTokens?: OauthTokens;
 }
 
 export interface ProfileAndTokenResponse<
   CustomAttributesType extends UnknownRecord,
 > {
   access_token: string;
   profile: ProfileResponse<CustomAttributesType>;
+  oauth_tokens?: OauthTokensResponse;
 }

src/sso/serializers/profile-and-token.serializer.ts

@@ -1,4 +1,5 @@
 import { UnknownRecord } from '../../common/interfaces/unknown-record.interface';
+import { deserializeOauthTokens } from '../../user-management/serializers/oauth-tokens.serializer';
 import { ProfileAndToken, ProfileAndTokenResponse } from '../interfaces';
 import { deserializeProfile } from './profile.serializer';
 
@@ -9,4 +10,5 @@ export const deserializeProfileAndToken = <
 ): ProfileAndToken<CustomAttributesType> => ({
   accessToken: profileAndToken.access_token,
   profile: deserializeProfile(profileAndToken.profile),
+  oauthTokens: deserializeOauthTokens(profileAndToken.oauth_tokens),
 });

src/sso/sso.spec.ts

@@ -193,6 +193,38 @@ describe('SSO', () => {
           );
         });
       });
+
+      describe('with providerScopes', () => {
+        it('generates an authorize url with the provided provider scopes', () => {
+          const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+
+          const url = workos.sso.getAuthorizationUrl({
+            provider: 'Google',
+            providerScopes: ['profile', 'email', 'calendar'],
+            clientId: 'proj_123',
+            redirectUri: 'example.com/sso/workos/callback',
+          });
+
+          expect(url).toMatchInlineSnapshot(
+            `"https://api.workos.com/sso/authorize?client_id=proj_123&provider=Google&provider_scopes=profile+email+calendar&redirect_uri=example.com%2Fsso%2Fworkos%2Fcallback&response_type=code"`,
+          );
+        });
+
+        it('handles empty provider scopes array', () => {
+          const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+
+          const url = workos.sso.getAuthorizationUrl({
+            provider: 'Google',
+            providerScopes: [],
+            clientId: 'proj_123',
+            redirectUri: 'example.com/sso/workos/callback',
+          });
+
+          expect(url).toMatchInlineSnapshot(
+            `"https://api.workos.com/sso/authorize?client_id=proj_123&provider=Google&redirect_uri=example.com%2Fsso%2Fworkos%2Fcallback&response_type=code"`,
+          );
+        });
+      });
     });
 
     describe('getProfileAndToken', () => {
@@ -280,6 +312,97 @@ describe('SSO', () => {
           expect(profile).toMatchSnapshot();
         });
       });
+
+      describe('with oauth tokens in the response', () => {
+        it('returns the oauth tokens from the profile and token response', async () => {
+          fetchOnce({
+            access_token: '01DMEK0J53CVMC32CK5SE0KZ8Q',
+            profile: {
+              id: 'prof_123',
+              idp_id: '123',
+              organization_id: 'org_123',
+              connection_id: 'conn_123',
+              connection_type: 'OktaSAML',
+              email: '[email protected]',
+              first_name: 'foo',
+              last_name: 'bar',
+              role: {
+                slug: 'admin',
+              },
+              groups: ['Admins', 'Developers'],
+              raw_attributes: {
+                email: '[email protected]',
+                first_name: 'foo',
+                last_name: 'bar',
+                groups: ['Admins', 'Developers'],
+              },
+              custom_attributes: {},
+            },
+            oauth_tokens: {
+              access_token: 'oauth_access_token',
+              refresh_token: 'oauth_refresh_token',
+              expires_at: 1640995200,
+              scopes: ['profile', 'email'],
+            },
+          });
+
+          const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+          const { accessToken, profile, oauthTokens } =
+            await workos.sso.getProfileAndToken({
+              code: 'authorization_code',
+              clientId: 'proj_123',
+            });
+
+          expect(fetch.mock.calls.length).toEqual(1);
+          expect(accessToken).toBe('01DMEK0J53CVMC32CK5SE0KZ8Q');
+          expect(profile).toBeDefined();
+          expect(oauthTokens).toEqual({
+            accessToken: 'oauth_access_token',
+            refreshToken: 'oauth_refresh_token',
+            expiresAt: 1640995200,
+            scopes: ['profile', 'email'],
+          });
+        });
+      });
+
+      describe('without oauth tokens in the response', () => {
+        it('returns undefined for oauth tokens when not present in response', async () => {
+          fetchOnce({
+            access_token: '01DMEK0J53CVMC32CK5SE0KZ8Q',
+            profile: {
+              id: 'prof_123',
+              idp_id: '123',
+              organization_id: 'org_123',
+              connection_id: 'conn_123',
+              connection_type: 'OktaSAML',
+              email: '[email protected]',
+              first_name: 'foo',
+              last_name: 'bar',
+              role: {
+                slug: 'admin',
+              },
+              raw_attributes: {
+                email: '[email protected]',
+                first_name: 'foo',
+                last_name: 'bar',
+              },
+              custom_attributes: {},
+            },
+          });
+
+          const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+          const { accessToken, profile, oauthTokens } =
+            await workos.sso.getProfileAndToken({
+              code: 'authorization_code',
+              clientId: 'proj_123',
+            });
+
+          expect(fetch.mock.calls.length).toEqual(1);
+          expect(accessToken).toBe('01DMEK0J53CVMC32CK5SE0KZ8Q');
+          expect(profile).toBeDefined();
+          expect(oauthTokens).toBeUndefined();
+        });
+      });
     });
 
     describe('getProfile', () => {

src/sso/sso.ts

@@ -71,6 +71,7 @@ export class SSO {
     loginHint,
     organization,
     provider,
+    providerScopes,
     redirectUri,
     state,
   }: SSOAuthorizationURLOptions): string {
@@ -93,6 +94,7 @@ export class SSO {
       domain_hint: domainHint,
       login_hint: loginHint,
       provider,
+      provider_scopes: providerScopes?.join(' '),
       client_id: clientId,
       redirect_uri: redirectUri,
       response_type: 'code',