Kurz: Volání rozhraní Microsoft Graph API v aplikaci démon konzoly Node.js

Článek
04/09/2024

V tomto kurzu vytvoříte aplikaci démon konzoly, která volá rozhraní Microsoft Graph API pomocí vlastní identity. Aplikace démona, kterou sestavíte, používá knihovnu MSAL (Microsoft Authentication Library) pro Node.js.

Postupujte podle kroků v tomto kurzu:

Registrace aplikace na webu Azure Portal
Vytvoření projektu démona konzoly Node.js
Přidání logiky ověřování do aplikace
Přidání podrobností o registraci aplikace
Přidání metody pro volání webového rozhraní API
Otestování aplikace

Požadavky

Node.js
Visual Studio Code nebo jiný editor kódu

Registrace aplikace

Nejprve proveďte kroky v části Registrace aplikace na platformě Microsoft Identity Platform a zaregistrujte aplikaci.

Pro registraci aplikace použijte následující nastavení:

Název: NodeDaemonApp (navrhované)
Podporované typy účtů: Účty pouze v tomto organizačním adresáři
Oprávnění rozhraní API: Microsoft APIs>Microsoft Graph>Application Permissions>User.Read.All
Tajný klíč klienta: ********* (poznamenejte si tuto hodnotu pro použití v pozdějším kroku – zobrazí se jenom jednou).

Vytvoření projektu

Začněte vytvořením adresáře pro tento projekt kurzu Node.js. Například NodeDaemonApp.
V terminálu přejděte do adresáře, který jste vytvořili (kořen projektu) a spusťte následující příkazy:
```
npm init -y
npm install --save dotenv yargs axios @azure/msal-node
```
Dále upravte soubor package.json v kořenovém adresáři projektu a předponu hodnoty s následujícím main kódem bin/:
```
"main": "bin/index.js",
```

Teď vytvořte adresář bin a do přihrádky přidejte do nového souboru s názvem index.js následující kód:

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

Soubor index.js , který jste právě vytvořili, odkazuje na dva další moduly uzlu, které vytvoříte dále:

auth.js – používá uzel MSAL k získání přístupových tokenů z platformy Microsoft Identity Platform.
fetch.js – Vyžaduje data z rozhraní Microsoft Graph API zahrnutím přístupových tokenů (získaných v auth.js) v požadavcích HTTP na rozhraní API.

Na konci kurzu by měla struktura souborů a adresářů projektu vypadat nějak takto:

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

Přidání logiky ověřování

Do adresáře bin přidejte následující kód do nového souboru s názvem auth.js. Kód v auth.js získá přístupový token z platformy Microsoft Identity Platform pro zahrnutí do požadavků rozhraní Microsoft Graph API.

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

Ve výše uvedeném fragmentu kódu nejprve vytvoříme objekt konfigurace (msalConfig) a předáme ho inicializaci MSAL ConfidentialClientApplication. Pak vytvoříme metodu pro získání tokenů prostřednictvím přihlašovacích údajů klienta a nakonec tento modul zveřejníme pro přístup main.js. Konfigurační parametry v tomto modulu se načítají ze souboru prostředí, který vytvoříme v dalším kroku.

Přidání podrobností o registraci aplikace

Vytvořte soubor prostředí pro uložení podrobností o registraci aplikace, které se použijí při získávání tokenů. Uděláte to tak, že v kořenové složce ukázky (NodeDaemonApp) vytvoříte soubor s názvem .env a přidáte následující kód:

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

Vyplňte tyto podrobnosti hodnotami, které získáte z portálu pro registraci aplikací Azure:

Enter_the_Tenant_Id_here by měla být jedna z následujících možností:
- Pokud vaše aplikace podporuje účty v tomto organizačním adresáři, nahraďte tuto hodnotu ID tenanta nebo názvem tenanta. Například contoso.microsoft.com.
- Pokud vaše aplikace podporuje účty v libovolném organizačním adresáři, nahraďte tuto hodnotu organizationshodnotou .
- Pokud vaše aplikace podporuje účty v libovolném organizačním adresáři a osobních účtech Microsoft, nahraďte tuto hodnotu commonhodnotou .
- Chcete-li omezit podporu pouze na osobní účty Microsoft, nahraďte tuto hodnotu consumershodnotou .
Enter_the_Application_Id_Here: ID aplikace (klienta) aplikace, kterou jste zaregistrovali.
Enter_the_Cloud_Instance_Id_Here: Cloudová instance Azure, ve které je vaše aplikace zaregistrovaná.
- V případě hlavního (nebo globálního) cloudu Azure zadejte https://login.microsoftonline.com.
- Pro národní cloudy (například Čína) najdete odpovídající hodnoty v národních cloudech.
Enter_the_Graph_Endpoint_Here je instance rozhraní Microsoft Graph API, se kterým by aplikace měla komunikovat.
- V případě globálního koncového bodu rozhraní Microsoft Graph API nahraďte obě instance tohoto řetězce řetězcem https://graph.microsoft.com.
- Koncové body v národních cloudových nasazeních najdete v dokumentaci k Microsoft Graphu v národních cloudových nasazeních .

Přidání metody pro volání webového rozhraní API

Ve složce bin vytvořte další soubor s názvem fetch.js a přidejte následující kód pro volání REST do rozhraní 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
};

Zde se callApi metoda používá k vytvoření požadavku HTTP GET na chráněný prostředek, který vyžaduje přístupový token. Požadavek pak vrátí obsah volajícímu. Tato metoda přidá získaný token do hlavičky autorizace HTTP. Chráněným prostředkem je koncový bod uživatelů rozhraní Microsoft Graph API, který zobrazuje uživatele v tenantovi, kde je tato aplikace zaregistrovaná.

Otestování aplikace

Dokončili jste vytváření aplikace a teď jste připraveni otestovat funkčnost aplikace.

Spusťte aplikaci démon konzoly Node.js spuštěním následujícího příkazu v kořenové složce projektu:

node . --op getUsers

Výsledkem by měla být odpověď JSON z rozhraní Microsoft Graph API a v konzole by se měla zobrazit pole uživatelských objektů:

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

Rozhraní příkazového řádku zobrazující odpověď graphu

Jak aplikace funguje

Tato aplikace používá udělení přihlašovacích údajů klienta OAuth 2.0. Tento typ udělení se běžně používá pro interakce mezi servery, které musí běžet na pozadí bez okamžité interakce s uživatelem. Tok udělení přihlašovacích údajů umožňuje webové službě (důvěrnému klientovi) používat vlastní přihlašovací údaje místo zosobnění uživatele při volání jiné webové služby. Typ aplikací podporovaných tímto modelem ověřování jsou obvykle démony nebo účty služeb.

Obor, který se má vyžádat pro tok přihlašovacích údajů klienta, je název prostředku následovaný /.default. Tato notace říká Microsoftu Entra ID, aby během registrace aplikace používalo staticky deklarovaná oprávnění na úrovni aplikace. Tato oprávnění rozhraní API musí také udělit správce tenanta.

Další kroky

Pokud se chcete podrobněji podívat na vývoj aplikací démona Node.js na platformě Microsoft Identity Platform, projděte si naši sérii scénářů s více částmi:

Scénář: Aplikace démona

Sdílet prostřednictvím