useOAuth & usePasskey

While the DidConnect component and useConnect hook provide a comprehensive, pre-built UI for all authentication methods, you may need to build a custom authentication flow. The useOAuth and usePasskey hooks offer direct access to the underlying logic for social logins (OAuth) and passwordless authentication (Passkey).

These hooks are powerful tools for creating bespoke user experiences. They depend on their respective context providers, OAuthProvider and PasskeyProvider, which are typically included within the main SessionProvider. For more information on session management, see the SessionProvider documentation.

useOAuth#

The useOAuth hook provides functions and state for handling third-party social login flows.

Import#

import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';

Return Value#

The hook returns an object containing the following properties and methods:

loginOAuth
function
required

Initiates a login flow with a specified OAuth provider. It opens a popup for user authorization and returns a promise that resolves with the login result.

bindOAuth
function
required

Binds a new OAuth account to the currently logged-in user's session.

unbindOAuth
function
required

Unbinds an OAuth account from the current user's session.

getOAuthConfigList
function
required

Fetches the list of enabled and configured OAuth providers from the blocklet settings. Returns a promise that resolves to an array of provider configuration objects.

switchOAuthPassport
function
required

Initiates a flow to switch between different connected accounts (passports) of the same identity.

bindAuthLoading
boolean
required

A boolean flag that is true while the bindOAuth operation is in progress.

unbindAuthLoading
boolean
required

A boolean flag that is true while the unbindOAuth operation is in progress.

oauthState
object
required

An object containing the real-time status of the authentication process.

3 subfields

Usage Example#

Here's an example of how to build a custom social login component.

CustomSocialLogin.jsx

import React, { useEffect, useState } from 'react';
import { useOAuth } from '@arcblock/did-connect-react/lib/OAuth';
import { useSession } from '@arcblock/did-connect-react/lib/Session';

export default function CustomSocialLogin() {
  const { loginOAuth, getOAuthConfigList } = useOAuth();
  const { session } = useSession();
  const [providers, setProviders] = useState([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  useEffect(() => {
    // Fetch the list of available OAuth providers when the component mounts
    getOAuthConfigList().then(setProviders).catch(console.error);
  }, [getOAuthConfigList]);

  const handleLogin = async (provider) => {
    setLoading(true);
    setError('');
    try {
      const result = await loginOAuth({ provider: provider.provider });
      // After successful login, the session will be updated automatically by the SessionProvider.
      console.log('Login successful:', result);
      // You might want to refresh the session or redirect the user here.
    } catch (err) {

See all 27 lines

usePasskey#

The usePasskey hook provides functions and state for handling passwordless authentication using WebAuthn (Passkeys).

Import#

import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';

Return Value#

The hook returns an object containing the following properties and methods:

loginPasskey
function
required

Initiates a login flow using an existing Passkey. It triggers the browser's native WebAuthn authentication prompt.

connectPasskey
function
required

Initiates a flow to create and bind a new Passkey to the current user's session.

disconnectPasskey
function
required

Unbinds a Passkey from the current user's session after successful verification.

switchPassport
function
required

Initiates a flow to switch between different connected accounts (passports).

connecting
boolean
required

A boolean flag that is true while the connectPasskey operation is in progress.

disconnecting
boolean
required

A boolean flag that is true while the disconnectPasskey operation is in progress.

passkeyState
object
required

An object containing the real-time status of the Passkey operation.

5 subfields

Usage Example#

Here's an example of how to create a "Login with Passkey" button.

PasskeyLoginButton.jsx

import React, { useState } from 'react';
import { usePasskey } from '@arcblock/did-connect-react/lib/Passkey';

export default function PasskeyLoginButton() {
  const { loginPasskey, passkeyState } = usePasskey();
  const [error, setError] = useState('');

  const handleLogin = async () => {
    setError('');
    try {
      const result = await loginPasskey();
      console.log('Passkey login successful:', result);
      // The session will be updated automatically by the SessionProvider.
    } catch (err) {
      setError(err.message);
      console.error('Passkey login failed:', err);
    }
  };

  return (
    <div>
      <button onClick={handleLogin} disabled={passkeyState.loading}>
        {passkeyState.loading ? 'Verifying...' : 'Login with Passkey'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}

See all 3 lines

These hooks provide the flexibility to integrate DID Connect's powerful authentication features into any part of your application with a completely custom UI. To learn about programmatically controlling the pre-built DidConnect modal, proceed to the useConnect hook documentation.

useDid
UI Components