Auth Flow
This article describes the steps required to authenticate and authorize wallets for purposes such as token gating.
Last updated
This article describes the steps required to authenticate and authorize wallets for purposes such as token gating.
Last updated
All methods of wallet-based authentication and authorization all follow roughly the same five step pattern
Connect wallet
Prompt user to to their wallet provider.
Obtain unique nonce
for user from picket
Sign nonce to obtain signature
Prompt user to sign nonce to retrieve verifiable .
Validate signature and authorization requirements (ex. token ownership)
Use the endpoint to authenticate the wallet and verify any token ownership requirements.
Obtain an
Use the access token as proof of wallet and token ownership for future requests until the access token expires.
Leveraging a Picket client library makes authentication and authorization simple. All step are handled for you in one function:
You can go from zero to token gating in minutes with a single line of code. And, there is no need to build your own auth scheme or secure and manage your auth service over time - Picket handles all of that for you so you can focus on your user experience and get it to the world that much faster.
Picket makes secure, multi-chain auth as simple as that!
However, if you are curious to know what's happening under the hood, keep reading! Picket supports several types of auth flows to meet any application requirements.
Picket SDKs default Solana login requests to the Trusted Wallet Provider flow; however, Solana wallet providers will not protect users against phishing attacks.
If you are using the login method of any of Picket's client-side SDKs, then you are already using this method of authentication 💪. This is the default login method for Picket's client-side SDKs and you can get started by following the instructions in any of Picket's client-side SDKs
The user clicks Login within the application
The Picket SDK generates a cryptographically-random code_verifier, which it uses to generate a code_challenge
The Picket SDK redirects the user to the Picket login page (/login) with code_challenge
The user chooses their wallet provider and receives a prompt to sign a nonce
The Picket Authorization Server validates the user's signature and any other authorization requirements
The Picket Authorization Server stores the code_challenge and redirects the user back to the application with a one-time authorization code
Once back on the application, the Picket SDK sends the authorization code, and the code_verifer to Picket Authorization Server (/oauth/token)
The Picket Authorization Server validates the code and code_verifier and returns an Access Token (JWT)
You can now use the Access Token within your App!
The PKCE flow is implemented for you in Picket's client SDKs. You can opt-in to the PKCE flow by using the loginWithRedirect or loginWithPopup methods instead of the default login method.
Typically, the Resource Owner Password flow, in which a user enters a username and password without redirection (think old-school login form), is not recommended unless it's a highly-trusted application.
However, in Picket, there are no passwords or usernames, only wallets, and signatures! We adapted the resource owner flow to use a wallet address as the username and the signature as the password. We call it the Wallet-Adapted Resource Owner Password Flow.
The user is already authenticated via a traditional provider (Google, Facebook, Github, etc)
The backend already authorize requests from the client
The goal is to associate a wallet address with an existing user account
There are two approaches to implementing the Wallet-Adapted Resource Owner Password Flow
Use Picket client-side SDK to login the user and get an access token, then send it to the backend and use Picket's server-side SDK to verify it
Simplest to implement. Picket handles allowing user to connect to their wallet provider of choice.
Connect the user a wallet provider yourself, use Picket API or client-side SDK to fetch a nonce for the user, have the user sign the nonce, send the signature to the backend, finally the backend uses the /auth endpoint to validate signature and get an access token
More complex to implement, but gives a user a native experience. Picket is invisible to the user.
As mentioned before, all of these authentication flows have roughly the same five steps process. The variations in the process are all state of the art security practices to make sure that only authenticated user receives their access token.
Picket exposes APIs for each part of the auth processes, allowing users to build their own custom flows or re-implement existing flows in languages that don't have a Picket SDK.
For security reasons, it's always advised to use one of the auth flows supported by Picket.
Generally, the most common use-case for implementing a custom signing flow is to re-implement one of the supported auth flows in a language that doesn't yet have a Picket SDK.
If your application deals with sensitive off-chain user information, we recommend the for Solana login requests.
The Trusted Wallet Provider Flow is Picket's chain-agnostic name for the Sign-In with Ethereum (SIWE) protocol created in .
As the name suggests, this flow delegates trust to the wallet provider to protect users from phishing attacks. Phishing attacks trick users into sending sensitive information to a bad actor, or in the case of web authentication, sending an access token to the wrong domain (i.e http://my-evil-app.com). Sign-In with Ethereum (SIWE) compatible wallets prevent phishing attacks by parsing the domain from SIWE and verifying the domain matches the current browser domain of the user.
The Trusted Wallet Provider flow is the default authentication method on all Picket's client-side SDKs and is acceptable for most applications; however, we are still early in the adoption of Sign-In with Ethereum (SIWE) across wallet providers. There is likely going to be a long-tail of EVM wallet providers that do not support SIWE for some time. Similarly, wallet providers don't support SIWE or a similar standard.
If your application deals with sensitive off-chain user information, we recommend using the instead.
The is the most secure method for authenticating users from a native, mobile, or single page app (SPA) application.
This is the most secure authentication flow. If someone getting access to a user's access token is catastrophic to your application, then use the .
The PKCE flow relies on a set of whitelisted redirected URIs to prevent phishing attacks. You can add and remove redirect URIs from a given project in your .
The Wallet-Adapted Resource Owner Password Flow is nearly identical to the with the downside that there is no built-in protection for phishing attacks. Users simply sign a nonce message, send it to the server for verification, and receive an access token in exchange.
The most common use-case for the Wallet-Adapted Resource Owner Password Flow is for . In this setup,
You can use to implement a custom auth flow in any programming language.
