Nuclear Powered Macros

    @dfinity/auth-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.12.0 • Public • Published

    @dfinity/auth-client

    0.10.5 Idle update - see changes here

    Simple interface to get your web application authenticated with the Internet Identity Service

    Visit the Dfinity Forum and SDK Documentation for more information and support building on the Internet Computer.

    Additional API Documentation can be found here.


    Installation

    Using AuthClient:

    npm i --save @dfinity/auth-client
    

    In the browser:

    import { AuthClient } from "@dfinity/auth-client";
    

    To get started with auth client, run

    const authClient = await AuthClient.create();

    The authClient can log in with

    authClient.login({
      // 7 days in nanoseconds
      maxTimeToLive: BigInt(7 * 24 * 60 * 60 * 1000 * 1000 * 1000),
      onSuccess: async () => {
        handleAuthenticated(authClient);
      },
    });

    It opens an identity.ic0.app window, saves your delegation to localStorage, and then sets you up with an identity.

    Then, you can use that identity to make authenticated calls using the @dfinity/agent Actor.

    const identity = await authClient.getIdentity();
    const actor = Actor.createActor(idlFactory, {
      agent: new HttpAgent({
        identity,
      }),
      canisterId,
    });

    Idle Management

    The AuthClient provides two forms of security for session management. The first is built into the Internet Identity delegation - the maxTimeToLive option in nanoseconds determines how long the DelegationIdentity you get back will be valid for. The second is the Idle Manager, which moniters keyboard, mouse and touchscreen identity. The Idle Manager will automatically log you out if you don't interact with the browser for a period of time.

    If you pass no options to the IdleManager, it will log you out after 10 minutes of inactivity by removing the DelegationIdentity from localStorage and then calling window.location.reload().

    If you pass an onIdle option, it will call that function when the user is idle, replacing the default window.location.reload() behavior. You can also register callbacks after the idleManager is created with the idleManager.registerCallback() method, which will also replace the default callback.

    The full set of options for the IdleManager is:

      /**
       * Callback after the user has gone idle
       */
      onIdle?: IdleCB;
      /**
       * timeout in ms
       * @default 30 minutes [600_000]
       */
      idleTimeout?: number;
      /**
       * capture scroll events
       * @default false
       */
      captureScroll?: boolean;
      /**
       * scroll debounce time in ms
       * @default 100
       */
      scrollDebounce?: number;

    Additionally, the AuthClient accepts a couple additional flags to idleOptions to control the IdleManager:

      /**
       * Disables idle functionality for {@link IdleManager}
       * @default false
       */
      disableIdle?: boolean;
    
      /**
       * Disables default idle behavior - call logout & reload window
       * @default false
       */
      disableDefaultIdleCallback?: boolean;

    IdleManager Example Usage

    const authClient = await AuthClient.create({
      idleOptions: {
        idleTimeout: 1000 * 60 * 30, // set to 30 minutes
        disableDefaultIdleCallback: true // disable the default reload behavior
      }
    });
    // ...authClient.login()
    const identity = await authClient.getIdentity();
    const actor = Actor.createActor(idlFactory, {
      agent: new HttpAgent({
        identity,
      }),
      canisterId,
    });
    
    refreshLogin() {
      // prompt the user then refresh their authentication
      authClient.login({
        onSuccess: async () => {
          const newIdentity = await AuthClient.getIdentity();
          Actor.getAgent(actor).replaceIdentity(newIdentity);
        }
      });
    }
    
    authClient.idleManager?.registerCallback?.(refreshLogin);

    In this code, we create an authClient with an idle timeout of 30 minutes. When the user is idle, we invalidate their identity and prompt them to login again.

    After the user logs in, we can set the new identity in the actor without reloading the page.

    Note: depends on @dfinity/agent, @dfinity/authentication, and @dfinity/identity.

    Install

    npm i @dfinity/auth-client

    DownloadsWeekly Downloads

    1,580

    Version

    0.12.0

    License

    Apache-2.0

    Unpacked Size

    145 kB

    Total Files

    19

    Last publish

    Collaborators

    • frederikrothenberger
    • bitdivine
    • ielashi
    • liadrit
    • dayyildiz
    • anthony_dfinity
    • eric-swanson-dfinity
    • krpeacock
    • terrorjack
    • npm-dfinity-org