Home / IBM Verify SDK for Javascript / Quickstart Guides / Device Flow / Getting Started

Quickstart (Node.js)

The following page will guide you through getting started with the Device Flow grant type by creating a CLI (Command Line Interface) example program.

Initialise a node package

npm init -y

The -y flag uses the default configuration.

Dependencies

ibm-verify-sdk - the sdk
dotenv - for loading the OAuth configuration through your .env file

npm install ibm-verify-sdk dotenv

.env

The recommended way of storing the OAuth configuration is in a file named .env, this way the values are not hard coded into the source. Using the node package dotenv we can load the contents of the file into the application environment variables.

An example configuration.

TENANT_URL=https://your-tenant-name.ibmcloud.com
CLIENT_ID=a1b2c3d4-abcd-1234-1337-itsanexample
CLIENT_SECRET=QwErTYasdf
FLOW_TYPE=device
SCOPE=openid

device-sample.js

Create the file device-sample.js, this will be the actual program file in which you add the following code.

Imports

const OAuthContext = require('ibm-verify-sdk').OAuthContext;
const fs = require('fs');

Load config

// load contents of .env into process.env
require('dotenv').config();

let config = {
    tenantUrl    : process.env.TENANT_URL,
    clientId     : process.env.CLIENT_ID,
    clientSecret : process.env.CLIENT_SECRET, // If using a Private Client
    flowType     : process.env.FLOW_TYPE,
    scope        : process.env.SCOPE
};

Instantiate OAuthContext with given config, returning a Device Flow OAuthContext

const dFlowCtx = new OAuthContext(config);

Call the authorize function on your Device Flow OAuthContext object to initialise the authorization process

The promise should resolve to an object containing, among other properties, a verification uri and a user code. Then call the pollTokenApi function on your Device Flow OAuthContext, this will poll the token API for confirmation that you have completed the authorization by visiting the verification_uri and entered your user_code.

Note: when entering your user code at the verification uri, please ensure that when prompted you sign in as an entitled user of this application.

dFlowCtx.authorize().then(
    res => {
        console.log(`\nTo authorize, visit:\n    ${res.verification_uri}\nThen input your user code:\n    ${res.user_code}`);
        console.log('This program will now poll the token API until authorization is complete...');

        // Poll the token API while the user completes the authorization process
        dFlowCtx.pollTokenApi(res.device_code).then(
            poll_response => console.log('Polling complete, you have successfully completed authorization.\n'),
            rej => console.log('Polling failed, error: ', rej)
        );
    }, rej => {
        console.log('Failed to authorize the Device Flow OAuth context. Error: ', rej);
    }
);

Experiment with QR Code functionality

If your application has generateDeviceFlowQrCode enabled, a QR code will be returned alongside your verifcation_uri and user_id. This QR code can be scanned in place of visiting the verification_uri.

Experiment with this by adjusting the function you used above, as below. The following code will save the generated QR code as a .png file on your local system, the program will prompt you when to open this file and scan the QR code.

dFlowCtx.authorize().then(
    res => {
        // Extract the QR code from res.verification_uri_complete_qrcode
        // The QR code will be sent as base64, using fs.writeFile this can be converted and saved locally as a .png file
        fs.writeFile(
            'qrCode.png', 
            res.verification_uri_complete_qrcode, 
            'base64', 
            (err) => {
                if(err){
                    console.log('Failed to save QR Code, error: ', err);
                    process.exit();
                } else {
                    console.log('\nSuccessfully retrieved QR Code.\n');
                    console.log('Open the file qrCode.png that is saved in this folder and use the IBM Verify Mobile app to scan the image.\n');
                    console.log('Alternatively, to manually authorize via code input visit: ');
                    console.log(`    ${res.verification_uri}`);
                    console.log('Then input your user code:');
                    console.log(`    ${res.user_code}\n`);
                    console.log('This program will now poll the token API until authorization is complete...\n');
                }
            });

        // Poll the token API while the user completes the authorization process
        dFlowCtx.pollTokenApi(res.device_code).then(
            poll_response => console.log('Polling complete, you have successfully completed authorization.\n'),
            rej => console.log('Polling failed, error: ', rej)
        );

    }, rej => {
        console.log('Failed to authorize the Device Flow OAuth context. Error: ', rej);
    }
);