🌊Auth Flow

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.

The Steps to Authenticate and Authorize Wallet

All methods of wallet-based authentication and authorization all follow roughly the same five step pattern

1. Connect wallet

   Prompt user to connect to their wallet provider.

2. Obtain unique nonce

   Fetch nonce for user from picket

3. Sign nonce to obtain signature

   Prompt user to sign nonce to retrieve verifiable signature.

4. Validate signature and authorization requirements (ex. token ownership)

   Use the /auth endpoint to authenticate the wallet and verify any token ownership requirements.

5. Obtain an access token

   Use the access token as proof of wallet and token ownership for future requests until the access token expires.

Auth w/ a Picket Client Library

Leveraging a Picket client library makes authentication and authorization simple. All step are handled for you in one function:

await picket.login();

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.

Auth Flows Deep Dive

Trusted Wallet Provider Flow (a.k.a Sign-In With Ethereum)

Picket SDKs default Solana login requests to the Trusted Wallet Provider flow; however, Solana wallet 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 Solana login requests.

Background

The Trusted Wallet Provider Flow is Picket's chain-agnostic name for the Sign-In with Ethereum (SIWE) protocol created in EIP-4361.

How it Works?

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 message template format and verifying the domain matches the current browser domain of the user.

When to Use?

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.

How to Use?

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

• Javascript SDK

• React SDK

OAuth 2.0 - Authorization Code Flow with Proof Key for Code Exchange (PKCE)

PKCE is colloquially pronounced "pixy"

Background

The Authorization Code Flow with PKCE is the most secure method for authenticating users from a native, mobile, or single page app (SPA) application.

How it Works?

Visual Representation of the Picket Authorization PKCE Flow

Step by Step 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 code_challenge

3. The Picket SDK redirects the user to the Picket login page (/login) with code_challenge

4. The user chooses their wallet provider and receives a prompt to sign a nonce

5. The Picket Authorization Server validates the user's signature and any other authorization requirements

6. The Picket Authorization Server stores the code_challenge and redirects the user back to the application with a one-time authorization code

7. Once back on the application, the Picket SDK sends the authorization code, and the code_verifer to Picket Authorization Server (/oauth/token)

8. The Picket Authorization Server validates the code and code_verifier and returns an Access Token (JWT)

9. You can now use the Access Token within your App!

When to Use?

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.

How to Use?

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.

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.

OAuth 2.0 - Wallet-Adapted Resource Owner Password Flow

Background

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.

How it Works?

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.

When to Use?

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

How to Use?

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 /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.

Manual Signing (Custom Implementation)

Background

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.

How it Works?

Auth Flow w/o picket.login()

When to Use?

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.

How to Use?

You can use Picket's REST APIs to implement a custom auth flow in any programming language.