Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Wallet Provider Authentication Refresh Service

See original GitHub issue

Wallet Provider Authentication Refresh Service

Overview

In order to resolve some issues around session management and improve syncing authentication session state between App <> FCL <> Wallet we are proposing the following Authentication Refresh Service. Since synchronization of a user’s session is important to provide a seamless user experience when using an app and transacting with the Flow Blockchain, a way to confirm, extend, and refresh this session should be provided by the wallet. This will allow FCL to keep app session state synched with wallet provider session state and gracefully handle expiration or failure.

Problem

Currently there is no way to know if a user’s wallet provider session has expired or ended for other reasons. This leads to a situation where a user who is logged in to an app initiates a transaction which fails silently and without any clear error. The user needs to reauthenticate, but the client (and FCL) are unaware. There is currently no way to query wallet user session state, or warn the app/user that their wallet session is invalid before initiating the transaction.

A solution to this issue should support synchronization between App <> FCL <> Wallet, and provide a standard means for the app to reauthenticate a user or inform them that their wallet session has expired. We have some thoughts on how this might work better and are interested in feedback.

Implementation

Wallet Providers integrate with FCL by providing implementations of various FCL services. For example, Authentication (Authn) Service, Authorization (Authz) Service, and User Signature Service. These services provide configuration and tell FCL how to talk to the wallet.

Details on current FCL Services for Wallet Developers can be found here along with supported Service Methods

Providers can include a new Authentication Refresh Service to FCL upon initial authentication. An Authentication Refresh Service should be included with an Authentication Approved PollingResponse and might look like:

  {
    f_type: "Service",                      // Its a service!
    f_vsn: "1.0.0",                         // Follows the v1.0.0 spec for the service
    type: "authn-refresh",                  // The type of service it is
    method: "HTTP/POST",                    // Back Channel
    endpoint: "authentication-refresh-url", // The authentication refresh endpoint
    uid: "awesome-wallet#authn-refresh",    // A unique identifier for the service
    id: "0xUSER",                           // the wallets internal id for the user or flow address
    data: {
      f_type: "authn-refresh",
      f_vsn: "1.0.0",
      address: "0xUSER",                    // The user's address with prefix
      // Additional data wallet 
      // needs to reauthenticate
      ...
    },                                      // will be included in the requests body
    params: { }                             // will be included in the requests url
  }

Here is an example using a WalletUtils to wrap an AuthnResponse in a PollingResponse. A detailed diagram of the HTTP/POST back channel communication flow can be found here.

import {WalletUtils} from "@onflow/fcl"

WalletUtils.approve({
  f_type: "AuthnResponse",
  f_vsn: "1.0.0"
  services: [                              // All the stuff that configures FCL
  // Authentication Service - REQUIRED
    {
      f_type: "Service",                   // Its a service!
      f_vsn: "1.0.0",                      // Follows the v1.0.0 spec for the service
      type: "authn",                       // the type of service it is
      ...
    },
  // Authentication Refresh Service
  {
    f_type: "Service",                      // Its a service!
    f_vsn: "1.0.0",                         // Follows the v1.0.0 spec for the service
    type: "authn-refresh",                  // The type of service it is
    method: "HTTP/POST",                    // Back Channel
    endpoint: "authentication-refresh-url", // The authentication refresh endpoint
    uid: "awesome-wallet#authn-refresh",    // A unique identifier for the service
    id: "0xUSER",                           // the wallets internal id for the user or flow address
    data: {
      f_type: "authn-refresh",
      f_vsn: "1.0.0",
      address: "0xUSER",                    // The user's address with prefix
    },                                      // will be included in the requests body
    params: { }                             // will be included in the requests url
  },
  /// Additional Services
  ...
  ]
})

FCL will use the service and method provided to request updated authentication data from the Authentication Refresh Service. The Authentication Refresh Service receives data needed to identify the user via the request body. The service is expected to reauthenticate the user or prompt for approval if required. Updated authentication information (user data and services) are sent back to FCL as part of an AuthnResponse in the data property of a PollingResponse.

The eventual response back from the Authentication Refresh Service should look something like the AuthnResponse shown above.

If FCL receives back an APPROVED PollingResponse including AuthnResponse data, it rebuilds the local currentUser with updated data and services and the Authentication Refresh process is complete. The initial transaction can then be executed with confidence the user session is valid.

Expected Outcomes

An FCL compatible wallet or service provider will include an authn-refresh service with user data and services after successfull authentication. This service should include any data necessary to confirm a user’s identity and refresh their session or trigger reauthentication.
An FCL compatible wallet or service provider will return informative errors when a user’s session is expired or invalid or a transaction fails or is declined by the wallet due to an expired or invalid session. This will allow the application to gracefully handle transaction failures in situations where a user session is invalid and an Authentication Refresh Service is not configured.
If an authn-refresh service is provided FCL will execute the service before attempting to authorize a transaction and upon receiving new session data, update currentUser session data stored locally.