|
1 | | -# Passage Next.js Example App |
| 1 | +# Passage + Next.js Examples |
| 2 | +This repository contains Next.js examples for different use cases with Passage. |
2 | 3 |
|
3 | | -This example application uses the [Passage Auth Element](https://www.npmjs.com/package/@passageidentity/passage-elements) in a Next.js application to authenticate users using biometrics or magic links. |
4 | | -[Passage Node.js SDK](https://www.npmjs.com/package/@passageidentity/passage-node) is used to verify users on authenticated endpoints. To run this example application, follow the instructions below. |
| 4 | +# What is Passage |
| 5 | +Passage is a passwordless authentication system that leverages biometrics (with a fallback of magic links) to authenticate users on your websites or mobile applications. By leveraging the [WebAuthn protocol](https://webauthn.io/) from the [FIDO Alliance](https://fidoalliance.org/), Passage can increase security and reduce end user friction. |
5 | 6 |
|
6 | | -## Configure Your Environment Variables |
| 7 | +Passage provides a full UI/UX login and registration in a web component that can be added to any application, as well as backend libraries in Python, Go, and Node.js to support user verification. To learn more [visit our website](https://passage.id). |
7 | 8 |
|
8 | | -1. Copy the EXAMPLE.env file to your own .env file. |
9 | | -2. Replace the example variables with your own Passage App ID and API Key. You can get these from the [Passage Console](https://console.passage.id). The App ID is found on the main Dashboard page, and the API Key can be created and retrieved from the `Setting/API Keys` page. **Note that both are required.** |
10 | 9 |
|
11 | | -## Getting Started |
| 10 | +# Examples in This Repo |
12 | 11 |
|
13 | | -First, run the development server: |
| 12 | +This repository contains two examples: |
14 | 13 |
|
15 | | -```bash |
16 | | -npm run dev |
17 | | -# or |
18 | | -yarn dev |
19 | | -``` |
| 14 | +* [Authenticating with Passage](./01-Login) -- a simple example implementing passwordless authentication |
| 15 | +* [Login with Profile](./02-Login-With-Profile) -- an example using passwordless authentication that displays information about registered devices |
20 | 16 |
|
21 | | -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. |
22 | | - |
23 | | -You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file. |
24 | | - |
25 | | -[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.js`. |
26 | | - |
27 | | -The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages. |
28 | | - |
29 | | -# Using Passage with Next.js |
30 | | - |
31 | | -## Importing and Using the Passage Custom Elements |
32 | | -The easiest way to add authentication to a web frontend is with a Passage Auth custom element. First you'll need to install the [passage-elements](https://www.npmjs.com/package/@passageidentity/passage-elements) package from npm: |
33 | | -``` |
34 | | -npm i --save @passageidentity/passage-elements |
35 | | -``` |
36 | | -Importing `@passageidentity/passage-elements/passage-auth` triggers a side-effect that will register the passage-auth custom element with the client browser for usage. Since Next.js pre-renders pages on the server this presents a common issue with using web components, such as the Passage elements, in pre-rendered pages - when the server side pre-render occurs there is no client window defined to call `window.customElements.define()` on, which results in an error being thrown. |
37 | | - |
38 | | -The most common solution when using custom elements in pre-rendered applications is to defer the registration of the custom element to a lifecycle hook so that the code is only executed when the client app is executed in browser. This is done in this example in [pages/index.js](https://github.com/passageidentity/example-nextjs/blob/main/pages/index.js): |
39 | | -```javascript |
40 | | -export default function Home() { |
41 | | - |
42 | | - useEffect(()=>{ |
43 | | - require('@passageidentity/passage-elements/passage-auth'); |
44 | | - }, []); |
45 | | - |
46 | | - return ( |
47 | | - <div> |
48 | | - ... |
49 | | - </div> |
50 | | - ) |
51 | | -} |
52 | | -``` |
53 | | - |
54 | | -Similarly for the dashboard in this example we use the passage-profile element to display user information. The profile element is imported in the same way the auth element is imported: |
55 | | -```javascript |
56 | | -function Dashboard({isAuthorized, appID}){ |
57 | | - |
58 | | - useEffect(()=>{ |
59 | | - require('@passageidentity/passage-elements/passage-profile'); |
60 | | - }, []); |
61 | | - |
62 | | -} |
63 | | -``` |
64 | | - |
65 | | -## Getting Authentication Status and User Information with Server-Side Rendering |
66 | | -After the user has logged in with Passage, all requests need to be authenticated using the JWT provided by Passage. The [Passage Node.js SDK](https://www.npmjs.com/package/@passageidentity/passage-node) to authenticate requests and retrieve user data for your application. |
67 | | - |
68 | | -In this example, we handle authentication securely in Next.js's server-side rendering function [`getServerSideProps()`](https://nextjs.org/docs/basic-features/data-fetching#getserversideprops-server-side-rendering). Per Next.js documention you can import modules in top-level scope for use in `getServerSideProps`. Imports used in `getServerSideProps` will not be bundled for the client-side. This means you can write server-side code directly in `getServerSideProps`. |
69 | | - |
70 | | -The JWT provided by Passage is stored in both cookies and localstorage. Next.js provides the cookies set for an application to `getServerSideProps` which allows passing the JWT from the client browser to the server to handle authentication. |
71 | | - |
72 | | -This is done in this example in pages/dashboard.js. |
| 17 | +We have posted a blog entry describing [how these demos can be built from scratch](https://passage.id/post/building-a-next-js-app-with-biometrics). |
0 commit comments