Introduction

Disclaimer: This README is provisional and still very incomplete.

This package is a thin wrapper over the oauth2 package to make it easier to implement OpenID authentication.

It does not assume any particular authentication provider. In theory it can be used with pretty much any OpenID provider. It has been tested with Keycloak and Microsoft Entra.

The Authenticator class drives the workflow. This class is implemented assuming that it will be used as a singleton. It implements the code authentication workflow with PKCE for public clients. The process works in the following steps:

1. The first method to be called is the login() method. It starts by creating and storing a code verifier and then using the the url_launcher package to use the browser to present the identity provider's interface.
2. When the identity provider is finished identifying the user, it needs to redirect the user back to the app:

• For web applications, the user is redirected to the application's URL at a specific sign-in callback endpoint.
• For mobile applications to be called back via an URL, they need deep linking.
• For desktop apps, Authenticator provides a callback server, that listens to localhost only, and that can be hosted just to receive callback requests from the external browser.

3. When the app is called back (bring your implementation), it needs to call Authenticator.complete() to complete the authentication process. This method expects the url used by the identity provider to callback into the app. It then trades the authorization code given by the provider plus the code verifier generated in the first step for the user's credentials, including a JWT and possibly a refresh token.
4. Authenticator also provides a getUpdatedCredentials() method, which receives the credentials and checks if they're still valid. If so, that method is just a no-op and returns the passed credentials. Otherwise, if they are close to expiry or already expired and if the credentials include a refresh token, it tries to get new credentials from the identity provider. It will return the refreshed credentials.