Skip to main content
The People Who Couldn't Get In: Onboarding Testers to Anvil Connect
platform-engineeringidentityproductsecurityhomelab

The People Who Couldn't Get In: Onboarding Testers to Anvil Connect

What tripped up the testers I invited to Anvil Connect, from passkeys to reset wording, and the fixes that moved the friction into the system.

Sekou M. Doumbouya

Sekou M. Doumbouya

· 10 min read

Listen to this article

The views expressed here are my own and do not represent those of any current or former employer.

Part 2 of a six-part series on Anvil Connect.

One of the first developers I invited could not create a passkey.

On September 12 and 13, I exposed Pi to a few developers and worked out the steps to set up a Pi-only user. Email was not working yet, so every verification code landed in a file on my side, and I copied each one out by hand and passed it along. Until email worked, I was, functionally, the email server. That file keeps only the newest message, so manual invitations go one at a time, and Authelia’s default setup link lasts five minutes.

Before any of this, my wife and my friends hit the Tailscale wall, and Part 1 covers that. The post on two agents and one gateway ends with my wife clicking a link and signing in. This post is about everything that link did not fix.

The main challenge of this whole project, in my own words, was “dealing with users that don’t use these different tools, that aren’t as tech savvy.” I know what a passkey is and why a redirect might loop. The people I wanted feedback from should not have to.

A link gets someone to a door. Getting them through it means account creation, a credential, a first sign-in, a second app that wants its own sign-in, and the right permissions waiting on the other side. Each of those is a step where a person can stop.

Onboarding is a new hire with no tribal knowledge

Anyone who has onboarded engineers knows the new hire is never the slow part. The organization is full of things everyone else learned by accident: which wiki page is stale, which button you never press, who to ask when the badge reader rejects you. A good onboarding process takes that tribal knowledge out of people’s heads and puts it into the system.

A tester who does not live in these tools is the purest version of that new hire. They arrive with zero context. Whatever I knew and they did not, I either built into Connect or carried myself. In those first days with Pi, copying codes out of a file, I carried it.

Inviting moved the first burden

The invite flow shipped on September 13. I create the account with its grants, Authelia emails a short-lived password-setup link, and the person sets their own password and then adds a passkey. Part 1 covers the roles behind those grants.

Skipping the starter password matters more than it looks. A starter password is a secret I have to generate, send, and trust the person to change. None is handed out, and the random value the account is created with is thrown away after hashing. Removing it improves security and onboarding at the same time.

Open WebUI fought back

The same day, I tried to put Open WebUI behind the new sign-in, and it did not go quietly. There was a PKCE mismatch with Authelia. PKCE is the check that ties the end of a sign-in to the browser that started it, so when the two sides disagree on it, the sign-in simply fails. New-user provisioning was turned off, so a person who signed in successfully had no account waiting for them. There were 500 errors. There was an extra Open WebUI login screen in front of a person who had already signed in once. And the passkey prompt only appeared after a password-manager setting changed.

From the inside, those are five separate problems. From the outside, it is one experience: this does not work.

What actually tripped people up

On September 20, I wrote an onboarding note listing what had tripped people up.

  • “Reset” wording on a first sign-in, when they were setting a password, not resetting one
  • Long invite links
  • A refreshed link that strands them
  • Phones capitalizing usernames
  • Landing back on the sign-in page after adding a passkey
  • A CLI preview of the setup email mistaken for a sent email

Look at the first one. A person signing in for the first time is told they are resetting a password they never had. The words were accurate from the system’s point of view and wrong from the person’s. Authelia uses the same notification for first setup and for later recovery, so the reset language comes from upstream, not from anything the person did.

The stranded link has a mechanical cause. The pinned Authelia flow uses up the link while it validates the password page, before the new password is ever submitted. A refresh or a second tab then shows an already-used-link error, or leaves the password fields disabled. The person did nothing wrong and is still stuck. The way out is Cancel, then Reset password, then a fresh link, and the setup email now carries that recovery action itself.

Landing back on sign-in after adding a passkey has a mechanical cause too. Registering a passkey does not necessarily finish the sign-in that is in progress. The person still has to complete it with the passkey they just registered. That is correct behavior, and it reads like being sent back to the start.

The phone item is the same lesson from another angle. A phone that helpfully capitalizes the first letter of a username has done nothing wrong by its own lights. So has a terminal preview of the setup email. Both told the truth, and both were easy to misread. Without confirmation, the account command only previews: no account is created and no email goes out. Even a real send now reports that the email was requested and that inbox delivery is not verified, which is honest about the one thing the command cannot know. And the browser acceptance checklist now names the actual mobile username field as something to test.

The fixes were unglamorous: a newer Authelia pin, readable setup mail, cache prevention, and guidance that separates enrollment from sign-in. Readable mail means the message leads with a Set up your password button, offers a way to get a replacement link, and points to the service home, while the plain-text version keeps the full link. Cache prevention means signed-in pages are marked so the browser does not keep them. Otherwise a page cached before a session expired can come back as a generic error, while the requests behind it correctly answer with a 401, the code for not signed in.

That last fix, the guidance, is the real lesson in the list. Enrolling a passkey and signing in with one are different moments, and treating them as the same moment confused people who do not live in these tools.

Later testers kept finding edges

One test account’s setup email went to spam. It also turned out that Connect needs a unique email per user. A request receipt is not a delivery receipt. The reset endpoint hides delivery failures on purpose, so nobody can probe which accounts exist, which means a successful request proves nothing about the inbox. On October 17, I spent an hour waiting on a tester who never arrived, and onboarding visibility came only after it; Part 6 tells that one.

What works now

Once email onboarding landed, adding a tester took one command. That is the number I care about. Not how many components sit behind the door, but how many steps it takes me to let someone through it.

Mistakes got cheaper too. If the account is created but granting access fails, the command reports which step stopped, and the fix is to retry the grants, not to create the account again. The rest of what made it useful, from per-user entitlements to rate limits, gets its due in the post on Open WebUI and Hindsight.

What still has friction

This is not frictionless, and I will not pretend it is.

Every person I invite needs an email address of their own, and that is a real constraint on who I can bring in easily.

The setup email’s subject and its password page still use reset wording. The template does not tell an invitation apart from an ordinary password reset, so the first item on that September list is still partly open.

Enrollment still asks a person to accept a passkey at least once. The guidance now separates enrollment from sign-in, but the first passkey is still a concept the person has to take on. I moved that friction. I did not remove it.

Five minutes is a short life for a setup link. I can now set a longer lifetime, up to a day, but that setting applies to every account, not to one invitation at a time.

Email delivery is also outside my control. A setup email that lands in spam can strand a tester before the first step.

Friction belongs in the system

Look back at every fix in this story and they share one shape. Copying codes by hand became Authelia emailing them. A starter password became a setup link where the person picks their own password, then adds a passkey. A link stranded by a refresh became a recovery action in the email itself. Guessing where a tester was became a view that shows me. A confusing first sign-in became guidance that separates enrollment from sign-in. Each fix took a burden off the person trying to get in and put it on the system I own.

That is the principle I would hand anyone building for people who do not share their skill set. Friction does not disappear. It lives somewhere. Put it in the system, where you can see it, test it, and fix it once, not on the person, where it is invisible.

The post on Pi Web picks up with the coding agent that sat behind this front door.

0 claps

Enjoyed this? Tap to applaud, hold to really applaud.

Share this post
LinkedInXHacker NewsBluesky

Co-authored with AI, based on the author's working sessions, dictations, and notes.

Explore the source

fakoli/anvil-serving

This article discusses an open-source project. Star it, fork it, or open an issue.