[GWS-3384] Implements automatic refresh and token management for system auth and company auth #7

azrosen92 · 2025-01-29T22:53:54Z

Makes the auth interface, including token management and refresh simpler.

Adds a custom pre request hook for fetching a new system access token
Creates a wrapper function instantiating the client with a custom security callback to handle refreshing and managing company auth access tokens.
Adds some open api overrides to support the new system access token auth.

Ticket: https://gustohq.atlassian.net/browse/GWS-3384

Testing in node console
First, apply these changes to your local branch to enable a local build (copy and then use pbpaste | git apply)

diff --git a/.speakeasy/workflow.yaml b/.speakeasy/workflow.yaml
index 2932a89..1e4936e 100644
--- a/.speakeasy/workflow.yaml
+++ b/.speakeasy/workflow.yaml
@@ -13,6 +13,14 @@ sources:
             - location: gusto_embedded/.speakeasy/speakeasy-modifications-overlay.yaml
         registry:
             location: registry.speakeasyapi.dev/gusto/ruby-sdk/gusto-embedded-oas
+    GustoEmbedded-local:
+        inputs:
+            - location: ../Gusto-Partner-API/generated/embedded/api.v2024-04-01.embedded.yaml
+        overlays:
+            - location: ../Gusto-Partner-API/.speakeasy/speakeasy-modifications-overlay.yaml
+            - location: gusto_embedded/.speakeasy/speakeasy-modifications-overlay.yaml
+        registry:
+            location: registry.speakeasyapi.dev/gusto/ruby-sdk/gusto-embedded-local
 targets:
     gusto-embedded:
         target: typescript
@@ -26,3 +34,14 @@ targets:
                 location: registry.speakeasyapi.dev/gusto/ruby-sdk/gusto-embedded-oas-typescript-code-samples
             labelOverride:
                 fixedValue: Typescript (SDK)
+            blocking: false
+    local:
+        target: typescript
+        source: GustoEmbedded-local
+        output: ./gusto_embedded
+        codeSamples:
+            registry:
+                location: registry.speakeasyapi.dev/gusto/ruby-sdk/gusto-embedded-oas-typescript-code-samples
+            labelOverride:
+                fixedValue: Typescript (SDK)
+            blocking: false

Generate code locally using speakeasy run --target=local

Import the generated library as a linked dependency into a node project (I like to use embedded-react-sdk). npm link --save ../gusto-typescript-client/gusto_embedded

open a node console in the node project's directory

Then try to initialize the client and start making requests.

You can test out the token refresh logic by instantiating CompanyAuthenticatedClient with serverURL: "http://api.gusto-dev.com:3000" instead of server: "demo". Change ZP's access_token_expires_in configuration in config/initizializers/doorkeeper.rb to something like 30.seconds.

const { GustoEmbedded } = await import('@gusto/embedded-api')
const { CompanyAuthenticatedClient } = await import(
  "@gusto/embedded-api/CompanyAuthenticatedClient"
);

const c = new GustoEmbedded()

const response = await c.companies.createPartnerManaged({ 
  clientId: "<client_id>", 
  clientSecret: "<client_secret>" 
}, {
  requestBody: { 
    user: { 
      firstName: "", 
      lastName: "", 
      email: "" 
    }, 
    company: { 
      name: "" 
    }
  }
})

const { accessToken, refreshToken, companyUuid, expiresIn } = response.object;

const companyAuthClient = CompanyAuthenticatedClient({
    clientId,
    clientSecret,
    accessToken,
    refreshToken,
    expiresIn,
    options: {
      server: "demo",
    },
});

await companyAuthClient.companies.get({ companyId: companyUuid });

.speakeasy/workflow.yaml

azrosen92 · 2025-01-29T22:57:36Z

gusto_embedded/.genignore

@@ -0,0 +1 @@
+/src/hooks/clientcredentials.ts


This is an auto-generated hook created by speakeasy when any endpoint in the API is configured to use a type: oauth2 security scheme. We are adding it to .genignore because I had to modify the file to make the fetch token request with grant_type: system_access instead of grant_type: client_credentials, which is the standard for oauth. For now, this is our only option, but in the future we should update our backend to properly support the oauth client credentials flow.

gusto_embedded/src/companyAuth.ts

azrosen92 · 2025-01-29T23:02:54Z

gusto_embedded/src/companyAuth.ts

+  clientSecret: string,
+  accessToken: string,
+  refreshToken: string,
+  options: { tokenStore?: TokenStore; url?: string } = {}


We might want to consider making this non-optional. This is what allows the developer to hook into a data store that can store access/refresh token pairs whenever they are refreshed.

azrosen92 · 2025-03-13T19:50:28Z

gusto_embedded/.speakeasy/speakeasy-modifications-overlay.yaml

+    update:
+      type: http
+      scheme: custom
+      x-speakeasy-custom-security-scheme:


Overlays the SystemAccessAuth security scheme from our open api spec with a custom security scheme that takes a clientId and clientSecret as inputs. These are then used to fetch a system access token before each request, using the clientcredentials hooks.

azrosen92 · 2025-03-13T19:56:03Z

gusto_embedded/src/hooks/clientcredentials.ts

+  scopes: string[];
+};
+
+export class ClientCredentialsHook


Defines beforeRequest and afterError hooks.

beforeRequest – Retrieves a saved system access token from an in-memory session or creates a new system access token if there isn't a saved one. Sets this token in the authorization header.

afterError – deletes a saved token from the session if the server returns a 401, indicating that the token is no longer valid.

azrosen92 · 2025-03-13T19:56:58Z

gusto_embedded/src/hooks/registration.ts

 export function initHooks(hooks: Hooks) {
  // Add hooks by calling hooks.register{ClientInit/BeforeCreateRequest/BeforeRequest/AfterSuccess/AfterError}Hook
  // with an instance of a hook that implements that specific Hook interface
  // Hooks are registered per SDK instance, and are valid for the lifetime of the SDK instance
+  const presetHooks: Array<Hook> = [new ClientCredentialsHook()];


registers the beforeRequest and afterError hooks

…ith token refresh

rqsilva

I'm a bit rusty with TS so this admittedly isn't the most thorough review, but I left a few questions/comments and noted where I faced the most friction while testing.

Is it worth it to also add some test coverage here?

Don't want to block getting this out to Lattice, so I'm happy to approve in the meantime if you want to address the feedback in another PR

rqsilva · 2025-03-28T21:27:51Z

gusto_embedded/src/CompanyAuthenticatedClient.ts

+  if (serverURL) {
+    return `${serverURL}/oauth/token`;
+  }
+
+  if (url) {
+    return url;
+  }


curious why the need to support both serverURL and url?

Good call – the original implementation of this security callback that Speakeasy recommended is built in a way that consumers of the client can configure a separate auth server (the oauth spec doesn't specify that the auth server should be on the same domain as the rest of the API). However, since our implementation of oauth has the auth server on the same domain as the rest of the API, this probably isn't necessary. I'll consolidate to just allow one of these.

rqsilva · 2025-03-28T21:35:39Z

gusto_embedded/src/hooks/clientcredentials.ts

+type Session = {
+  credentials: Credentials;
+  token: string;
+  expiresAt?: number;


is this being optional to ensure support for something like a personal access token, which never expires?

I'm looking through the code and I'm not actually sure why I made this optional. But I think it would make sense to leave as optional for that exact case.

rqsilva · 2025-03-28T21:38:19Z

gusto_embedded/src/companyAuth.ts

+) {
+  const {
+    tokenStore = new InMemoryTokenStore(),
+    url = "https://api.gusto-demo.com/oauth/token",


should this (or at least the demo root) be stored as a constant in a separate file?

also is this hard coding the demo environment? (sorry, it's been a minute since I've looked at TS code 😅 )

yup, this is defaulting to the demo environment. We default to demo in a few other places, most importantly here. So I just wanted to make that behavior consistent for auth code. I'm also changing this to use

url = ServerList[ServerDemo],

You're right that we should be using a constant!

rqsilva · 2025-03-28T21:40:33Z

gusto_embedded/src/CompanyAuthenticatedClient.ts

+  options: TokenRefreshOptions & SDKOptions;
+};
+
+export function CompanyAuthenticatedClient({


are there plans to extend this to other token types? (essentially, will we offer this for system tokens as well?)

The clientcredentials.ts file in this PR handles fetching and refreshing system access tokens. Consumers of the library only have to pass in a clientId and clientSecret and the clientcredentials hooks will automatically fetch or refresh a system access token as needed.

This is relying on Speakeasy's concept of "hooks". clientcredentials.ts defines a beforeRequest hook, that checks for the existence of a system access token before the request and fetches one if one hasn't been generated yet. It also defines an afterError hook that checks for a 401 response code, then deletes the saved system access token so the user of the client library can retry the request and create a new system access token.

rqsilva · 2025-03-28T21:49:03Z

gusto_embedded/src/CompanyAuthenticatedClient.ts

+  });
+}
+
+function constructAuthUrl(


during my local testing, I didn't realize I had multiple options for setting the server url/env. Will partners using this SDK also be testing locally? If so, it might be worth it to improve that feedback loop.

Workarounds I tried to get it working locally:

setting server to local (raised an Uncaught TypeError: Invalid URL error)

not passing in options (raised an Uncaught: TypeError: Cannot destructure property 'server' of 'options' as it is undefined. error)

Not sure if setting a default "server" value here would be best, or if improving the error messages makes more sense. The error message might be preferable since it gives the dev more insight as to what's being executed

In practice, partners will not be testing against a local server, so I'm hesitant to index too much on the UX of the serverURL argument. Partners should be using the server argument (either 'demo' or 'prod'), which defaults to 'demo'. If nothing is passed in for server or serverURL the client should still work.

setting server to local

This should both be caught by the type checker. The server argument's type should be 'prod' | 'demo', so the type checker would not allow a value of 'local' and should guide the developer toward the two possible values.

not passing in options

Thanks for calling this out. The options argument was not optional in the type signature, but in practice you should be able to use the client without setting any of these values. I'll change it to be optional, and update the code to avoid this scenario when the user doesn't pass in anything for options.

In practice, partners will not be testing against a local server

Could you explain a little more about how this is to work between prod/non-prod environments? Is it expected that the partner uses this only in prod and in non-prod comes up with their own solution?

scally · 2025-03-31T19:39:11Z

gusto_embedded/README.md

+}
+
+const client = new GustoEmbedded();
+const clientId = process.env["GUSTOEMBEDDED_CLIENT_ID"]


If this module gets imported on the client, process.env will likely not be defined. What if we deferred this until a particular action is taken instead of making it happen in the module import?

scally · 2025-03-31T19:40:30Z

gusto_embedded/README.md

-const gustoEmbedded = new GustoEmbedded({
-  companyAccessAuth: process.env["GUSTOEMBEDDED_COMPANY_ACCESS_AUTH"] ?? "",
-});
+class PersistentTokenStore implements TokenStore {


Do we need to add some kind of documentation that this is insecure if you attempt to use it in the browser? Right now the SDK assumes it's running solely in the browser and not on the server. That's subject to change eventually but it might break some assumptions we currently make.

The reason I bring up the SDK here is that it ships this library, so whatever imports we add here have a chance of intentionally or unintentionally impacting the SDK

scally · 2025-03-31T19:43:16Z

gusto_embedded/src/companyAuth.ts

+ */
+export interface TokenStore {
+  get(): Promise<
+    { token: string; refreshToken: string; expires: number } | undefined


Since the tuple token, refreshToken, expires occurs together so often I wonder if making an interface/type for them would be appropriate. What do you think?

scally · 2025-03-31T19:44:22Z

gusto_embedded/src/hooks/clientcredentials.ts

+  }
+
+  private hasTokenExpired(expiresAt?: number): boolean {
+    return !expiresAt || Date.now() + 60000 > expiresAt;


What do you think about extracting the magic number 60000 into an explanatory constant?

scally · 2025-03-31T19:46:02Z

gusto_embedded/README.md

+    {
+      requestBody: {
+        user: {
+          firstName: "Frank",


What are the implications of using these hardcoded values for all partners?

scally · 2025-03-31T19:48:01Z

I am assuming that the purpose of this is to help partners who are already using NodeJS as their backend tech. Is that correct? Is there any guidance as to how to incorporate their own authentication system with this?

scally · 2025-03-31T19:51:45Z

gusto_embedded/src/companyAuth.ts

+}
+
+/**
+ * A TokenStore is used to save and retrieve OAuth tokens for use across SDK


This is a cool idea; I like that it's flexible enough to be agnostic about the store implementation

azrosen92 commented Jan 29, 2025

View reviewed changes

.speakeasy/workflow.yaml Outdated Show resolved Hide resolved

azrosen92 commented Jan 29, 2025

View reviewed changes

gusto_embedded/src/companyAuth.ts Outdated Show resolved Hide resolved

azrosen92 commented Jan 29, 2025

View reviewed changes

gusto_embedded/src/companyAuth.ts Outdated Show resolved Hide resolved

azrosen92 commented Jan 29, 2025

View reviewed changes

azrosen92 force-pushed the ar/add-oauth branch 2 times, most recently from eeb991b to 3b479aa Compare January 29, 2025 23:07

azrosen92 force-pushed the ar/add-oauth branch 2 times, most recently from c8d45d1 to 45704db Compare March 12, 2025 22:06

azrosen92 changed the title ~~Implements automatic refresh and token management for system auth and company auth~~ [GWS-3384] Implements automatic refresh and token management for system auth and company auth Mar 13, 2025

azrosen92 commented Mar 13, 2025

View reviewed changes

azrosen92 force-pushed the ar/add-oauth branch from 3a08668 to 7e4e12b Compare March 13, 2025 22:55

azrosen92 marked this pull request as ready for review March 13, 2025 23:03

azrosen92 requested a review from a team March 13, 2025 23:03

azrosen92 added 14 commits March 28, 2025 09:39

add auth.ts

5288c0d

adds source and target for generating code from local file

c882fdc

implement company auth with refresh

c973f0a

create company auth callback

4b12dd8

generated client credentials oauth flow code

bff2f93

remove autogenerated files

ddd76d2

renew system access token via pre-request hook

b56930f

undo generated code changes

b02a4d5

update clientcredentials hook

05d935f

create a wrapper function for instantiating a company auth'd client w…

e3b189b

…ith token refresh

Custom usage example for new token refresh wrapper functions

83b851b

fix bugs in token refresh, add tokenStore example

1022738

remove local workflow

27995bc

support custom http client

d41a9a5

azrosen92 force-pushed the ar/add-oauth branch from 664296d to d41a9a5 Compare March 28, 2025 15:39

rqsilva approved these changes Mar 28, 2025

View reviewed changes

PR feedback

7edf492

scally reviewed Mar 31, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[GWS-3384] Implements automatic refresh and token management for system auth and company auth #7

[GWS-3384] Implements automatic refresh and token management for system auth and company auth #7

azrosen92 commented Jan 29, 2025 •

edited

Loading

azrosen92 Jan 29, 2025

azrosen92 Jan 29, 2025

azrosen92 Mar 13, 2025

azrosen92 Mar 13, 2025

azrosen92 Mar 13, 2025

rqsilva left a comment

rqsilva Mar 28, 2025

azrosen92 Mar 31, 2025

rqsilva Mar 28, 2025

azrosen92 Mar 31, 2025

rqsilva Mar 28, 2025

rqsilva Mar 28, 2025

azrosen92 Mar 31, 2025

rqsilva Mar 28, 2025

azrosen92 Mar 31, 2025

rqsilva Mar 28, 2025 •

edited

Loading

azrosen92 Mar 31, 2025

scally Mar 31, 2025

scally Mar 31, 2025

scally Mar 31, 2025

scally Mar 31, 2025

scally Mar 31, 2025

scally Mar 31, 2025

scally Mar 31, 2025

scally commented Mar 31, 2025

scally Mar 31, 2025

		@@ -0,0 +1 @@
		/src/hooks/clientcredentials.ts

[GWS-3384] Implements automatic refresh and token management for system auth and company auth #7

Are you sure you want to change the base?

[GWS-3384] Implements automatic refresh and token management for system auth and company auth #7

Conversation

azrosen92 commented Jan 29, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rqsilva left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rqsilva Mar 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scally commented Mar 31, 2025

Choose a reason for hiding this comment

azrosen92 commented Jan 29, 2025 •

edited

Loading

rqsilva Mar 28, 2025 •

edited

Loading