Oktatóanyag: A Microsoft Graph API meghívása egy Node.js konzol démonalkalmazásban

Cikk
07/04/2024

Ebben az oktatóanyagban egy konzoldémonalkalmazást hoz létre, amely saját identitásával hívja meg a Microsoft Graph API-t. A buildelt démonalkalmazás a Microsoft Authentication Library (MSAL) használatával Node.js.

Kövesse az oktatóanyag lépéseit a következőkhöz:

Az alkalmazás regisztrálása az Azure Portalon
Node.js konzol démonalkalmazás-projekt létrehozása
Hitelesítési logika hozzáadása az alkalmazáshoz
Alkalmazásregisztráció részleteinek hozzáadása
Metódus hozzáadása webes API meghívásához
Az alkalmazás tesztelése

Előfeltételek

Node.js
Visual Studio Code vagy más kódszerkesztő

Az alkalmazás regisztrálása

Először végezze el az alkalmazás regisztrálásához szükséges lépéseket az alkalmazás regisztrálásához az Microsoft Identitásplatform.

Az alkalmazásregisztrációhoz használja az alábbi beállításokat:

Név: NodeDaemonApp (javasolt)
Támogatott fióktípusok: Csak ebben a szervezeti címtárban lévő fiókok
API-engedélyek: Microsoft API-k>Microsoft Graph-alkalmazásengedélyek>>User.Read.All
Titkos ügyfélkód: ********* (ezt az értéket egy későbbi lépésben rögzítheti – csak egyszer jelenik meg)

A projekt létrehozása

Először hozzon létre egy könyvtárat ehhez a Node.js oktatóanyag-projekthez. Például a NodeDaemonApp.
A terminálban váltson a létrehozott könyvtárra (a projekt gyökérkönyvtárára), majd futtassa a következő parancsokat:
```
npm init -y
npm install --save dotenv yargs axios @azure/msal-node
```
Ezután szerkessze a package.json fájlt a projekt gyökerében, és az előtag main értékét bin/a következőhöz hasonlóan:
```
"main": "bin/index.js",
```

Most hozza létre a bin könyvtárat, és a tárolón belül adja hozzá a következő kódot egy index.js nevű új fájlhoz:

#!/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();

Az imént létrehozott index.js fájl két másik csomópontmodulra hivatkozik, amelyeket a következő lépésben fog létrehozni:

auth.js – MSAL-csomópontot használ a hozzáférési jogkivonatok beszerzéséhez a Microsoft Identitásplatform.
fetch.js – Adatokat kér le a Microsoft Graph API-ból a (auth.js-ben beszerzett) hozzáférési jogkivonatok beiktatásával az API-nak küldött HTTP-kérésekben.

Az oktatóanyag végén a projekt fájl- és könyvtárstruktúrájának az alábbihoz hasonlóan kell kinéznie:

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

Hitelesítési logika hozzáadása

A bin könyvtárban adja hozzá a következő kódot egy auth.js nevű új fájlhoz. A auth.js kód egy hozzáférési jogkivonatot szerez be a Microsoft Identitásplatform a Microsoft Graph API-kérésekbe való beleféréshez.

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
};

A fenti kódrészletben először létrehozunk egy konfigurációs objektumot (msalConfig), majd átadjuk egy MSAL ConfidentialClientApplication inicializálásához. Ezután létrehozunk egy módszert a jogkivonatok ügyfél-hitelesítő adatokon keresztüli beszerzésére, és végül elérhetővé tesszük ezt a modult, amelyet a main.js érhet el. A modul konfigurációs paraméterei egy környezeti fájlból származnak, amelyet a következő lépésben fogunk létrehozni.

Alkalmazásregisztráció részleteinek hozzáadása

Hozzon létre egy környezeti fájlt a jogkivonatok beszerzésekor használt alkalmazásregisztrációs adatok tárolásához. Ehhez hozzon létre egy .env nevű fájlt a minta gyökérmappájában (NodeDaemonApp), és adja hozzá a következő kódot:

# 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/

Töltse ki ezeket a részleteket az Azure alkalmazásregisztrációs portálról beszerzett értékekkel:

Enter_the_Tenant_Id_here az alábbiak egyikének kell lennie:
- Ha az alkalmazás támogatja a szervezeti címtárban lévő fiókokat, cserélje le ezt az értéket a bérlőazonosítóra vagy a bérlő nevére. Például: contoso.microsoft.com.
- Ha az alkalmazás bármely szervezeti könyvtárban támogatja a fiókokat, cserélje le ezt az értéket a következőreorganizations: .
- Ha az alkalmazás bármely szervezeti címtárban és személyes Microsoft-fiókban támogatja a fiókokat, cserélje le ezt az értéket a következőre common: .
- Ha csak a személyes Microsoft-fiókok támogatását szeretné korlátozni, cserélje le ezt az értéket consumersa gombra.
Enter_the_Application_Id_Here: A regisztrált alkalmazás (ügyfél) azonosítója .
Enter_the_Cloud_Instance_Id_Here: Az az Azure-felhőpéldány, amelyben az alkalmazás regisztrálva van.
- A fő (vagy globális) Azure-felhőbe írja be a következőt https://login.microsoftonline.com: .
- A nemzeti felhők (például Kína) esetében a nemzeti felhőkben megtalálhatja a megfelelő értékeket.
Enter_the_Graph_Endpoint_Here a Microsoft Graph API azon példánya, amellyel az alkalmazásnak kommunikálnia kell.
- A globális Microsoft Graph API-végpont esetében cserélje le a sztring mindkét példányát a következőrehttps://graph.microsoft.com: .
- Az országos felhőbeli üzemelő példányok végpontjait a Microsoft Graph dokumentációjában találja.

Metódus hozzáadása webes API meghívásához

A bin mappában hozzon létre egy fetch.js nevű fájlt, és adja hozzá a következő kódot a REST-hívások Microsoft Graph API-hoz való indításához:

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
};

Itt a callApi metódussal HTTP-kérést GET lehet küldeni egy olyan védett erőforrásra, amely hozzáférési jogkivonatot igényel. A kérés ezután visszaadja a tartalmat a hívónak. Ez a metódus hozzáadja a beszerzett jogkivonatot a HTTP-engedélyezési fejléchez. A védett erőforrás itt a Microsoft Graph API felhasználói végpontja , amely azon bérlő felhasználóit jeleníti meg, ahol az alkalmazás regisztrálva van.

Az alkalmazás tesztelése

Befejezte az alkalmazás létrehozását, és készen áll az alkalmazás működésének tesztelésére.

Indítsa el a Node.js konzol démonalkalmazást a következő parancs futtatásával a projektmappában:

node . --op getUsers

Ennek jSON-választ kell adnia a Microsoft Graph API-nak, és a konzolon felhasználói objektumok tömbjének kell megjelennie:

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'
        }
    ]
}

A Graph-választ megjelenítő parancssori felület

Az alkalmazás működése

Ez az alkalmazás az OAuth 2.0 ügyfél hitelesítő adatainak megadását használja. Ez az engedélytípus általában olyan kiszolgálóközi interakciók esetén használatos, amelyeknek a felhasználóval való azonnali interakció nélkül, a háttérben kell futniuk. A hitelesítő adatok lehetővé teszik, hogy egy webszolgáltatás (bizalmas ügyfél) saját hitelesítő adatait használja ahelyett, hogy megszemélyesítenének egy felhasználót, hogy hitelesítést végezzen egy másik webszolgáltatás hívásakor. Az ezzel a hitelesítési modellel támogatott alkalmazások típusa általában démonok vagy szolgáltatásfiókok.

Az ügyfél hitelesítő adatainak lekérésére szolgáló hatókör az erőforrás neve, amelyet a következő követ /.default: . Ez a jelölés arra utasítja a Microsoft Entra-azonosítót, hogy az alkalmazásregisztráció során statikusan deklarált alkalmazásszintű engedélyeket használja. Ezeket az API-engedélyeket egy bérlői rendszergazdának kell megadnia.

Következő lépések

Ha részletesebben szeretne megismerkedni Node.js démonalkalmazás-fejlesztéssel a Microsoft Identitásplatform, tekintse meg többrészes forgatókönyv-sorozatunkat:

Forgatókönyv: Démonalkalmazás

Megosztás a következőn keresztül: