Merge pull request #4 from passageidentity/users/kf/passage-profile-integration

Add Passage Profile Example

Author: apobletts

01-Login/README.md

@@ -1,4 +1,12 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Passage Next.js Example App
+
+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.
+[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.
+
+## Configure Your Environment Variables
+
+1. Copy the EXAMPLE.env file to your own .env file.
+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).
 
 ## Getting Started
 
@@ -18,17 +26,36 @@ You can start editing the page by modifying `pages/index.js`. The page auto-upda
 
 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.
 
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
+# Using Passage with Next.js
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Importing and Using the Passage-Auth Custom Element
+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:
+```
+npm i --save @passageidentity/passage-elements
+```
+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.
+
+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):
+```javascript
+export default function Home() {
+
+    useEffect(()=>{
+        require('@passageidentity/passage-elements/passage-auth');
+    }, []);
+
+    return (
+        <div>
+            ...
+        </div>
+    )
+}
+```
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+## Getting Authentication Status and User Information with Server-Side Rendering
+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. 
 
-## Deploy on Vercel
+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`.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+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.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+This is done in this example in pages/dashboard.js.

01-Login/package.json

@@ -8,7 +8,7 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@passageidentity/passage-auth": "latest",
+    "@passageidentity/passage-elements": "latest",
     "@passageidentity/passage-node": "^1.2.0",
     "next": "12.0.10",
     "react": "17.0.2",

01-Login/pages/index.js

@@ -2,7 +2,7 @@ import { useEffect } from 'react';
 
 export default function Home({appID}) {
   useEffect(()=>{
-    require('@passageidentity/passage-auth');
+    require('@passageidentity/passage-elements/passage-auth');
   }, []);
 
   return (

01-Login/styles/globals.css

@@ -4,6 +4,7 @@ body {
   margin: 0;
   font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,
     Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+  background-color: #E5E5E5;
 }
 
 a {

02-Login-With-Profile/.eslintrc.json

@@ -0,0 +1,7 @@
+{
+  "extends": "next/core-web-vitals",
+  "rules": {
+    "semi": ["warn", "always"],
+    "semi-style": ["warn", "last"]
+  }
+}

02-Login-With-Profile/.gitignore

@@ -0,0 +1,110 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# Next.js build output
+.next
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and *not* Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# DS_Store file
+.DS_Store
+
+# package-lock
+package-lock.json

02-Login-With-Profile/EXAMPLE.env

@@ -0,0 +1,2 @@
+PASSAGE_APP_ID=
+PASSAGE_API_KEY=

02-Login-With-Profile/README.md

@@ -0,0 +1,72 @@
+# Passage Next.js Example App
+
+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.
+[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.
+
+## Configure Your Environment Variables
+
+1. Copy the EXAMPLE.env file to your own .env file.
+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).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
+
+[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`.
+
+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.
+
+# Using Passage with Next.js
+
+## Importing and Using the Passage Custom Elements
+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:
+```
+npm i --save @passageidentity/passage-elements
+```
+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.
+
+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):
+```javascript
+export default function Home() {
+
+    useEffect(()=>{
+        require('@passageidentity/passage-elements/passage-auth');
+    }, []);
+
+    return (
+        <div>
+            ...
+        </div>
+    )
+}
+```
+
+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:
+```javascript
+function Dashboard({isAuthorized, appID}){
+
+  useEffect(()=>{
+    require('@passageidentity/passage-elements/passage-profile');
+  }, []);
+  
+}
+```
+
+## Getting Authentication Status and User Information with Server-Side Rendering
+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. 
+
+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`.
+
+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.
+
+This is done in this example in pages/dashboard.js.

02-Login-With-Profile/components/banner.js

@@ -0,0 +1,12 @@
+import styles from '../styles/Banner.module.css';
+
+export default function Banner() {
+    return ( 
+        <div className={styles.mainHeader}>
+            <a href="https://passage.id/" ><div className={styles.passageLogo}></div></a>
+            <div className={styles.headerText}>Passage + Next.js Example App</div>
+            <div className={styles.spacer}></div>
+            <a href="https://passage.id/" ><span className={styles.text}>Go to Passage</span></a>
+        </div>
+    );
+}

02-Login-With-Profile/next.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  reactStrictMode: true,
+}

02-Login-With-Profile/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "passage-next-app",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@passageidentity/passage-elements": "latest",
+    "@passageidentity/passage-node": "^1.2.0",
+    "next": "12.0.10",
+    "react": "17.0.2",
+    "react-dom": "17.0.2"
+  },
+  "devDependencies": {
+    "eslint": "8.8.0",
+    "eslint-config-next": "12.0.10"
+  }
+}

02-Login-With-Profile/pages/_app.js

@@ -0,0 +1,20 @@
+import '../styles/globals.css';
+
+import Banner from '../components/banner';
+import styles from '../styles/App.module.css';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <>
+      <Banner></Banner>
+      <div className={styles.mainContainer}>
+        <Component {...pageProps} />
+      </div>
+      <div className={styles.footer}>
+        Learn more with our <u><a href="https://docs.passage.id">Documentation</a></u> and <u><a href="https://github.com/passageidentity">Github</a></u>.
+      </div>
+    </>
+  );
+}
+
+export default MyApp;

02-Login-With-Profile/pages/api/hello.js

@@ -0,0 +1,5 @@
+// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
+
+export default function handler(req, res) {
+  res.status(200).json({ name: 'John Doe' })
+}