Dela via

Självstudie: Anropa Microsoft Graph API i en Daemon-app för Node.js-konsolen

  • Artikel

I den här självstudien skapar du en konsol daemon-app som anropar Microsoft Graph API med sin egen identitet. Daemon-appen som du skapar använder Microsoft Authentication Library (MSAL) för Node.js.

Följ stegen i den här självstudien för att:

  • Registrera programmet i Azure-portalen
  • Skapa ett Daemon-appprojekt för Node.js-konsolen
  • Lägga till autentiseringslogik i din app
  • Lägga till appregistreringsinformation
  • Lägga till en metod för att anropa ett webb-API
  • Testa appen

Förutsättningar

Registrera programmet

Slutför först stegen i Registrera ett program med Microsofts identitetsplattform för att registrera din app.

Använd följande inställningar för din appregistrering:

  • Namn: NodeDaemonApp (föreslås)
  • Kontotyper som stöds: Endast konton i den här organisationskatalogen
  • API-behörigheter: Microsoft API:er>Microsoft Graph-programbehörigheter>>User.Read.All
  • Klienthemlighet: ********* (registrera det här värdet för användning i ett senare steg – det visas bara en gång)

Skapa projektet

  1. Börja med att skapa en katalog för det här node.js-självstudieprojektet. Till exempel NodeDaemonApp.

  2. I terminalen ändrar du till katalogen du skapade (projektroten) och kör sedan följande kommandon:

    npm init -y
npm install --save dotenv yargs axios @azure/msal-node

  3. Redigera sedan filen package.json i projektroten och prefixet värdet main för med bin/, så här:

    "main": "bin/index.js",

  4. Skapa nu bin-katalogen och lägg till följande kod i en ny fil med namnet index.js:

    #!/usr/bin/env node

// read in env settings
require('dotenv').config();

const yargs = require('yargs');

const fetch = require('./fetch');
const auth = require('./auth');

const options = yargs
    .usage('Usage: --op <operation_name>')
    .option('op', { alias: 'operation', describe: 'operation name', type: 'string', demandOption: true })
    .argv;

async function main() {
    console.log(`You have selected: ${options.op}`);

    switch (yargs.argv['op']) {
        case 'getUsers':

            try {
                // here we get an access token
                const authResponse = await auth.getToken(auth.tokenRequest);

                // call the web API with the access token
                const users = await fetch.callApi(auth.apiConfig.uri, authResponse.accessToken);

                // display result
                console.log(users);
            } catch (error) {
                console.log(error);
            }

            break;
        default:
            console.log('Select a Graph operation first');
            break;
    }
};

main();

Den index.js-fil som du nyss skapade refererar till två andra nodmoduler som du skapar härnäst:

  • auth.js – Använder MSAL Node för att hämta åtkomsttoken från Microsofts identitetsplattform.
  • fetch.js – Begär data från Microsoft Graph API genom att inkludera åtkomsttoken (hämtas i auth.js) i HTTP-begäranden till API:et.

I slutet av självstudien bör projektets fil- och katalogstruktur se ut ungefär så här:

NodeDaemonApp/
├── bin
│   ├── auth.js
│   ├── fetch.js
│   ├── index.js
├── package.json
└── .env

Lägga till autentiseringslogik

I bin-katalogen lägger du till följande kod i en ny fil med namnet auth.js. Koden i auth.js hämtar en åtkomsttoken från Microsofts identitetsplattform för att inkludera i Microsoft Graph API-begäranden.

const msal = require('@azure/msal-node');

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + '/' + process.env.TENANT_ID,
        clientSecret: process.env.CLIENT_SECRET,
    }
};

/**
 * With client credentials flows permissions need to be granted in the portal by a tenant administrator.
 * The scope is always in the format '<resource>/.default'. For more, visit:
 * https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
 */
const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '/.default'],
};

const apiConfig = {
    uri: process.env.GRAPH_ENDPOINT + '/v1.0/users',
};

/**
 * Initialize a confidential client application. For more info, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-confidential-client-application.md
 */
const cca = new msal.ConfidentialClientApplication(msalConfig);

/**
 * Acquires token with client credentials.
 * @param {object} tokenRequest
 */
async function getToken(tokenRequest) {
    return await cca.acquireTokenByClientCredential(tokenRequest);
}

module.exports = {
    apiConfig: apiConfig,
    tokenRequest: tokenRequest,
    getToken: getToken
};

I kodfragmentet ovan skapar vi först ett konfigurationsobjekt (msalConfig) och skickar det för att initiera en MSAL ConfidentialClientApplication. Sedan skapar vi en metod för att hämta token via klientautentiseringsuppgifter och slutligen exponerar vi den här modulen för åtkomst av main.js. Konfigurationsparametrarna i den här modulen hämtas från en miljöfil som vi skapar i nästa steg.

Lägga till appregistreringsinformation

Skapa en miljöfil för att lagra den appregistreringsinformation som ska användas vid anskaffning av token. Det gör du genom att skapa en fil med namnet .env i rotmappen i exemplet (NodeDaemonApp) och lägga till följande kod:

# Credentials
TENANT_ID=Enter_the_Tenant_Id_Here
CLIENT_ID=Enter_the_Application_Id_Here
CLIENT_SECRET=Enter_the_Client_Secret_Here

# Endpoints
AAD_ENDPOINT=Enter_the_Cloud_Instance_Id_Here/
GRAPH_ENDPOINT=Enter_the_Graph_Endpoint_Here/

Fyll i den här informationen med de värden som du får från Azure-appregistreringsportalen:

  • Enter_the_Tenant_Id_here bör vara något av följande:
    • Om ditt program stöder konton i den här organisationskatalogen ersätter du det här värdet med klientorganisations-ID:t eller klientorganisationens namn. Exempel: contoso.microsoft.com
    • Om ditt program stöder konton i en organisationskatalog ersätter du det här värdet med organizations.
    • Om ditt program stöder konton i en organisationskatalog och personliga Microsoft-konton ersätter du det här värdet med common.
    • Om du bara vill begränsa stödet till personliga Microsoft-konton ersätter du det här värdet med consumers.
  • Enter_the_Application_Id_Here: Program-ID :t (klient) för det program som du registrerade.
  • Enter_the_Cloud_Instance_Id_Here: Azure-molninstansen där ditt program är registrerat.
    • För det huvudsakliga (eller globala) Azure-molnet anger du https://login.microsoftonline.com.
    • För nationella moln (till exempel Kina) kan du hitta lämpliga värden i nationella moln.
  • Enter_the_Graph_Endpoint_Here är instansen av Microsoft Graph API som programmet ska kommunicera med.
    • För den globala Microsoft Graph API-slutpunkten ersätter du båda instanserna av den här strängen med https://graph.microsoft.com.
    • Slutpunkter i nationella molndistributioner finns i Nationella molndistributioner i Microsoft Graph-dokumentationen.

Lägga till en metod för att anropa ett webb-API

I mappen bin skapar du en annan fil med namnet fetch.js och lägger till följande kod för att göra REST-anrop till Microsoft Graph API:

const axios = require('axios');

/**
 * Calls the endpoint with authorization bearer token.
 * @param {string} endpoint
 * @param {string} accessToken
 */
async function callApi(endpoint, accessToken) {

    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log('request made to web API at: ' + new Date().toString());

    try {
        const response = await axios.get(endpoint, options);
        return response.data;
    } catch (error) {
        console.log(error)
        return error;
    }
};

module.exports = {
    callApi: callApi
};

callApi Här används metoden för att göra en HTTP-begäran GET mot en skyddad resurs som kräver en åtkomsttoken. Begäran returnerar sedan innehållet till anroparen. Den här metoden lägger till den förvärvade token i HTTP-auktoriseringshuvudet. Den skyddade resursen här är Microsoft Graph API-användarslutpunkten som visar användarna i klientorganisationen där den här appen är registrerad.

Testa appen

Du har slutfört skapandet av programmet och är nu redo att testa appens funktioner.

Starta daemonappen node.js-konsolen genom att köra följande kommando från roten i projektmappen:

node . --op getUsers

Detta bör resultera i ett JSON-svar från Microsoft Graph API och du bör se en matris med användarobjekt i konsolen:

You have selected: getUsers
request made to web API at: Fri Jan 22 2021 09:31:52 GMT-0800 (Pacific Standard Time)
{
    '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
    value: [
        {
            displayName: 'Adele Vance'
            givenName: 'Adele',
            jobTitle: 'Retail Manager',
            mail: 'AdeleV@msaltestingjs.onmicrosoft.com',
            mobilePhone: null,
            officeLocation: '18/2111',
            preferredLanguage: 'en-US',
            surname: 'Vance',
            userPrincipalName: 'AdeleV@msaltestingjs.onmicrosoft.com',
            id: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'
        }
    ]
}

Command-line interface displaying Graph response

Så här fungerar programmet

Det här programmet använder OAuth 2.0-klientautentiseringsuppgifter. Den här beviljandetypen används ofta för server-till-server-interaktioner som måste köras i bakgrunden, utan direkt interaktion med en användare. Autentiseringsuppgifterna beviljar flödet tillåter en webbtjänst (konfidentiell klient) att använda sina egna autentiseringsuppgifter, i stället för att personifiera en användare, för att autentisera när den anropar en annan webbtjänst. Den typ av program som stöds med den här autentiseringsmodellen är vanligtvis daemoner eller tjänstkonton.

Omfånget för att begära ett flöde för klientautentiseringsuppgifter är namnet på resursen följt av /.default. Den här notationen instruerar Microsoft Entra-ID:t att använda de behörigheter på programnivå som deklareras statiskt under programregistreringen. Dessa API-behörigheter måste också beviljas av en klientadministratör.

Nästa steg

Om du vill gå djupare in på Node.js daemon-programutveckling på Microsofts identitetsplattform kan du läsa vår serie med flerdelade scenarion:

Scenario: Daemon-program