@wristband/passport-wristband v1.0.2

Wristband Multi-Tenant Authentication Strategy SDK for Passport

Wristband authentication strategy for Passport.

This module lets you authenticate through Wristband.dev with its supported IDPs in your Node.js applications. By plugging into Passport, Wristband will support login, authorize, callback, sessionStore, token management

How to setup a demo app with Wristband What does wristband offer

Install

$ npm install passport-wristband

Usage

Configure Strategy

The Wristband authentication strategy authenticates users using a wristband account credential to obtain access, refresh tokens, and user profile. The strategy requires a callback, which receives an access token and profile, and calls the callback function providing a req.user object with tokens, user profile and more.

• Auth Flow Walkthrough.
• Login Workflow In Depth

passport.use(new WristbandStrategy({
        clientId: 'qoblahblahblahblahprw6u',
        clientSecret: 'a8blahblahblahblahblahblahblahcd',
        callbackUrl: 'http://localhost:8080/api/auth/callback',
        wristbandApplicationDomain: 'testdomain.wristband.dev',
    },
    function (accessToken, refreshToken, idToken, params, profile, done) {
        const expiresAt = calculateExpTimeWithBuffer(params.expires_in);
        done(null, { 'expiresAt': expiresAt, 'accessToken': accessToken, 'refreshToken': refreshToken, 'idToken': idToken, 'profile': profile, 'userId': profile.sub
            , 'tenantId' : profile.tnt_id, 'identityProviderName': profile.idp_name, 'returnUrl': params.return_url});
    }
));

Adveanced Strategy Configuration

passport.use(new WristbandStrategy({
        clientId: 'qoblahblahblahblahprw6u',
        clientSecret: 'a8blahblahblahblahblahblahblahcd',
        callbackUrl: 'http://{tenant_domain}.invotastic.com/api/auth/callback',
        rootDomain : 'invotastic.com',
        useCustomDomains: true,
        useTenantSubdomains: true,
        wristbandApplicationDomain: 'auth.invotastic.com',
    },
    function (accessToken, refreshToken, idToken, params, profile, done) {
        const expiresAt = calculateExpTimeWithBuffer(params.expires_in);
        done(null, { 'expiresAt': expiresAt, 'accessToken': accessToken, 'refreshToken': refreshToken, 'idToken': idToken, 'profile': profile, 'userId': profile.sub
            , 'tenantId' : profile.tnt_id, 'identityProviderName': profile.idp_name, 'returnUrl': params.return_url});
    }
));

Authenticate Requests

Use passport.authenticate(), specifying the 'wristband' strategy, to authenticate requests. Use router to ensure login and callback routes to authenticate through Wristband.

For example, as route middleware in an Express application:

[Passport session setup](https://www.passportjs.org/concepts/authentication/sessions/) 

passport.serializeUser((user, done) => {
    done(null, user);
});

passport.deserializeUser((user, done) => {
    return done(null, user); 
});

router.get('/login', passport.authenticate('wristband'));

router.get('/callback', passport.authenticate('wristband', {failureRedirect: '/login'}),
    function (req, res) {
        // Successful authentication, redirect returnUrl or homepage.
        if(req.user && req.user.returnUrl){
            return res.redirect(req.user.returnUrl);
        }else{
            return res.redirect(`http://invotastic.com/home`);
        }
    });

Wristband Auth Configuration Options

Login Hint

Wristband will redirect to your Express Login Endpoint for workflows like Application-Level Login (Tenant Discovery) and can pass the login_hint query parameter as part of the redirect request:

GET https://customer01.yourapp.io/auth/login?login_hint=user@wristband.dev

If Wristband passes this parameter, it will be appended as part of the redirect request to the Wristband Authorize Endpoint. Typically, the email form field on the Tenant-Level Login page is pre-filled when a user has previously entered their email on the Application-Level Login Page.

Return URL

It is possible that users will try to access a location within your application that is not some default landing page. In those cases, they would expect to immediately land back at that desired location after logging in. This is a better experience for the user, especially in cases where they have application URLs bookmarked for convenience. Given that your frontend will redirect users to your Express Login Endpoint, you can pass a return_url query parameter when redirecting to your Login Endpoint, and that URL will be available to you upon completion of the Callback Endpoint.

GET https://customer01.yourapp.io/auth/login?return_url=https://customer01.yourapp.io/settings/profile

Test

$ npm run test-with-coverage

Contributing

License

The MIT License https://www.wristband.dev/

Copyright (c) 2024 Apitopia, Inc.