Authenticate Users with Connect

Authentication is a fundamental part of many web applications, ensuring that users are who they claim to be and that their data is secure. With the Stacks blockchain, user authentication involves connecting to users' wallets and managing their sessions securely.

The @stacks/connect package from Stacks.js provides the tools needed to integrate this functionality seamlessly into your web app.

In this guide, you will learn how to:

1. Install and set up the @stacks/connect package
2. Initiate a userSession with specific permission scopes
3. Trigger the authentication flow with the showConnect function
4. Handle pending authentication states and manage user data

The examples in this guide are designed to be minimalistic, allowing you to easily adapt and customize them to fit your application's specific needs.

Install and set up the @stacks/connect package

First, install the @stacks/connect package in your project.

npm install @stacks/connect

Initiate a userSession with specific permission scopes

After installing the @stacks/connect package, initiate a userSession with the following permission scopes.

import { AppConfig, UserSession } from '@stacks/connect';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });

Trigger the authentication flow with the showConnect function

Create an authenticate function that will call showConnect, triggering the popup that initiates the authentication process for users. They will authenticate with a Secret Key that's used to encrypt their private data.

function authenticate() {
  showConnect({
    appDetails: {
      name: 'My App',
      icon: window.location.origin + '/my-app-logo.svg',
    },
    redirectTo: '/',
    onFinish: () => {
      let userData = userSession.loadUserData();
    },
    userSession,
  });
}

Handle Pending Authentication

After initiating the authentication process, you will most likely need to handle cases where the user hasn't completed the authentication flow.

1. Check if there is a pending sign-in using the isSignInPending method of the userSession object.
2. If there is a pending sign-in, handle it by calling handlePendingSignIn which processes the sign-in and then utilizes the userData returned in a promise.

import { AppConfig, UserSession, showConnect } from '@stacks/connect';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });

window.onload = function () {
  if (userSession.isSignInPending()) {
    userSession.handlePendingSignIn().then(userData => {
      // Save or otherwise utilize userData post-authentication
    });
  } else if (userSession.isUserSignedIn()) {
    // Handle case in which user is already authenticated
  }
};

For users already signed in, you can directly access their session information and proceed with your app's flow.

Next steps