Express Quickstart

Follow the directions below to add Hellō (opens in a new tab) to your Express (opens in a new tab) application in a couple minutes.

You will get the user's name, verified email, and profile picture.
Users can use their preferred login provider including Apple, Facebook, Google, GitHub, GitLab, and Microsoft.
Hellō has done all the work to get a verified email and profile picture.

Add Hellō to Your Server

Don't have a project? Start with the Express application generator (opens in a new tab).

Install the Package

In your project directory:

npm i @hellocoop/express

Run Quickstart

npx @hellocoop/quickstart@latest --express

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:

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

Test Your Server

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

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

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

Log in to Hellō with in a new tab with:
http://localhost:3000/api/hellocoop?op=login (opens in a new tab)
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"
}

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

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

You have added Hellō to your Express application.

Add a Callback Stub

We will now add a stub function that you can modify later to integrate with your user database.

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

// hello-callback.js
module.exports = async ({ 
    payload,    // parsed ID Token payload
    token,      // ID Token in compact, unparsed format
    req,        // HelloRequest
    res         // HelloResponse
}) => {
 
    console.log('Callback received:',JSON.stringify(payload,null,4))
    // TODO
    // lookup user from your DB wth payload.sub user identifier
    // create a user in DB if not found if open registration
    return({
        // accessDenied = true, // will set auth.isLoggedIn = false
        // isProcessed = true,  // response has been sent by callback()
        // updatedAuth = {},    // auth object stored in cookie
    })
}

Configure Callback

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

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

Test the Callback

Restart your server for it to load the updated configuration

http://localhost:3000/api/hellocoop?op=login&target_uri=%2Fapi%2Fhellocoop%3Fauth%3Dtrue (opens in a new tab)

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

You now have a stub you can extend to integrate your user database!

Next Steps

Change the claims received or providers recommended by updating your hello.config.js file.
Review the SDK Reference | Express documentation.
Review the Web Client documentation.
Replace the ./hello-callback.js file with your own code that integrates with your user DB.

Quickstarts Fastify