Delen via

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

  • Artikel

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 Node.js console-daemon-app-project maken
  • Verificatielogica toevoegen aan uw app
  • Registratiegegevens van app toevoegen
  • Een methode toevoegen om een web-API aan te roepen
  • De app testen

Vereisten

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

  1. Begin met het maken van een map voor dit Node.js zelfstudieproject. Bijvoorbeeld NodeDaemonApp.

  2. 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

  3. Bewerk vervolgens het bestand package.json in de hoofdmap van het project en geef het voorvoegsel van de waarde, main bin/zoals deze:

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

  4. Maak nu de bin-map en voeg in de bin 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 Identity Platform.
  • fetch.js : vraagt gegevens van de Microsoft Graph API aan door toegangstokens (verkregen in auth.js) op te halen in HTTP-aanvragen voor de API.

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 bin-map 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 Node.js console daemon-app 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'
        }
    ]
}

Opdrachtregelinterface met Graph-antwoord

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 Node.js ontwikkeling van daemon-toepassingen op het Microsoft Identity Platform, raadpleegt u onze reeks scenario's met meerdere onderdelen:

Scenario: Daemon-toepassing