Proposed solutions for desktop safari & firefox sign in

We currently use blockstack: custom protocol handler to communicate between an app requesting user authentication and the authenticator tool that the user has selected. If you’ve installed Blockstack for macOS, Windows or Linux, the software installs the blockstack: handler and redirects requests to a locally served copy of the Blockstack Browser typically running on http://localhost:8888.

We attempt to detect if your computer supports the blockstack: protocol handler and if it does not, direct you to the copy of the Blockstack Browser that we host at

Web browsers do not generally have support for detecting whether or not a user’s computer supports a given custom protocol handler. On Chrome, we use a library that detects some side effects of support for the protocol handler while on Firefox and Safari, users who haven’t installed Blockstack simply see errors such as the following:

This problem also existed on mobile devices, however, we worked around it by always redirecting mobile browsers to

On desktop, we have existing users whose apps would stop working without identity migration if we took a similar approach on desktop. We also have apps with users that would be uncomfortable storing their private keys on an origin that Blockstack PBC controls instead of one that they control.

This thread is meant to be a discussion around potential solutions to this problem.

Idea 1: Redirect except for whitelisted legacy apps

Create a whitelist consisting of existing apps in blockstack.js that would continue to have the current behavior. All other apps would redirect to

If a user wants to override this behavior, they can create a browser extension or separate browser app that intercepts this call and redirects it to their own authenticator.

Idea 2: User decides on first sign in

Add functionality to blockstack.js that creates a modal or popup on affected browsers that asks users if they’ve installed the native browser. If they have, use the custom protocol handler, if not redirect to Remember their choice in localstorage of the app.

Idea 3: Install web extension to keep using native

Modify blockstack.js to redirect all users to Offer a simple web extension that intercepts this request and redirects it to the localhost hosted versions for users that prefer to use that.

Please post your ideas and thoughts below!


I like this option best, because it doesn’t require any additional work from the user (option 3), and it doesn’t prohibit users from easily using the native/local browser (option 1).


I like idea 2 as well. One thing that the protocol handler enables is community implementations of a Blockstack authenticator. So I’m in favour of keeping it.


I am also for the second option as the custom protocol is exactly made for this.

For Firefox and Chrome web-based protocol handler browser APIs should be part of the solution? See caniuse for the current support.

If we assume the users are onboarding to blockstack through then the user has already a custom protocol handler installed when visiting the first app. If the local browser is installed then the user usually gets a popup to choose from the web app or local apps.


This might work as a specific solution for the desktop versions of those two browsers. We tried the web-based protocols last year and found that they didn’t work the same way in Chrome as they did in Firefox and instead decided to try to use something that would work the same on all browsers and most importantly would work on mobile.

Is the intention that in the future mobile will have a set of native apps too in order to address the origin concern for private keys? It sounds like it applies there too.
Which of the ideas could be made to work on mobile?

1 Like

@zone117x has been making progress recently on protocol handling per this thread.

He’s produced a prototype here that’d be great for you all to try out:

While I also like @larry’s “Idea 2”, it appears that @zone117x is taking another stab at automatic detection of local vs. hosted browser support. Let’s see if we pull it off better this time!

For reference, I’ve also labeled all the issues I see related to protocol handling for blockstack.js: I’m hoping we can resolve all of these soon.

I think issues with the current prototype would be mostly alleviated by combining it with @larry’s idea number 2. We attempt to perform the protocol handler launch using this new method, and if not detected, rather than redirecting to http ls auth immediately, we prompt the user to choose https auth or install the browser.

I need some UX input on the new protocol handler proposal. I think this is a reliable fix for the vast majority of reports about completely broken Blockstack login experiences, but during testing I’ve found one critical flaw with this approach, and the fix requires a minor auth UX change.

Here is the PR or the new approach with the technical details:

The behavior to note here is:

If something prevents the protocol handler from pinging back to the web app before the timeout (like an “Open Blockstack?” browser prompt or just slow computer) then the original tab will redirect to the https auth. This could also be considered good behavior that makes this approach more resilient, since in the situation of some unknown failure condition, the user auth flow will still be able to progress. And in the case of this false-positive (where the redirect happens even though protocol handler did launch) that original tab was already useless anyway with the current approach.

The problem: All web browsers show a prompt the first time when a custom protocol app is about to be launched, something like “Do you want to open Blockstack?“, and an option for “remember” or "always”. This is usually okay, however, all chromium-based browsers (Chrome, Opera, Brave) show this browser prompt, but will automatically close the prompt if the window URL is changed / redirected. The protocol handler detection timeout redirect is set to 2000ms right now, and so this time easily elapses before the user can read the prompt and select an answer. Resulting in a the window URL changing and the “Open Blockstack?” prompt confusingly disappearing.

Quick screen capture of the problem:

The solution: combine this new approach with the choice modal that has been proposed by Larry (his idea #2 in the original post above). So instead of performing a redirect to the https login, we show a modal with options something like “A) Click here to login through, or B) click here to install the Blockstack Browser” (needs word-smithed). This in-page modal avoids a redirect and prevents the browser prompt from being closed.

Adding this modal has these effects on the following types of user interactions:

  • User does not have the Blockstack Browser installed: they click login w/ Blockstack, a second later a modal pops up and they have to make one additional click to login with our https site (slight decrease in UX for them). On the upside, it gives us a chance to advertise the second option of installing the Blockstack Browser (we want users to do that anyway right?)
  • User just installed Blockstack Browser for first time: they click login w/ Blockstack, a browser prompt shows “Open Blockstack?”, the user probably takes a couple seconds to click “Yes”, and there is some noise in the background where the modal is shown. They click “yes” on the browser prompt and immediately end up in a new tab where they login - and just like the existing method, they ignore the original tab.
  • User has Blockstack Browser installed has already clicked “always” on browser prompt: they click login w/ Blockstack and it magically works with no downsides at all.

A slightly different solution: Rather than showing a modal of choices for which auth method to use, we instead show an iframe of (a la Stripe payment iframes). This method has the upside of not requiring an additional click from https auth users.