Zelfstudie: De Microsoft Graph API aanroepen in een Node.js-console-daemon-app

Artikel
04/09/2024

In deze zelfstudie bouwt u een console-daemon-app die Microsoft Graph API aanroept met behulp van een eigen identiteit. De daemon-app die u bouwt, maakt gebruik van de Microsoft Authentication Library (MSAL) voor Node.js.

Volg de stappen in deze zelfstudie voor het volgende:

De app registreren in de Azure Portal
Een Daemon-app-project voor de Node.js-console maken
Verificatielogica toevoegen aan uw app
Registratiegegevens van app toevoegen
Een methode toevoegen om een web-API aan te roepen
De app testen

Vereisten

Node.js
Visual Studio Code of een andere code-editor

Registreer de toepassing

Voltooi eerst de stappen in Een toepassing registreren bij het Microsoft identity platform om uw app te registreren.

Gebruik de volgende instellingen voor uw app-registratie:

Naam: NodeDaemonApp (voorgesteld)
Ondersteunde accounttypen: alleen accounts in deze organisatiemap
API-machtigingen: Microsoft API's>Microsoft Graph-toepassingsmachtigingen>>User.Read.All
Clientgeheim: ********* (noteer deze waarde voor gebruik in een latere stap- deze wordt slechts één keer weergegeven)

Het project maken

Begin met het maken van een map voor dit node.js-zelfstudieproject. Bijvoorbeeld NodeDaemonApp.
Ga in de terminal naar de map die u hebt gemaakt (de hoofdmap van het project) en voer vervolgens de volgende opdrachten uit:
```
npm init -y
npm install --save dotenv yargs axios @azure/msal-node
```
Bewerk vervolgens het bestand package.json in de hoofdmap van het project en geef het voorvoegsel van de waarde, mainbin/zoals deze:
```
"main": "bin/index.js",
```

Maak nu de bin-map en voeg de volgende code toe aan een nieuw bestand met de naam 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();

Het bestand index.js dat u zojuist hebt gemaakt, verwijst naar twee andere knooppuntmodules die u hierna gaat maken:

auth.js: gebruikt MSAL Node voor het verkrijgen van toegangstokens van het Microsoft-identiteitsplatform.
fetch.js : vraagt gegevens van de Microsoft Graph API aan door toegangstokens (verkregen in auth.js) in HTTP-aanvragen naar de API op te halen.

Aan het einde van de zelfstudie moet de bestands- en mapstructuur van uw project er ongeveer als volgt uitzien:

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

Verificatielogica toevoegen

Voeg in de bin-map de volgende code toe aan een nieuw bestand met de naam auth.js. De code in auth.js verkrijgt een toegangstoken van het Microsoft Identity Platform voor het opnemen in Microsoft Graph API-aanvragen.

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

In het bovenstaande codefragment maken we eerst een configuratieobject (msalConfig) en geven we dit door om een MSAL ConfidentialClientApplication te initialiseren. Vervolgens maken we een methode voor het verkrijgen van tokens via clientreferenties en maken we deze module ten slotte beschikbaar voor toegang door main.js. De configuratieparameters in deze module worden getrokken uit een omgevingsbestand, dat we in de volgende stap gaan maken.

Registratiegegevens van app toevoegen

Maak een omgevingsbestand om de app-registratiegegevens op te slaan die worden gebruikt bij het verkrijgen van tokens. Hiervoor maakt u een bestand met de naam .env in de hoofdmap van het voorbeeld (NodeDaemonApp) en voegt u de volgende code toe:

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

Vul deze gegevens in met de waarden die u hebt verkregen via de registratie-portal van de Azure-app:

Enter_the_Tenant_Id_here moet een van de volgende zijn:
- Als uw toepassing ondersteuning biedt voor accounts in deze organisatiemap, vervangt u deze waarde door de Tenant-id of Tenantnaam. Bijvoorbeeld contoso.microsoft.com.
- Als uw toepassing ondersteuning biedt voor accounts in elke organisatiemap, vervangt u waarde door organizations.
- Als uw toepassing accounts in elke organisatiemap en persoonlijke Microsoft-accounts ondersteunt, vervang deze waarde dan door common.
- Als u de ondersteuning wilt beperken tot alleen persoonlijke Microsoft-accounts, vervang deze waarde dan door consumers.
Enter_the_Application_Id_Here: de toepassings-id (client) van de toepassing die u hebt geregistreerd.
Enter_the_Cloud_Instance_Id_Here: Het Azure-cloudexemplaren waarin uw toepassing is geregistreerd.
- Voer https://login.microsoftonline.com in voor de hoofd- (of globale) Azure-cloud.
- Voor nationale clouds (bijvoorbeeld China) kunt u de juiste waarden vinden in Nationale clouds.
Enter_the_Graph_Endpoint_Here is het exemplaar van de Microsoft Graph API waarmee de toepassing moet communiceren.
- Vervang beide exemplaren van deze teken reeks door https://graph.microsoft.com voor het wereldwijde Microsoft Graph API-eindpunt.
- Zie Nationale cloudimplementaties in de Microsoft Graph-documentatie voor eindpunten in nationale cloudimplementaties.

Een methode toevoegen om een web-API aan te roepen

Maak in de map bin een ander bestand met de naam fetch.js en voeg de volgende code toe voor het maken van REST-aanroepen naar de 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
};

Hier wordt de callApi methode gebruikt om een HTTP-aanvraag GET uit te voeren voor een beveiligde resource waarvoor een toegangstoken is vereist. De aanvraag retourneert vervolgens de inhoud naar de aanroeper. Met deze methode wordt het verkregen token toegevoegd in de HTTP-autorisatie-header. De beveiligde resource hier is het Microsoft Graph API-gebruikerseindpunt dat de gebruikers weergeeft in de tenant waarin deze app is geregistreerd.

De app testen

U hebt het maken van de toepassing voltooid en bent nu klaar om de functionaliteit van de app te testen.

Start de Daemon-app van de Node.js-console door de volgende opdracht uit te voeren vanuit de hoofdmap van uw projectmap:

node . --op getUsers

Dit moet resulteren in een JSON-antwoord van Microsoft Graph API en u ziet een matrix met gebruikersobjecten in de console:

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

Werking van de toepassing

Deze toepassing maakt gebruik van de toekenning van OAuth 2.0-clientreferenties. Dit type toekenning wordt meestal gebruikt voor server-naar-server-interacties die op de achtergrond moeten worden uitgevoerd, zonder directe interactie met een gebruiker. Met de stroom voor het verlenen van referenties kan een webservice (vertrouwelijke client) eigen referenties gebruiken in plaats van een gebruiker te imiteren, om te verifiëren bij het aanroepen van een andere webservice. Het type toepassingen dat wordt ondersteund met dit verificatiemodel, zijn meestal daemons of serviceaccounts.

Het bereik dat moet worden aangevraagd voor een clientreferentiestroom is de naam van de resource gevolgd door /.default. Deze notatie vertelt Microsoft Entra-id dat de machtigingen op toepassingsniveau statisch moeten worden gebruikt die tijdens de registratie van de toepassing zijn gedeclareerd. Deze API-machtigingen moeten ook worden verleend door een tenantbeheerder.

Volgende stappen

Als u meer wilt weten over de ontwikkeling van Node.js-daemon-toepassingen op het Microsoft Identity Platform, raadpleegt u onze reeks scenario's met meerdere onderdelen:

Scenario: Daemon-toepassing

Delen via