OAuth Support for refreshing tokens given an access and refresh token

[jeffosmith]

We have an application that using background downloader to upload images in the background, as part of completing a large process based submission. The service is using OAuth with JWTs to manage the Authentication and Authorization of the upload requests. We are seeing instances of the access token expiring between when we create the task (and set the Auth Header) and when the task happens.

Would love to be able to provide, access token, refresh token and token refresh endpoint to allow the token to be refreshed if the current access token expires.

Have attempted to update the access token, just before creating the task, and although this reduces the error, it doesn't eliminate it.

I'm willing to put together a PR across both platforms, although mindful that I don't want to complicate your API too much, and question whether we can make it generic enough to update the token for a wide enough audience to make it worth while.

[781flyingdutchman]

Hi, thanks for raising this issue and for offering to help solve for this use case. As you mention, it is a bit niche and difficult to generalize, so I propose the following conditions before committing to including this:

1. It needs to apply to a reasonably large group of OAuth/JWT use cases, This means that the authentication needs to be configurable (e.g. different end points, different names of the header or url structure). I think this is doable, but it is more work than just solving for your specific use case
2. It needs to work on Android, iOS and Desktop (desktop is pure Dart code), and because I am not familiar with OAuth you will have to implement on all three platforms, as it needs to be a feature that is consistent across
3. No new dependencies, especially on iOS and Android, as that code is not tree-shaken so lives with every use of the package

If you think you can meet these conditions, then I would love for you to implement this, and, knowing the downloader code base, have a few suggestions for how to approach it:

1. Create a new Auth class in models.dart that contains the basic data for the auth/token request, e.g. the auth and refresh tokens themselves, as well as the string representation of the urls for re-authentication and for adding authentication to the url or headers. This class must have a toJson and fromJson (manual, not using JsonSerializable). You will also need to create this class in iOS and Android, where serialization is automated
2. In this Auth class, use templates to allow the user to put the token in the tight place, e.g. allow a string to contain {token} which will be replaced by the actual token upon execution. See how this is done for notifications, where you can for example insert the filename in the notification text. This bit requires some thought, as there are likely many different ways the token can be included in the request, and it is important that the structure you propose can represent those different ways
3. Add an auth field to the Request class: this is the base class for Task and ideally this would work also for Request (it's the same logic), and modify toJson and fromJson so that this field is passed to the native/desktop download code. on iOS and Android you need to add that same auth field to the Task struct and class
4. On desktop, iOS and Android there is a point in the code where the actual HTTP request is constructed (e.g. adding headers etc). Just before this happens, you should check if the task has an auth field, and if so, this is where you do your special handling, that should result in a proper request being constructed (with the auth headers as needed, but in such a way that all the other options are also still possible, e.g. the user may supply other headers and may set WiFi requirements etc - you should not duplicate that code, just create a starting point that already has the right authentication things included, then let the rest of the code that's already there do the other stuff). That ensures that all of the following code (for all task types) uses that request, now guaranteed to have a valid token
5. In your special handling, check for expiration of the auth token and refresh if needed, then construct the request (or just the url and headers, you'll have to determine what is easiest) based in the information in the task's auth object. This is where you would substitute {token} etc.

Let me know what you think.

[kuhnroyal]

I have the exact same use-case and was gonna create a ticket for this :)

Wondering if this would be easier by providing some kind of token resolver on the Dart side, not sure if the plugin could launch a Dart VM and execute the resolver even if the app is suspended.

CC @lyio

[781flyingdutchman]

I believe it's possible to launch a Dart VM from the background, but it is complicated and resource intense, so I believe this should be handled on the native side so that a background task can remain fully in the background.

[jeffosmith]

I think the approach outlined looks solid, let me have a review of some other OAuth libraries, to get a feel for the different approaches for refreshing tokens, and how those requests are formatted, query param, post body etc.

I'll add some notes here, once I'm clear on a generic approach for refreshing tokens

[781flyingdutchman]

I'm going to convert this to a discussion (instead of an issue) so it doesn't get labeled as stale by the bot.

[781flyingdutchman]

HI @jeffosmith , curious if you've been able to pursue this further?

[781flyingdutchman]

On branch callbacks I have implemented callbacks that are called before and after a task runs, and can be used to modify the task (e.g. update an auth token or url). This should allow for the functionality described here. I may implement a specific auth callback (doing some expiration math on the native side) but not sure yet.

From the (draft) readme:

OnTaskStart and OnTaskFinished "native" callbacks

For more complex situations you can use OnTaskStart and OnTaskFinished callbacks. This is only required if you need to - for example - refresh an expired auth token just before an enqueued task starts, or conditionally call your server to confirm an upload has finished successfully, which requires the callback to be called even when the main application has been suspended by the OS.
To add a callback to a Task, set its options property, e.g. to add an onTaskStart callback:

final task = DownloadTask(url: 'https://google.com',
   options: TaskOptions(onTaskStart: myStartCallback));

where myStartCallback must be a top level or static function.

For most situations, using the event listeners or registered "regular" callbacks is recommended, as they run in the normal application context on the main isolate. Native callbacks are called directly from native code (iOS, Android or Desktop) and therefore behave differently:

• Callbacks are called even when an application is suspended
• On iOS, the callbacks runs in the main isolate
• On Android, callbacks run in a shared background isolate, though there is no guarantee that every callback shares the same isolate as another callback
• On Desktop, callbacks run in the same isolate as the task, and every task has its own isolate

You should assume that the callback runs in an isolate, and has no access to application state or to plugins. Native callbacks are really only meant to perform simple "local" functions, operating only on the parameter passed into the callback function.

OnTaskStart

Callback with signatureFuture<Task?> Function(Task original), called just before the task starts executing. Your callback receives the original task about to start, and can modify this task if necessary (for example to refresh an auth token). If you make modifications, you return the modified task - otherwise return null to continue execution with the original task. You can only change the task's url (including query parameters) and headers properties - making changes to any other property may lead to undefined behavior.

OnTaskFinished

Callback with signature Future<void> Function(TaskStatusUpdate taskStatusUpdate), called when the task has reached a final state (regardless of outcome). Your callback receives the final TaskStatusUpdate and can act on that.

[781flyingdutchman]

Added an Auth mechanism using the same callback concept, on the auth branch of the repo until published. Would appreciate feedback on how this is working.

Authorization

The Auth object (which can be set as the auth property in TaskOptions) contains several properties that can optionally be set:

• accessToken: the token created by your auth mechanism to provide access. It is typically passed as part of a request in the Authorization header, but different mechanisms exist
• accessHeaders: the headers specific to authorization. In these headers, the template {accessToken} will be replaced by the actual accessToken property, so a common value would be {'Authorization': 'Bearer {accessToken}'
• accessQueryParams: the query parameters specific to authorization. In these headers, the template {accessToken} will be replaced by the actual accessToken property
• accessTokenExpiryTime: the time at which the accessToken will expire.
• refreshToken, refreshHeaders and refreshQueryParams are similar to those for access (and replace the {refreshToken} template)
• refreshUrl: url to use for refresh, including query parameters not related to the auth tokens
• onAuth: callback that will be called when token refresh is required

The downloader uses the auth object on the native side as follows:

• Just before the task starts, we check the accessTokenExpiryTime
• If it is close to this time, the downloader will call the onAuth callback (your code) to refresh the access token
  • A defaultOnAuth function is included that calls auth.refreshAccessToken using a common approach, but use your own onAuth callback if your auth mechanism differs
  • The Task returned by the onAuth call can change the Auth object itself (e.g. replace the accessToken with a refreshed one) and those values will be used to construct the task's request
• The Task request is built as follows:
  • Start with the headers and query parameters of the original task. You should have all headers and query parameters that are not related to authentication here
  • Add or replace every header and query parameter from the accessHeaders and accessQueryParams to the task's headers and query parameters, substituting the templates for accessToken and refreshToken
  • Construct the task's server request using these merged headers and query parameters

A typical way to construct a task with authorization and default onAuth refresh approach then is:

final auth = Auth(
    accessToken: 'initialAccessToken',
    accessHeaders: {'Authorization': 'Bearer {accessToken}'},
    refreshToken: 'initialRefreshToken',
    refreshUrl: 'https://your.server/refresh_endpoint',
    accessTokenExpiryTime: DateTime.now()
            .add(const Duration(minutes: 10)), // typically extracted from token
    onAuth: defaultOnAuth // to use typical default callback
);
final task = DownloadTask(
    url: 'https://your.server/download_endpoint',
    urlQueryParameters: {'param1': 'value1'},
    headers: {'Header1': 'value2'},
    filename: 'my_file.txt',
    options: TaskOptions(auth: auth));

[781flyingdutchman]

Published in V8.9.0