Picket Docs
  • ๐Ÿ‘‹Welcome to Picket
  • Quick Start Guides
    • ๐Ÿš€Quick Start Guides
      • โš™๏ธStart Here: Setup
      • ๐Ÿ”Wallet Login
      • ๐Ÿช™Token Gating (Ethereum / EVM)
      • ๐ŸคบToken Gating (Solana)
      • ๐Ÿคนโ€โ™‚๏ธIncremental Token Gating
      • โ›”Restrict Access to Specific Wallets
      • ๐Ÿ”‘Working with Access Tokens
  • Reference
    • ๐ŸŽ“Concepts
      • ๐ŸŒŠAuth Flow
      • ๐Ÿ—ƒ๏ธConnect
      • โœ๏ธSignatures
      • ๐Ÿ”Authentication and Authorization
      • ๐ŸคนIncremental Authorization
      • ๐Ÿช™Access Tokens
      • ๐ŸงชTesting
      • โ‰๏ธErrors
      • โ›“๏ธSupported Blockchains
      • ๐ŸŒSupported Languages (Localization)
      • ๐ŸŽจModal Themes
      • ๐Ÿ’ฟOpen Source Web3 Client Libraries
    • ๐Ÿ“šLibraries and SDKs
      • Javascript Library - picket-js
      • React SDK - picket-react
      • Node.js Library - picket-node
      • Go Library - picket-go
      • Python Library - picket-python
    • ๐Ÿ”ฅIntegrations
      • ๐ŸŒˆPicket Authentication with RainbowKit
      • โšกSupabase
      • โ˜๏ธAmazon Cognito
      • ๐Ÿ›๏ธPicket Shopify App - Merchant Documentation
      • ๐Ÿ›’Picket BigCommerce App - Merchant Documentation
    • ๐Ÿ“–API Reference
      • Projects & API Keys
      • Auth
      • Chains
      • Wallets
      • Contracts
      • OAuth 2.0
  • ๐Ÿ•น๏ธTutorials
    • ๐ŸŒŽSign-In with Wallet (React)
    • ๐ŸฐToken Gated Photo Board (React)
    • ๐Ÿ”—Link a Wallet to a Web 2.0 Account
    • ๐ŸคIncremental Authorization (React)
Powered by GitBook
On this page
  • The Steps to Authenticate and Authorize Wallet
  • Auth w/ a Picket Client Library
  • Auth Flows Deep Dive
  • Trusted Wallet Provider Flow (a.k.a Sign-In With Ethereum)
  • OAuth 2.0 - Authorization Code Flow with Proof Key for Code Exchange (PKCE)
  • OAuth 2.0 - Wallet-Adapted Resource Owner Password Flow
  • Manual Signing (Custom Implementation)
  1. Reference
  2. Concepts

Auth Flow

This article describes the steps required to authenticate and authorize wallets for purposes such as token gating.

PreviousConceptsNextConnect

Last updated 3 years ago

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 to their wallet provider.

  2. Obtain unique nonce

    for user from picket

  3. Sign nonce to obtain signature

    Prompt user to sign nonce to retrieve verifiable .

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

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

  5. Obtain an

    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.

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.

Background

How it Works?

When to Use?

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

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

PKCE is colloquially pronounced "pixy"

Background

How it Works?

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?

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.

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?

When to Use?

  • 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?

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?

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.

๐ŸŽ“
๐ŸŒŠ
connect
Fetch nonce
signature
/auth
access token
OAuth 2.0 PKCE flow
EIP-4361
message template format
Solana
OAuth 2.0 PKCE flow
Javascript SDK
React SDK
Authorization Code Flow with PKCE
Authorization Code Flow with PKCE
Picket account dashboard
Trusted Wallet Provider Flow
linking a wallet address to an existing user account
Picket's REST APIs
Auth Flow implemented w/ client SDK
Visual Representation of the Picket Authorization PKCE Flow
Auth Flow w/o picket.login()