add support for provider_query_params option on getAuthorizationUrl

[stacurry]

Description

• moves to using qs to create query strings for getAuthorizationUrl to more easily support a new object type parameter and stringify it into the format our API expects
  • we have lots of tests for getAuthorizationUrl (sso and user_management) that compare full url strings to snapshots, so the fact that all of these tests still pass (with qs options set to maintain backwards compatibility with our previous implementation) makes this feel pretty safe to me, but if anyone disagrees, let me know
• adds support for the new provider_query_params query parameter / option added in https://github.com/workos/workos/pull/41556

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Summary

This PR adds support for a new provider_query_params option in the getAuthorizationUrl method, allowing developers to pass additional query parameters to identity providers during the authorization flow. The implementation replaces the existing URL parameter handling with the qs library to better support complex object parameters while maintaining backward compatibility.

Key changes:

• Added providerQueryParams option to UserManagementAuthorizationURLOptions interface
• Switched to qs library (v6.14.0) for query string generation
• Refactored toQueryString function to use qs.stringify with specific options to maintain backward compatibility
• Added comprehensive test coverage for the new feature

The change is well-tested through existing snapshot tests that verify URL generation remains consistent with previous behavior.

Confidence score: 4/5

1. This PR is safe to merge with normal review attention
2. Score of 4 given due to solid test coverage and backward compatibility, with minor concern about potential edge cases in query parameter handling
3. Files needing attention:
   • src/user-management/user-management.ts - Verify qs.stringify options are correctly configured
   • src/user-management/interfaces/authorization-url-options.interface.ts - Ensure type constraints are appropriate for provider parameters

_{4 files reviewed, 1 comment
Edit PR Review Bot Settings | Greptile}

[greptile-apps]

style: Consider adding JSDoc comment explaining the purpose and expected format of providerQueryParams, similar to the context param above

[jonatascastro12]

I'd avoid adding the new package qs here if it's possible to use the native URLSearchParams (to avoid extra packages installed in the SDK).

[stacurry]

the native URLSearchParams doesn't have good support for array or object parameters, like provider_scopes and now provider_query_params. writing our own logic for array params was ok, but I was worried about missing edge cases if we tried to write our own logic to handle objects so I thought this was worth the added dependency.

[MTG2000]

Hey @stacurry

Not sure if this is a bug or not, but I noticed that after updating to this version, the authorization urls generated with a query parameter with undefined value are now resulting in broken urls.

So generating a url previously like this:

workos.userManagement.getAuthorizationUrl({
      provider: 'authkit',
      clientId: this.clientId,
      redirectUri: callbackUrl,
      state: options.state,
      screenHint: undefined,
    })

Would result in a url like this: (where the screenHint param has been removed)

https://api.workos.com/user_management/authorize?client_id=client_0000&provider=authkit&redirect_uri=https%3A%2F%2Fapp.something.com%2F_auth%2Fcallback&response_type=code

Whereas now, the same call would return this URL: (note the empty screen_hint at the end)

https://api.workos.com/user_management/authorize?client_id=client_000&provider=authkit&redirect_uri=https%3A%2F%2Fapp.something.com%2F_auth%2Fcallback&response_type=code&screen_hint=

Which results in an error page.

I fixed it temporarily by conditionally passing the screenHint value,

workos.userManagement.getAuthorizationUrl({
      provider: 'authkit',
      clientId: this.clientId,
      redirectUri: callbackUrl,
      ...(options.state && {
        state: options.state,
      }),
      ...(options.signInType && {
        screenHint: options.signInType,
      }),
    })

But if this new behaviour is intended, it should have been marked as a breaking change I think.

[stacurry]

Hi @MTG2000 thanks for reporting this. I haven't been able to reproduce and I added a test that seems to cover this case here: #1322. I'm seeing it exclude screen_hint from the authorization URL when the screenHint option is undefined. Are you still seeing this?

[MTG2000]

Yeah, my bad.

The value that was getting passed was null instead of undefined
It worked in the previous version because it was doing a truthy check before including the value or not, so it didn't matter whether it was null or undefined. But qs treats null & undefined differently, hence the issue.

I fixed it in my code to ensure that only undefined is passed when there's no value/null/undefined.

Thanks for checking this out.