Authenticate users

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

Install the @stacks/connect package

npm install @stacks/connect

Initiate a UserSession

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 });

Apps may request any of the following scopes:

For more detailed information on these scopes and other API references, visit the Connect API reference page.

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,
  });
}

The showConnect function accepts an object with the following properties:

• The app's name and icon: provided as strings comprising the appDetails object property.
• The redirectTo string: used to provide a URL to which the user should be redirected upon successful authentication.
• The onFinish callback serves a similar purpose by handling successful authentication within a context of a popup window.
• The userSession object initiated above.

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