This article describes the steps required to authenticate and authorize wallets for purposes such as token gating.
All API requests must be made over HTTPS. HTTP is insecure and unsupported.
All methods of wallet-based authentication and authorization all follow roughly the same five step pattern
- 4.Validate signature and authorization requirements (ex. token ownership)Use the
/authendpoint to authenticate the wallet and verify any token ownership requirements.
- 5.Obtain an access tokenUse 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.
Auth Flow implemented w/ client SDK
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
Solanalogin requests to the Trusted Wallet Provider flow; however,
Solanawallet providers will not protect users against phishing attacks.
If your application deals with sensitive off-chain user information, we recommend the OAuth 2.0 PKCE flow for
The Trusted Wallet Provider Flow is Picket's chain-agnostic name for the Sign-In with Ethereum (SIWE) protocol created in EIP-4361.
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
domainfrom SIWE message template format and verifying the
domainmatches 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, Solana wallet providers don't support SIWE or a similar standard.
If your application deals with sensitive off-chain user information, we recommend using the OAuth 2.0 PKCE flow instead.
If you are using the
loginmethod 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
PKCE is colloquially pronounced "pixy"
The Authorization Code Flow with PKCE is the most secure method for authenticating users from a native, mobile, or single page app (SPA) application.
Visual Representation of the Picket Authorization PKCE Flow
- 1.The user clicks Login within the application
- 2.The Picket SDK generates a cryptographically-random
code_verifier, which it uses to generate a
- 3.The Picket SDK redirects the user to the Picket login page (
- 4.The user chooses their wallet provider and receives a prompt to sign a
- 5.The Picket Authorization Server validates the user's signature and any other authorization requirements
- 6.The Picket Authorization Server stores the
code_challengeand redirects the user back to the application with a one-time authorization
- 7.Once back on the application, the Picket SDK sends the authorization
code_veriferto Picket Authorization Server (
- 8.The Picket Authorization Server validates the
code_verifierand returns an Access Token (JWT)
- 9.You can now use the Access Token within your App!
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 Authorization Code Flow with PKCE.
The PKCE flow is implemented for you in Picket's client SDKs. You can opt-in to the PKCE flow by using the
loginWithPopupmethods instead of the default
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 Picket account dashboard.
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.
A nice side-effect of using nonce signatures as a password is that you can only use it once (a.k.a OTP, One-Time Password).
Even if an attacker steals your signature and uses it to get an access token before the signature expires (<= two minutes), they won't be able to re-use the signature to get an access token in the future.
The Wallet-Adapted Resource Owner Password Flow is nearly identical to the Trusted Wallet Provider Flow 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 linking a wallet address to an existing user account. In this setup,
- 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
- 1.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.
- 2.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
/authendpoint 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.
Auth Flow w/o picket.login()
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.