Fastify Quickstart

Install the Package

In your project directory:

npm i @hellocoop/fastify

pnpm add @hellocoop/fastify

yarn add @hellocoop/fastify

bun add @hellocoop/fastify

Run Quickstart

npx @hellocoop/quickstart@latest --fastify

Quickstart will prompt you to:

• download the @hellocoop/quickstart package
• log in to Quickstart with Hellō
• create an application, or select an existing one

Quickstart will then:

• create a hello.config.js file containing your app’s client_id
• generate a random HELLO_COOKIE_SECRET and add it to .env

Mount Hellō

In your main server file add the following code:

import fastify from 'fastify'
import helloConfig from '../hello.config.js' // adjust path as needed
import { helloAuth } from '@hellocoop/fastify'
 
fastify.register(helloAuth, helloConfig)
 

const fastify = require('fastify')
const { helloAuth } = require('@hellocoop/fastify')
const helloConfig = require('../hello.config.js') // adjust path as needed
 
fastify.register(helloAuth, helloConfig)
 

Your server should now be fully configured to work with Hellõ

Test Your Server

Start your server. Assuming the server started on port 3000:

1. Check your logged in status in a new tab with:
   http://localhost:3000/api/hellocoop?op=auth 

You should get {"isLoggedIn": false} in your browser window.

2. Log in to Hellō with in a new tab with:
   http://localhost:3000/api/hellocoop?op=login 

3. See your logged in status and profile by reloading /api/hellocoop?op=auth

You should see something similar to this:

{
  "isLoggedIn": true,
  "sub": "sub_vvCgtpv35lDgQpHtxmpvmnxK_2nZ",
  "iat": 1699234659,
  "name": "Dick Hardt",
  "picture": "https://pictures.hello.coop/r/7a160eed-46bf-48e2-a909-161745535895.png",
  "email": "dick.hardt@hello.coop"
}

4. Log out in a new tab with:
   http://localhost:3000/api/hellocoop?op=logout&target_uri=%2Fapi%2Fhellocoop%3Fauth%3Dtrue 

After being logged out, you will be redirected back to /api/hellocoop?op=auth to confirm you are logged out.

Create Callback Stub

Copy the following code and save it to hello-callback.js in your root folder (you can move it later):

// hello-callback.js
module.exports = async ({ 
    token,      // ID Token in compact, unparsed format
    payload,    // parsed ID Token payload
    target_uri, // target URI for redirect
    req,        // FastifyRequest
    res         // FastifyReply
}) => {
 
    console.log('LoginSync received:',JSON.stringify(payload,null,4))
    // TODO
    // lookup user from your DB with payload.sub user identifier
    // create a user in DB if not found if open registration
    return({
        // accessDenied: true, // will set auth.isLoggedIn = false
        // target_uri: '/custom-redirect', // override redirect URI
        // updatedAuth: {}, // auth object stored in cookie
    })
}

Configure Callback

Add the highlighted lines to your hello.config.js file:

const loginSync = require('./hello-callback')
 
const config = {
    client_id: 'YOUR_CLIENT_ID',
    loginSync
}
module.exports = config

Test the Callback

1. Restart your server for it to load the updated configuration

http://localhost:3000/api/hellocoop?op=login&target_uri=%2Fapi%2Fhellocoop%3Fauth%3Dtrue 

You should see the contents of the ID Token payload logged to your terminal. See OpenID Connect | ID Token for details.