User Authentication in Frames

[deodad]

In the original frames design a FrameMessage was signed over by a user's App Key. This was a lightweight way to give frames a reasonable expectation of who they were interacting with while providing a great UX for the user since the user didn't need to take any additional action.

The downside to this approach is that App Keys weren't intended to be authorization tokens:

• When a user creates an App Key they are warned that this key can post on their behalf but nothing indicates it will be used as a general purpose means of authorization.
• App Keys are usually custodial—they are controlled by the Farcaster client instead of the user.
• Applications need to maintain separate auth flows for Sign In With Farcaster (SIWF) vs frame interactions.

Proposal

In Frames v2 SIWF should be the primary mechanism to authenticate users. This simplifies the mental model for users and developers alike and provides much stronger guarantees against abuse since the keys are self-custodial.

We can add an action API signIn({ nonce }) that initiates the SIWF flow from within the frame and returns a SIWF token if completed. Since this flow is controlled by the hosting client we avoid some of the security and routing issues that we have in the standalone SIWF flow:

• phishing attacks becomes less likely since the host knows the domain of the frame the user interacting with
• the SIWF will be initiated with the Farcaster client rather than the relay: the Farcaster client can make optimizations if they have access to the user's custody address or already know where to route the user, otherwise they can fallback to a flow similar to the existing AuthKit SIWF flow where the user is directed via QR code to complete the signature on a device where there key is stored

The biggest drawback with this approach is that the user experience won't always be seamless: for example, a Warpcast web user or Super user who has their custody address hosted by Warpcast mobile will need to go to their mobile device to complete the request. This is a general limitation of SIWF that should independently be addressed but is outside the scope of this current proposal.

Frames can use the SIWF credential to bootstrap their own cookie based authentication session so that a session can be maintained for the user across frame interactions.

Update

Frame Auth has been added to the frames spec and discussion here is closed.

[cryptods8]

is the current (mini app-like) auth out of the question? i feel like no-hassle auth was the greatest benefit of frames.

i know we (app devs) don't have the strongest possible guarantee, but it's sufficient for many cases. (plus, if needed, we can fall back to SIWF.)

[deodad]

Not out of the question. This path would likely look like signing over the context object with a Json Farcaster Signature using the user's app key. We'd call it something like verified context and indicate that it isn't meant to serve as a general purpose authentication mechanism but can be carefully used in certain contexts.

It'd be a big UX win for a lot of apps where SIWF is overkill (e.g. no funds, no private information). The downside is it's more complexity for devs since there are now two ways to discover the FID from a signed message. And it's not easy to describe in what situations one is preferred to the other. There will be a non-zero number of cases of misuse either intentionally (e.g. I want a good UX and am too lazy to do SIWF) or unintentionally (e.g. assumed verified means good for auth).

[cryptods8]

The downside is it's more complexity for devs since there are now two ways to discover the FID from a signed message

what do you mean? as in one fid in unsigned and one in signed body? does it matter? if i don't need auth, i just use either one (probably from unsigned), if i do, i should verify they match anyway, no?

agreed with the rest. it's obvious since i'm the one asking, but for me personally, the positives outweigh the negatives.

[deodad]

w hat do you mean? as in one fid in unsigned and one in signed body? does it matter? if i don't need auth, i just use either one (probably from unsigned), if i do, i should verify they match anyway, no?

for a dev they would have:

• an untrusted FID they could pull from context
• a verifiable version of context they could pull the FID from and verify the signature via a hub or neynay
• a SIWF authentication flow where they could get a SIWF token that has the FID

if you are new to FC these three different ways to access the FID and the implications of each (untrusted vs App Key signed vs self-custodial signed) is hard to grok

[SamuelLHuber]

what if it's like Frames v1? both signedMessageBytes and untrustedData are available where signedMessageBytes is the untrustedData but signed with an appKey (Signer)

this would be familiar to existing devs, easy to understand for future devs that want to know it's likely that FID and for anyone requiring auth -> Farcaster connect (current SIWF)

[vrypan]

The biggest drawback with this approach is that the user experience won't always be seamless: for example, a Warpcast web user or Super user who has their custody address hosted by Warpcast mobile will need to go to their mobile device to complete the request.

Can't we support both? The party to decide if they need a signature by the appkey or the user's wallet is the frame. My casual game is fine with an appkey-signed proof of identity, an airdrop-by-fid frame will probably want a signature from my wallet. Why not let the Frame request the type of authentication it needs?

[deodad]

we can, see this thread for info. it's likely worth the benefit but the cost is a complex auth model for users and devs to grok—it will mean unavoidable confusion for both parties

[vrypan]

When we were discussing (a year ago?) about Farcaster Connect and Sign in With Farcaster, I had suggested we use Farcaster Connect with levels. https://warpcast.com/vrypan.eth/0x2fc50727

Levels are easier to explain to user, imho.

As for devs, I know what my Frame requires. I mean, I should be able to let the client know that my Frame expects a signature from the custody address, or from an appkey, and my code will only check for what I expect. I won't have three if-then-elses: I expect a custody address signature and I check if it's there or not. What am I missing?

[vrypan]

Connect-0: Get FID from the request
Connect-1: Get FID signed by the app (you trust the app, and you have to verify using a hub)
Connect-10: Get FID signed by the user's wallet (most trusted, but more friction)

[deodad]

the levels concept is nice but take a relatively new user or developer and they are going to be confused.

there are sophisticated devs and users who've been following FC for years who don't understand the nuance of app keys. it's much simpler to just point to one way to do auth.

[sidrisov]

I like this! Just curious any plan to re-use or integrate into existing @farcaster/auth-kit?

Overall, if it works exactly as existing SIWF, very less work to do, till there is clearer path for more granular auth permission control on farcaster.

[deodad]

yes 💯

[benadamsky]

With the proposed requestSIWF action, would apps be able to bootstrap their own auth provider sessions (eg Privy, Thirdweb, etc) from the SIWF token?

Also curious if requestSIWF needs to go through a client like Warpcast directly, or there’s another way this could work with existing SIWF implementations from other providers. The most seamless solution would be if auth providers could handle SIWF directly within the frame context

Ideally we'd love to either:

1. Have auth providers handle SIWF directly in frame context
2. Use that for session establishment
3. Maintain that session across frame interactions

Or at minimum:

1. Use requestSIWF through a client like Warpcast when in frame context
2. Use that token to establish an auth provider session w/ a third-party
3. Maintain that session across frame interactions

This would give us both the security of SIWF and seamless UX after first login, while still keeping auth consistent between frame and web contexts

[deodad]

yes the token can be used however you see fit. these providers will need to support accepting a token directly in addition to the baked in AuthKIt SIWF flow. we're already started working with Privy on this.

the flow should end up being something like this:

1. auth provider initiates SIWF flow, if it's the web flow is not changed (e.g. goes through the relay), if it's a frame they can skip the relay and make the request directly through the SDK
2. frame receives that request and handles it natively — this will be a much better experience, for instance if the user in on Warpcast mobile the request can be immediately satisfied, otherwise the host can route the user to whereever their custody is address to complete (again this can be optimized, if on Warpcast web we can send a push notification)

once the token is returned it should be used as a credential and cookie based session can be started so that the next time the user interacts with the frame the session can be resumed

[benadamsky]

Got it, that's great additional context thanks!

Excited to test this flow out as soon as it's ready 🙏

[SamuelLHuber]

adding on: privy looking into it. @benadamsky

[wojtekwtf]

How does it relate to Farcaster Connect? Using SIWF in current version feels too painful

[deodad]

tangentially. in the frames model a request is handled directly by the hosting Farcaster client which is quite convenient. for example, when Super implements frames v2 and receives a sign in request from the frame, if Super has access to the user's custody address Super can immediately get the signature. If Super doesn't have access then routing needs to happen, this is where Farcaster Connect would come in handy. For now the existing QR code based flow would likely suffice well since almost all non-Super users are on Warpcast.

[androidsixteen]

I don't fully understand the purpose of this change... it seems like it narrows the methods by which the frame server can ascertain FID in order to create a standardized path through SIWF

But the slickness and "just works" quality of signing with the App Key is too good to lose

I'd suggest allowing for both paths (verified context and auth). And accept the trade-off of having to explain or let devs navigate both paths. But at this stage of frames adoption (ie. low), more power is desirable over cleaner docs and paved roads for how to do things

[deodad]

primary purpose: provide a robust auth solution into frames. right now there is no way to do this in frames v2 (SIWF or App Key based).

adding a native SIWF action will accomplish this with some major advantages:

• self-custodial
• isomorphic auth experience between web vs frame which is beneficial for users and devs alike

a secondary question is should we also add an app key based signature and if so how should that work (is signing the context enough? how are apps supposed to use this: to bootstrap a JWT based session or to use it as a session token itself when making subsequent requests? should we let them request an arbitrary or limited payload instead more akin to a FrameMessage? or just keep support FrameMessages?). I agree the juice is likely worth the squeeze here. but it's also worth understanding the trade offs and considering whether there's a path to double down on SIWF to make it as seamless a UX. if we think we could achieve that in a month or two I could be convinced to push for that instead. short term the complexity bump seems fine but on broader horizons is the fragmentation worth it if the UX problems are tractable?

[vrypan]

For appkey signatures, I would create a similar call requestAppSignature({ nonce, endpoint }) and the app will have to sign a pre-defined message (for example, {fid, nonce, signature}) and post it to endpoint. Would this work?

[vrypan]

On second thought, the signed payload should be similar to v1 signatures, so that the Frame server can use the ValidateMessage() endpoint?

[deodad]

@vrypan I see lots of ways it could work but not one of them has stood out as obvious

[SamuelLHuber]

For appkey signatures, I would create a similar call requestAppSignature({ nonce, endpoint }) and the app will have to sign a pre-defined message (for example, {fid, nonce, signature}) and post it to endpoint. Would this work?

I'd say we get signedMessageBytes directly in the context message and are good to go? #211 (reply in thread)