Getting Started

This guide will walk you through the essential steps to integrate decentralized identity (DID) authentication into your React application using @arcblock/did-connect-react. In just a few minutes, you'll have a fully functional login and logout flow.

Prerequisites#

Before you begin, ensure your development environment meets the following criteria:

• You have a React project set up.
• You have a running Blocklet Server instance that will handle the authentication requests. The library is designed to work seamlessly with a backend powered by Blocklet Server.

Step 1: Install the Library#

First, add the @arcblock/did-connect-react package to your project. You can use either npm or yarn.

npm install @arcblock/did-connect-react

yarn add @arcblock/did-connect-react

Step 2: Set Up the SessionProvider#

The SessionProvider is the heart of the library. It's a context provider that manages the user's session state (like login status and user information) and makes it available to all components wrapped within it. You should place it at the root of your application, for instance, in your App.js file.

For applications built on Blocklet, the recommended way to initialize the provider is by using the createAuthServiceSessionContext factory function.

import React from 'react';
import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
import Home from './Home'; // We will create this component in the next step

// createAuthServiceSessionContext is optimized for Blocklet environments
const { SessionProvider } = createAuthServiceSessionContext();

function App() {
  return (
    // The serviceHost prop points to the base path of your backend authentication service.
    // For a standard Blocklet, this is usually the blocklet's prefix or '/'.
    <SessionProvider serviceHost="/">
      <Home />
    </SessionProvider>
  );
}

export default App;

Step 3: Implement Login and Logout#

Now, let's create a component that allows users to log in and log out. We can access the session data and functions using React's useContext hook with the SessionContext.

The session object gives you everything you need: the current user, the loading state, and functions like login() and logout().

import React, { useContext } from 'react';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
import Button from '@arcblock/ux/lib/Button'; // A general-purpose button
import CircularProgress from '@mui/material/CircularProgress';

function Home() {
  // Access the session context
  const { session } = useContext(SessionContext);

  // Destructure for easier access
  const { user, loading, login, logout } = session;

  // Display a loading indicator while the session is being initialized
  if (loading) {
    return <CircularProgress />;
  }

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      {user ? (
        // If the user is logged in, show their DID and a logout button
        <div>
          <h1>Welcome!</h1>
          <p>Your DID: {user.did}</p>

When the user clicks the ConnectButton, the login() function is called. This function handles opening the DID Connect modal, which displays a QR code for the user to scan with their DID Wallet, and manages the entire authentication process.

Step 4: Access User Data#

Once a user has successfully logged in, the session.user object will be populated. This object contains the user's profile information retrieved from their DID Wallet.

The session object provided by the context is your main interface to the user's authentication state. Here are its key properties:

You're All Set!#

Congratulations! You have successfully implemented a complete DID-based authentication flow in your React application. Users can now sign in using their DID Wallet, and your application can securely access their session information.

Next Steps#

To dive deeper and explore more advanced features, check out the following sections: