Samouczek: wywoływanie interfejsu API programu Microsoft Graph w aplikacji demona konsoli Node.js

Artykuł
04/09/2024

W tym samouczku utworzysz aplikację demona konsoli, która wywołuje interfejs API programu Microsoft Graph przy użyciu własnej tożsamości. Utworzona aplikacja demona używa biblioteki Microsoft Authentication Library (MSAL) do Node.js.

Wykonaj kroki opisane w tym samouczku, aby:

Rejestrowanie aplikacji w witrynie Azure Portal
Tworzenie projektu aplikacji demona konsoli Node.js
Dodawanie logiki uwierzytelniania do aplikacji
Dodawanie szczegółów rejestracji aplikacji
Dodawanie metody do wywoływania internetowego interfejsu API
Testowanie aplikacji

Wymagania wstępne

Node.js
Visual Studio Code lub inny edytor kodu

Rejestrowanie aplikacji

Najpierw wykonaj kroki opisane w temacie Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft, aby zarejestrować aplikację.

Użyj następujących ustawień rejestracji aplikacji:

Nazwa: NodeDaemonApp (sugerowane)
Obsługiwane typy kont: konta tylko w tym katalogu organizacyjnym
Uprawnienia interfejsu API: Microsoft APIs>Microsoft Graph Application Permissions (Uprawnienia aplikacji microsoft Graph) >>User.Read.All
Wpis tajny klienta: ********* (zapisz tę wartość do użycia w późniejszym kroku — jest wyświetlany tylko raz)

Tworzenie projektu

Zacznij od utworzenia katalogu dla tego projektu samouczka Node.js. Na przykład NodeDaemonApp.
W terminalu przejdź do utworzonego katalogu (katalogu głównego projektu), a następnie uruchom następujące polecenia:
```
npm init -y
npm install --save dotenv yargs axios @azure/msal-node
```
Następnie zmodyfikuj plik package.json w katalogu głównym projektu i prefiks wartości main z wartością bin/, w następujący sposób:
```
"main": "bin/index.js",
```

Teraz utwórz katalog bin i wewnątrz pojemnika dodaj następujący kod do nowego pliku o nazwie 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();

Utworzony plik index.js odwołuje się do dwóch innych modułów węzłów, które utworzysz w następnej kolejności:

auth.js — używa węzła MSAL do uzyskiwania tokenów dostępu z Platforma tożsamości Microsoft.
fetch.js — żąda danych z interfejsu API programu Microsoft Graph przez uwzględnienie tokenów dostępu (uzyskanych w auth.js) w żądaniach HTTP do interfejsu API.

Na końcu samouczka struktura plików i katalogów projektu powinna wyglądać mniej więcej tak:

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

Dodawanie logiki uwierzytelniania

W katalogu bin dodaj następujący kod do nowego pliku o nazwie auth.js. Kod w auth.js uzyskuje token dostępu z Platforma tożsamości Microsoft do dołączania żądań interfejsu API programu Microsoft Graph.

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

W powyższym fragmencie kodu najpierw utworzymy obiekt konfiguracji (msalConfig) i przekażemy go do zainicjowania klasy MSAL ConfidentialClientApplication. Następnie utworzymy metodę uzyskiwania tokenów za pośrednictwem poświadczeń klienta i na koniec uwidaczniamy ten moduł, aby uzyskać dostęp main.js. Parametry konfiguracji w tym module są pobierane z pliku środowiska, który zostanie utworzony w następnym kroku.

Dodawanie szczegółów rejestracji aplikacji

Utwórz plik środowiska do przechowywania szczegółów rejestracji aplikacji, które będą używane podczas uzyskiwania tokenów. W tym celu utwórz plik o nazwie env w folderze głównym przykładu (NodeDaemonApp) i dodaj następujący 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/

Wypełnij te szczegóły wartościami uzyskanymi w portalu rejestracji aplikacji platformy Azure:

Enter_the_Tenant_Id_here powinien być jednym z następujących elementów:
- Jeśli aplikacja obsługuje konta w tym katalogu organizacyjnym, zastąp tę wartość identyfikatorem dzierżawy lub nazwą dzierżawy. Na przykład contoso.microsoft.com.
- Jeśli aplikacja obsługuje konta w dowolnym katalogu organizacyjnym, zastąp tę wartość wartością organizations.
- Jeśli aplikacja obsługuje konta w dowolnym katalogu organizacyjnym i osobistych kontach Microsoft, zastąp tę wartość wartością common.
- Aby ograniczyć obsługę tylko do osobistych kont Microsoft, zastąp tę wartość wartością consumers.
Enter_the_Application_Id_Here: identyfikator aplikacji (klienta) zarejestrowanej aplikacji.
Enter_the_Cloud_Instance_Id_Here: wystąpienie chmury platformy Azure, w którym zarejestrowano aplikację.
- W przypadku głównej (lub globalnej) chmury platformy Azure wprowadź .https://login.microsoftonline.com
- W przypadku chmur krajowych (na przykład w Chinach) można znaleźć odpowiednie wartości w chmurach krajowych.
Enter_the_Graph_Endpoint_Here to wystąpienie interfejsu API programu Microsoft Graph, z którymi aplikacja powinna się komunikować.
- W przypadku globalnego punktu końcowego interfejsu API programu Microsoft Graph zastąp oba wystąpienia tego ciągu ciągiem https://graph.microsoft.com.
- Aby uzyskać informacje o punktach końcowych we wdrożeniach chmury krajowej, zobacz Wdrożenia chmury krajowej w dokumentacji programu Microsoft Graph.

Dodawanie metody do wywoływania internetowego interfejsu API

W folderze bin utwórz inny plik o nazwie fetch.js i dodaj następujący kod do wykonywania wywołań REST do interfejsu API programu Microsoft Graph:

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 W tym miejscu metoda służy do tworzenia żądania HTTP GET względem chronionego zasobu, który wymaga tokenu dostępu. Następnie żądanie zwraca zawartość do elementu wywołującego. Ta metoda dodaje uzyskany token w nagłówku autoryzacji HTTP. Chroniony zasób to punkt końcowy użytkowników interfejsu API programu Microsoft Graph, który wyświetla użytkowników w dzierżawie, w której zarejestrowano tę aplikację.

Testowanie aplikacji

Ukończono tworzenie aplikacji i teraz możesz przystąpić do testowania funkcjonalności aplikacji.

Uruchom aplikację demona konsoli Node.js, uruchamiając następujące polecenie z poziomu katalogu głównego folderu projektu:

node . --op getUsers

Powinno to spowodować odpowiedź w formacie JSON z interfejsu API programu Microsoft Graph i powinna zostać wyświetlona tablica obiektów użytkownika w konsoli programu :

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

Interfejs wiersza polecenia wyświetlający odpowiedź programu Graph

Jak działa aplikacja

Ta aplikacja używa poświadczeń klienta protokołu OAuth 2.0. Ten typ uprawnień jest często używany do interakcji między serwerami, które muszą działać w tle bez natychmiastowej interakcji z użytkownikiem. Przepływ udzielania poświadczeń umożliwia usłudze internetowej (poufnemu klientowi) używanie własnych poświadczeń zamiast personifikowania użytkownika w celu uwierzytelniania podczas wywoływania innej usługi internetowej. Typ aplikacji obsługiwanych w tym modelu uwierzytelniania to zwykle demony lub konta usług.

Zakres żądania przepływu poświadczeń klienta to nazwa zasobu, po którym następuje /.default. Ta notacja informuje identyfikator Entra firmy Microsoft o użyciu uprawnień na poziomie aplikacji zadeklarowanych statycznie podczas rejestracji aplikacji. Ponadto te uprawnienia interfejsu API muszą zostać przyznane przez administratora dzierżawy.

Następne kroki

Jeśli chcesz dowiedzieć się więcej na temat tworzenia aplikacji demona Node.js w Platforma tożsamości Microsoft, zobacz naszą wieloczęściową serię scenariuszy:

Scenariusz: aplikacja demona

Udostępnij za pośrednictwem