Öğretici: Node.js konsol daemon uygulamasında Microsoft Graph API'sini çağırma

Makale
04/09/2024

Bu öğreticide, kendi kimliğini kullanarak Microsoft Graph API'sini çağıran bir konsol daemon uygulaması oluşturacaksınız. Oluşturduğunuz daemon uygulaması, Node.js için Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanır.

Aşağıdakiler için bu öğreticideki adımları izleyin:

Uygulamayı Azure portalına kaydetme
Node.js konsol daemon uygulaması projesi oluşturma
Uygulamanıza kimlik doğrulama mantığı ekleme
Uygulama kaydı ayrıntıları ekleme
Web API'sini çağırmak için yöntem ekleme
Uygulamayı test etme

Önkoşullar

Node.js
Visual Studio Code veya başka bir kod düzenleyicisi

Uygulamayı kaydetme

İlk olarak, Uygulamanızı kaydetmek için Microsoft kimlik platformu bir uygulamayı kaydetme bölümünde yer alan adımları tamamlayın.

Uygulama kaydınız için aşağıdaki ayarları kullanın:

Ad: NodeDaemonApp (önerilen)
Desteklenen hesap türleri: Yalnızca bu kuruluş dizinindeki hesaplar
API izinleri: Microsoft API'leri>Microsoft Graph>Uygulama İzinleri>User.Read.All
gizli dizi: ********* (bu değeri daha sonraki bir adımda kullanmak üzere kaydedin; yalnızca bir kez gösterilir)

Proje oluşturma

Bu Node.js öğretici projesi için bir dizin oluşturarak başlayın. Örneğin NodeDaemonApp.
Terminalinizde, oluşturduğunuz dizine (proje kökü) geçin ve aşağıdaki komutları çalıştırın:
```
npm init -y
npm install --save dotenv yargs axios @azure/msal-node
```
Ardından, proje kökündeki package.json dosyasını düzenleyin ve değerini main ile bin/önek olarak ekleyin:
```
"main": "bin/index.js",
```

Şimdi bin dizinini oluşturun ve depo gözü içinde aşağıdaki kodu index.js adlı yeni bir dosyaya ekleyin:

#!/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 önce oluşturduğunuz index.js dosyası, oluşturacağınız diğer iki düğüm modülüne başvurur:

auth.js - Microsoft kimlik platformu erişim belirteçlerini almak için MSAL Düğümünü kullanır.
fetch.js - HTTP isteklerinde ERIŞIM belirteçlerini (auth.js alınan) API'ye ekleyerek Microsoft Graph API'sinden veri ister.

Öğreticinin sonunda projenizin dosyası ve dizin yapısı şuna benzer olmalıdır:

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

Kimlik doğrulama mantığı ekleme

Bin dizininin içine aşağıdaki kodu auth.js adlı yeni bir dosyaya ekleyin. auth.js'deki kod, Microsoft Graph API isteklerine dahil etmek üzere Microsoft kimlik platformu bir erişim belirteci alır.

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

Yukarıdaki kod parçacığında, önce bir yapılandırma nesnesi (msalConfig) oluşturur ve bunu bir MSAL ConfidentialClientApplication başlatmak için geçiririz. Ardından, istemci kimlik bilgileri aracılığıyla belirteçleri almak için bir yöntem oluşturur ve son olarak bu modülü main.js tarafından erişilecek şekilde kullanıma sunarız. Bu modüldeki yapılandırma parametreleri, bir sonraki adımda oluşturacağımız bir ortam dosyasından çekilir.

Uygulama kaydı ayrıntıları ekleme

Belirteçleri alırken kullanılacak uygulama kaydı ayrıntılarını depolamak için bir ortam dosyası oluşturun. Bunu yapmak için, örneğin kök klasörünün (NodeDaemonApp) içinde .env adlı bir dosya oluşturun ve aşağıdaki kodu ekleyin:

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

Bu ayrıntıları Azure uygulama kayıt portalından aldığınız değerlerle doldurun:

Enter_the_Tenant_Id_here aşağıdakilerden biri olmalıdır:
- Uygulamanız bu kuruluş dizinindeki hesapları destekliyorsa, bu değeri Kiracı Kimliği veya Kiracı adı ile değiştirin. Örneğin, contoso.microsoft.com.
- Uygulamanız herhangi bir kuruluş dizinindeki hesapları destekliyorsa, bu değeri ile organizationsdeğiştirin.
- Uygulamanız herhangi bir kuruluş dizinindeki hesapları ve kişisel Microsoft hesaplarını destekliyorsa, bu değeri ile commondeğiştirin.
- Desteği yalnızca kişisel Microsoft hesaplarıyla kısıtlamak için bu değeri ile consumersdeğiştirin.
Enter_the_Application_Id_Here: Kaydettiğiniz uygulamanın Uygulama (istemci) kimliği.
Enter_the_Cloud_Instance_Id_Here: Uygulamanızın kayıtlı olduğu Azure bulut örneği.
- Ana (veya genel) Azure bulutu için girin https://login.microsoftonline.com.
- Ulusal bulutlar (örneğin, Çin) için Uygun değerleri Ulusal bulutlarda bulabilirsiniz.
Enter_the_Graph_Endpoint_Here , uygulamanın iletişim kurması gereken Microsoft Graph API örneğidir.
- Genel Microsoft Graph API uç noktası için bu dizenin her iki örneğini de ile https://graph.microsoft.comdeğiştirin.
- Ulusal bulut dağıtımlarındaki uç noktalar için Microsoft Graph belgelerindeki Ulusal bulut dağıtımları bölümüne bakın.

Web API'sini çağırmak için yöntem ekleme

Bölme klasörünün içinde fetch.js adlı başka bir dosya oluşturun ve Microsoft Graph API'sine REST çağrıları yapmak için aşağıdaki kodu ekleyin:

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

Burada yöntemi, callApi erişim belirteci gerektiren korumalı bir kaynağa http isteğinde bulunmak GET için kullanılır. İstek daha sonra içeriği çağırana döndürür. Bu yöntem, alınan belirteci HTTP Yetkilendirme üst bilgisine ekler. Buradaki korumalı kaynak, bu uygulamanın kayıtlı olduğu kiracıdaki kullanıcıları görüntüleyen Microsoft Graph API kullanıcıları uç noktasıdır .

Uygulamayı test etme

Uygulamanın oluşturulmasını tamamladınız ve artık uygulamanın işlevselliğini test etmeye hazırsınız.

Proje klasörünüzün kökünden aşağıdaki komutu çalıştırarak Node.js konsol daemon uygulamasını başlatın:

node . --op getUsers

Bunun sonucunda Microsoft Graph API'sinden bazı JSON yanıtları alınmalıdır ve konsolda bir kullanıcı nesneleri dizisi görmeniz gerekir:

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

Graph yanıtlarını görüntüleyen komut satırı arabirimi

Uygulama nasıl çalışır?

Bu uygulama OAuth 2.0 istemci kimlik bilgileri verme işlevini kullanır. Kullanıcının anında etkileşime geçmesi gerekmeyen ve arka planda çalışması gereken sunucular arası etkileşimler için genellikle bu izin türü kullanılır. Kimlik bilgileri verme akışı, bir web hizmetinin (gizli istemci) bir kullanıcının kimliğine bürünmek yerine kendi kimlik bilgilerini kullanmasına izin verir ve başka bir web hizmetini çağırırken kimlik doğrulaması yapar. Bu kimlik doğrulama modeliyle desteklenen uygulamaların türü genellikle daemon'lar veya hizmet hesaplarıdır.

İstemci kimlik bilgisi akışı için istekte bulunacak kapsam, kaynağın adı ve ardından /.defaultgelen adıdır. Bu notasyon, Microsoft Entra Id'ye uygulama kaydı sırasında statik olarak bildirilen uygulama düzeyi izinlerini kullanmasını bildirir. Ayrıca, bu API izinleri bir kiracı yöneticisi tarafından verilmelidir.

Sonraki adımlar

Microsoft kimlik platformu Node.js daemon uygulama geliştirme hakkında daha ayrıntılı bilgi edinmek isterseniz çok parçalı senaryo serimize bakın:

Senaryo: Daemon uygulaması

Aracılığıyla paylaş