@civic/auth

Civic Auth Client SDK

The Civic Auth Client SDK is a powerful and flexible authentication library for React and Next.js applications. It provides a seamless way to integrate Civic's authentication services into your web applications.

Features

• Easy-to-use React hooks and components
• Support for various authentication flows (iframe, redirect, new tab)
• Token management and refresh
• User information retrieval
• Customizable UI components
• TypeScript support

Installation

Install the package using npm or yarn:

npm install @civic/auth

or

yarn add @civic/auth

Usage

First, import the CSS styles in your main application file (e.g., _app.tsx for Next.js):

import "@civic/auth/styles.css";

Setup CivicAuthProvider

To use the Civic Auth Client SDK, wrap your application with the CivicAuthProvider component. This will allow the authentication context to be accessible throughout your app.

import { CivicAuthProvider } from "@civic/auth/react";

function App({ children }) {
  return (
    <CivicAuthProvider clientId="your-client-id" redirectUrl="https://your-app.com/callback">
      {children}
    </CivicAuthProvider>
  );
}

The only required prop for CivicAuthProvider is the clientId. By default, the SDK uses Civic's endpoints. If you need to use your own endpoints, you can provide them using the config prop. See the advanced configuration section below for more details.

Advanced Configuration

If you want to use your own endpoints, you can pass a config object to the CivicAuthProvider as shown below:

import { CivicAuthProvider } from "@civic/auth/react";

function App({ children }) {
  return (
    <CivicAuthProvider
      clientId="your-client-id"
      redirectUrl="https://your-app.com/callback"
      config={{
        endpoints: {
          auth: "https://your-auth-server.com/oauth/auth",
          token: "https://your-auth-server.com/oauth/token",
          userinfo: "https://your-auth-server.com/oauth/userinfo",
        },
      }}
    >
      {children}
    </CivicAuthProvider>
  );
}

Sign In and User Profile

The SDK provides hooks like useAuth and useUser to manage authentication and user information. Below is an example of a profile component that handles signing in and signing out.

import { useAuth, useUser } from "@civic/auth/react";

function Profile() {
  const { isAuthenticated, signIn, signOut } = useAuth();
  const { user } = useUser();

  if (!isAuthenticated) {
    return <button onClick={() => signIn()}>Sign In</button>;
  }

  return (
    <div>
      <h1>Welcome, {user?.name}</h1>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}

UserButton Component

The SDK also includes ready-to-use UI components like UserButton, which provides an easy way to display user information and authentication controls.

import { UserButton } from "@civic/auth/react";

function Header() {
  return (
    <header>
      <h1>My App</h1>
      <UserButton />
    </header>
  );
}

Embedding the login iframe in your page

The default displayMode for user login is 'iframe' which will show a modal containing the login page for users, when the signIn hook is called. If you want to customize where this page is shown and embed it into your page instead i.e. in the case where you have a landing page and don't want users to have to click on a 'sign-in' button, you can embed the login iframe directly inside your page and it will work just like in the modal, as long as it is a child of a . In this mode, the iframe auto-loads the login page.

To enable this mode, you need to set the parameter 'modalIframe' to false (it defaults to true in normal operation).

The example below shows the iframe centered inside a div embedded on the page:

import { CivicAuthProvider } from "@civic/auth/react";

function App({ children }) {
  return (
    <CivicAuthProvider
      clientId="your-client-id"
      redirectUrl="https://your-app.com/callback"
      modalIframe={false}
    >
      {children}
      <div className="flex min-h-[200px] items-center justify-center">
        <CivicAuthIframeContainer />
      </div>
    </CivicAuthProvider>
  );
}

Token Management with useToken Hook

The useToken hook can be used to access and manage tokens within your application. This hook provides the current access and ID tokens, a refresh function, and token loading/error states.

import { useToken } from "@civic/auth/react";

function TokenInfo() {
  const { accessToken, idToken, refreshToken, isLoading, error } = useToken();

  if (isLoading) {
    return <div>Loading tokens...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      <h2>Access Token: {accessToken}</h2>
      <h2>ID Token: {idToken}</h2>
      <button onClick={() => refreshToken()}>Refresh Tokens</button>
    </div>
  );
}

Configuration Options

• clientId: Your application's client ID provided by Civic.
• redirectUrl: (Optional) The URL to which users will be redirected after authentication.
• endpoints: (Optional) Object containing the URLs for the authentication endpoints (auth, token, userinfo). Use this if you want to point to your own authentication server.

Display modes

In order to verify a user's credentials, an auth window is loaded in one of three modes:

iframe

an iframe is overlaid onto the page where the AuthProvider lives, and the Civic auth UI is loaded inside the iframe. When authentication is complete the iframe will disappear.

redirect

the current page is redirecting to the Civic auth UI. When authentication is complete, the page redirects back to the original page.

new_tab

the current page remains open and a new tab is open to show the Civic auth UI. When authentication is complete, the tab is closed.

Note that if a user's browser does not allow popups, then the display mode defaults to 'redirect'.

TypeScript Support

This SDK is fully written in TypeScript, providing type definitions out of the box for a smooth development experience.

License

This project is licensed under the MIT License.