-
Notifications
You must be signed in to change notification settings - Fork 533
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Documentation] Amplifying refreshFn
usage
#1357
Labels
docs
Documentation
Comments
related: #1213 We'll keep both issues opened to make sure details are covered in the documentation update. |
new session refresh section in docs: |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
When creating a new connection on JSForce, a parameter can be passed along to the connection options that reflects logic that refreshes a connection's access token when expiring.
In the case of using a JWT server-to-server OAuth flow, the existence of a refresh token is nullified as it cannot be used, thus it cannot be passed on to the connection instance for auto-refreshing from the library itself. Therefore it is obligatory to refresh the access token every now and then via the same flow.
There is little to none documentation about how the
refreshFn
function works, I've investigated on how the inner works for this function are inside the library so I thought I'd give a little more insight from my behalf on how I solved this for our organization facing this issue where our session would die out after the access token expired, causing a bad implementation of this function to cause issues similar #356.JWT OAuth Flow
Salesforce allows the usage of signed JWTs for authorizing users into an organization. In contrast of actual OAuth flows for users (such as username:password flows or clientId:clientSecret) this flow makes use of x509 certificate signed tokens to authorize access, while keeping scope permissions on the app's side. Documentation for this can be found here.
An integration for this type of authorization would be as follows (Typescript):
With a signed JWT following Salesforce's official documentation on the flow, one can send this token for Salesforce to authorize the request and return an access token.
This is a manual implementation for this call:
domain
is either the generic production or sandbox environment on Salesforce (https://login.salesforce.com
for production orhttps://test.salesforce.com
for sandbox). After a JWT is sent to Salesforce and authorized, a response from the API should be as seen in their documentation. If need be, access to JWT OAuth flow is detailed on top of the issue.JSForce Implementation
Once the
access_token
andinstance_url
is obtained from Salesforce, assigning it to the connection is as basic as passing it as a parameter as follows:This is fine for a short period of calls that need to be done on Salesforce, say a request scoped class is consuming this then it would authorize itself on each call. However, there may be use cases in which one would require for the connection to persist for as long the application is running, in our case for updates and service inter-connection.
The
refreshFn
FunctionIn this case, to refresh the session JSForce has a function parameter called
refreshFn
that exposes this functionality and allows one to override logic for token refreshing. It's functionality is hidden within the actual workings of the library, hence I wish to use this issue as an opportunity to amplify how it works and how to use it.Within the
Connection
declarations, one can find how this parameter operates.jsforce/lib/connection.js
Lines 155 to 163 in e011fc5
It checks for the existance of a custom function being passed on and declares it for internal usage to override it. If it is present, it is passed on to the custom wrapper for HTTP calls onto Salesforce for refreshing when needed. This is what the
SessionRefreshDelegate
method does:jsforce/lib/http-api.js
Lines 261 to 293 in e011fc5
It delegates token refreshing logic to whatever is defined inside the passed on function by reference, and interprets the result based on what the callback gives back onto its call. To put this into perspective, one would require to define asynchronous logic to ask for new tokens and resolve the callback with the resultant access token and emit the successful refresh.
Once a
refresh
event is emmited, the connection is stored again with its new parameters onto the same instance, thus providing an accesible refreshed connection from all consuming parts.jsforce/lib/cli/cli.js
Lines 143 to 146 in e011fc5
jsforce/lib/cli/cli.js
Lines 82 to 97 in e011fc5
An Implementation
To implement a persistent refreshing using this logic, an example implementation would be as follows:
Connection
instance to updateFollowing the signing process described above, the refreshing function would look like this:
Thus having the final
Connection
declaration passed on to any instance that requires it would be:The text was updated successfully, but these errors were encountered: