教程：在 Node.js 和 Express Web 应用中登录用户并获取 Microsoft Graph 的令牌

在本教程中，你将生成 Web 应用，用于登录用户并获取调用 Microsoft Graph 的访问令牌。 构建的 Web 应用使用适用于 Node.js 的 Microsoft 身份验证库 (MSAL)。

请按照本教程中的步骤进行操作：

有关详细信息，请参阅示例代码，了解如何使用 MSAL Node 登录、注销和获取 Microsoft Graph 等受保护资源的访问令牌。

先决条件

• Node.js
• Visual Studio Code 或其他代码编辑器

注册应用程序

首先，请完成向 Microsoft 标识平台注册应用程序中的步骤来注册你的应用。

对于应用注册，请使用以下设置：

• 名称：ExpressWebApp（建议）
• 支持的帐户类型：仅此组织目录中的帐户
• 平台类型：Web
• 重定向 URI：http://localhost:3000/auth/redirect
• 客户端机密：*********（记录此值以便在后面的步骤中使用 - 它只显示一次）

创建项目

使用 Express 应用程序生成器工具创建应用程序框架。

1. 首先，安装 express-generator 包：

    	npm install -g express-generator
   

2. 然后，创建应用程序框架，如下所示：

    	express --view=hbs /ExpressWebApp && cd /ExpressWebApp
    	npm install
   

现在已有简单 Express Web 应用。 项目的文件和文件夹结构应类似于以下文件夹结构：

ExpressWebApp/
├── bin/
|    └── wwww
├── public/
|    ├── images/
|    ├── javascript/
|    └── stylesheets/
|        └── style.css
├── routes/
|    ├── index.js
|    └── users.js
├── views/
|    ├── error.hbs
|    ├── index.hbs
|    └── layout.hbs
├── app.js
└── package.json

安装身份验证库

在终端中找到项目的根目录，并通过 npm 安装 MSAL Node 包。

    npm install --save @azure/msal-node

安装其他依赖项

本教程中的 Web 应用示例使用 包来进行会话管理、使用 dotenv 包在开发期间读取环境参数，使用 axios 来对 Microsoft Graph API 进行网络调用。 通过 npm 安装这些包：

    npm install --save express-session dotenv axios

添加应用注册详细信息

1. 在项目文件夹的根目录中创建 .env.dev 文件。 然后，添加以下代码：

   CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
   TENANT_ID="Enter_the_Tenant_Info_Here"
   CLIENT_ID="Enter_the_Application_Id_Here"
   CLIENT_SECRET="Enter_the_Client_Secret_Here"
   
   REDIRECT_URI="http://localhost:3000/auth/redirect"
   POST_LOGOUT_REDIRECT_URI="http://localhost:3000"
   
   GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash
   
   EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"
   

   使用从 Azure 应用注册门户获取的值填写以下详细信息：

   • Enter_the_Cloud_Instance_Id_Here：在其中注册应用程序的 Azure 云实例。
   • 对于国家/地区云（例如中国云），可以在国家/地区云中找到相应值。
   • Enter_the_Tenant_Info_here 应是以下参数之一：
   • 如果应用程序支持“此组织目录中的帐户”，请将此值替换为“租户 ID”或“租户名称”。 例如，contoso.microsoft.com。
   • 如果应用程序支持“任何组织目录中的帐户”，请将该值替换为“organizations”。
   • Enter_the_Application_Id_Here：已注册应用程序的应用程序（客户端）ID。
   • Enter_the_Client_secret：将此值替换为先前创建的客户端机密。 若要生成新密钥，请在 Azure 门户的应用注册设置中使用“证书和密码”。

   警告

   源代码中的任何纯文本机密都会增加安全风险。 本文使用纯文本客户端机密只是为了简单起见。 在机密客户端应用程序中使用证书凭据（而不是客户端机密），尤其是计划部署到生产环境的应用。

   • Enter_the_Graph_Endpoint_Here：应用将调用的 Microsoft Graph API 云实例。
   • Enter_the_Express_Session_Secret_Here 用于对 Express 会话 cookie 进行签名的机密。 选择要用于替换此字符串的随机字符串（例如客户端机密）。

2. 接下来，在项目的根目录中创建名为 authConfig.js 的文件，以读取这些参数。 创建后，在其中添加以下代码：

    /*
     * Copyright (c) Microsoft Corporation. All rights reserved.
     * Licensed under the MIT License.
     */
   
    require('dotenv').config({ path: '.env.dev' });
   
    /**
     * 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, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
            authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.partner.microsoftonline.cn/<tenant>
            clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
        },
        system: {
            loggerOptions: {
                loggerCallback(loglevel, message, containsPii) {
                    console.log(message);
                },
                piiLoggingEnabled: false,
                logLevel: 3,
            }
        }
    }
   
    const REDIRECT_URI = process.env.REDIRECT_URI;
    const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
    const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";
   
    module.exports = {
        msalConfig,
        REDIRECT_URI,
        POST_LOGOUT_REDIRECT_URI,
        GRAPH_ME_ENDPOINT
    };
   

添加用于登录用户和获取令牌的代码

1. 创建名为“auth”的新文件夹，并在其下添加名为“AuthProvider.js”的新文件。 这将包含 AuthProvider 类，其使用 MSAL Node 封装必要的身份验证逻辑。 在其中添加以下代码：

    const msal = require('@azure/msal-node');
    const axios = require('axios');
   
    const { msalConfig } = require('../authConfig');
   
    class AuthProvider {
        msalConfig;
        cryptoProvider;
   
        constructor(msalConfig) {
            this.msalConfig = msalConfig
            this.cryptoProvider = new msal.CryptoProvider();
        };
   
        login(options = {}) {
            return async (req, res, next) => {
   
                /**
                 * MSAL Node library allows you to pass your custom state as state parameter in the Request object.
                 * The state parameter can also be used to encode information of the app's state before redirect.
                 * You can pass the user's state in the app, such as the page or view they were on, as input to this parameter.
                 */
                const state = this.cryptoProvider.base64Encode(
                    JSON.stringify({
                        successRedirect: options.successRedirect || '/',
                    })
                );
   
                const authCodeUrlRequestParams = {
                    state: state,
   
                    /**
                     * By default, MSAL Node will add OIDC scopes to the auth code url request. For more information, visit:
                     * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
                     */
                    scopes: options.scopes || [],
                    redirectUri: options.redirectUri,
                };
   
                const authCodeRequestParams = {
                    state: state,
   
                    /**
                     * By default, MSAL Node will add OIDC scopes to the auth code request. For more information, visit:
                     * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
                     */
                    scopes: options.scopes || [],
                    redirectUri: options.redirectUri,
                };
   
                /**
                 * If the current msal configuration does not have cloudDiscoveryMetadata or authorityMetadata, we will 
                 * make a request to the relevant endpoints to retrieve the metadata. This allows MSAL to avoid making 
                 * metadata discovery calls, thereby improving performance of token acquisition process. For more, see:
                 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/performance.md
                 */
                if (!this.msalConfig.auth.cloudDiscoveryMetadata || !this.msalConfig.auth.authorityMetadata) {
   
                    const [cloudDiscoveryMetadata, authorityMetadata] = await Promise.all([
                        this.getCloudDiscoveryMetadata(this.msalConfig.auth.authority),
                        this.getAuthorityMetadata(this.msalConfig.auth.authority)
                    ]);
   
                    this.msalConfig.auth.cloudDiscoveryMetadata = JSON.stringify(cloudDiscoveryMetadata);
                    this.msalConfig.auth.authorityMetadata = JSON.stringify(authorityMetadata);
                }
   
                const msalInstance = this.getMsalInstance(this.msalConfig);
   
                // trigger the first leg of auth code flow
                return this.redirectToAuthCodeUrl(
                    authCodeUrlRequestParams,
                    authCodeRequestParams,
                    msalInstance
                )(req, res, next);
            };
        }
   
        acquireToken(options = {}) {
            return async (req, res, next) => {
                try {
                    const msalInstance = this.getMsalInstance(this.msalConfig);
   
                    /**
                     * If a token cache exists in the session, deserialize it and set it as the 
                     * cache for the new MSAL CCA instance. For more, see: 
                     * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/caching.md
                     */
                    if (req.session.tokenCache) {
                        msalInstance.getTokenCache().deserialize(req.session.tokenCache);
                    }
   
                    const tokenResponse = await msalInstance.acquireTokenSilent({
                        account: req.session.account,
                        scopes: options.scopes || [],
                    });
   
                    /**
                     * On successful token acquisition, write the updated token 
                     * cache back to the session. For more, see: 
                     * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/caching.md
                     */
                    req.session.tokenCache = msalInstance.getTokenCache().serialize();
                    req.session.accessToken = tokenResponse.accessToken;
                    req.session.idToken = tokenResponse.idToken;
                    req.session.account = tokenResponse.account;
   
                    res.redirect(options.successRedirect);
                } catch (error) {
                    if (error instanceof msal.InteractionRequiredAuthError) {
                        return this.login({
                            scopes: options.scopes || [],
                            redirectUri: options.redirectUri,
                            successRedirect: options.successRedirect || '/',
                        })(req, res, next);
                    }
   
                    next(error);
                }
            };
        }
   
        handleRedirect(options = {}) {
            return async (req, res, next) => {
                if (!req.body || !req.body.state) {
                    return next(new Error('Error: response not found'));
                }
   
                const authCodeRequest = {
                    ...req.session.authCodeRequest,
                    code: req.body.code,
                    codeVerifier: req.session.pkceCodes.verifier,
                };
   
                try {
                    const msalInstance = this.getMsalInstance(this.msalConfig);
   
                    if (req.session.tokenCache) {
                        msalInstance.getTokenCache().deserialize(req.session.tokenCache);
                    }
   
                    const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);
   
                    req.session.tokenCache = msalInstance.getTokenCache().serialize();
                    req.session.idToken = tokenResponse.idToken;
                    req.session.account = tokenResponse.account;
                    req.session.isAuthenticated = true;
   
                    const state = JSON.parse(this.cryptoProvider.base64Decode(req.body.state));
                    res.redirect(state.successRedirect);
                } catch (error) {
                    next(error);
                }
            }
        }
   
        logout(options = {}) {
            return (req, res, next) => {
   
                /**
                 * Construct a logout URI and redirect the user to end the
                 * session with Azure AD. For more information, visit:
                 * https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc#send-a-sign-out-request
                 */
                let logoutUri = `${this.msalConfig.auth.authority}/oauth2/v2.0/`;
   
                if (options.postLogoutRedirectUri) {
                    logoutUri += `logout?post_logout_redirect_uri=${options.postLogoutRedirectUri}`;
                }
   
                req.session.destroy(() => {
                    res.redirect(logoutUri);
                });
            }
        }
   
        /**
         * Instantiates a new MSAL ConfidentialClientApplication object
         * @param msalConfig: MSAL Node Configuration object 
         * @returns 
         */
        getMsalInstance(msalConfig) {
            return new msal.ConfidentialClientApplication(msalConfig);
        }
   
   
        /**
         * Prepares the auth code request parameters and initiates the first leg of auth code flow
         * @param req: Express request object
         * @param res: Express response object
         * @param next: Express next function
         * @param authCodeUrlRequestParams: parameters for requesting an auth code url
         * @param authCodeRequestParams: parameters for requesting tokens using auth code
         */
        redirectToAuthCodeUrl(authCodeUrlRequestParams, authCodeRequestParams, msalInstance) {
            return async (req, res, next) => {
                // Generate PKCE Codes before starting the authorization flow
                const { verifier, challenge } = await this.cryptoProvider.generatePkceCodes();
   
                // Set generated PKCE codes and method as session vars
                req.session.pkceCodes = {
                    challengeMethod: 'S256',
                    verifier: verifier,
                    challenge: challenge,
                };
   
                /**
                 * By manipulating the request objects below before each request, we can obtain
                 * auth artifacts with desired claims. For more information, visit:
                 * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationurlrequest
                 * https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_node.html#authorizationcoderequest
                 **/
                req.session.authCodeUrlRequest = {
                    ...authCodeUrlRequestParams,
                    responseMode: msal.ResponseMode.FORM_POST, // recommended for confidential clients
                    codeChallenge: req.session.pkceCodes.challenge,
                    codeChallengeMethod: req.session.pkceCodes.challengeMethod,
                };
   
                req.session.authCodeRequest = {
                    ...authCodeRequestParams,
                    code: '',
                };
   
                try {
                    const authCodeUrlResponse = await msalInstance.getAuthCodeUrl(req.session.authCodeUrlRequest);
                    res.redirect(authCodeUrlResponse);
                } catch (error) {
                    next(error);
                }
            };
        }
   
        /**
         * Retrieves cloud discovery metadata from the /discovery/instance endpoint
         * @returns 
         */
        async getCloudDiscoveryMetadata(authority) {
            const endpoint = 'https://login.partner.microsoftonline.cn/common/discovery/instance';
   
            try {
                const response = await axios.get(endpoint, {
                    params: {
                        'api-version': '1.1',
                        'authorization_endpoint': `${authority}/oauth2/v2.0/authorize`
                    }
                });
   
                return await response.data;
            } catch (error) {
                throw error;
            }
        }
   
        /**
         * Retrieves oidc metadata from the openid endpoint
         * @returns
         */
        async getAuthorityMetadata(authority) {
            const endpoint = `${authority}/v2.0/.well-known/openid-configuration`;
   
            try {
                const response = await axios.get(endpoint);
                return await response.data;
            } catch (error) {
                console.log(error);
            }
        }
    }
   
    const authProvider = new AuthProvider(msalConfig);
   
    module.exports = authProvider;
   

2. 接下来，在路由文件夹下创建名为“auth.js”的新文件，并在其中添加以下代码：

    /*
     * Copyright (c) Microsoft Corporation. All rights reserved.
     * Licensed under the MIT License.
     */
   
    var express = require('express');
   
    const authProvider = require('../auth/AuthProvider');
    const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');
   
    const router = express.Router();
   
    router.get('/signin', authProvider.login({
        scopes: [],
        redirectUri: REDIRECT_URI,
        successRedirect: '/'
    }));
   
    router.get('/acquireToken', authProvider.acquireToken({
           scopes: ['https://microsoftgraph.chinacloudapi.cn/User.Read'],
        redirectUri: REDIRECT_URI,
        successRedirect: '/users/profile'
    }));
   
    router.post('/redirect', authProvider.handleRedirect());
   
    router.get('/signout', authProvider.logout({
        postLogoutRedirectUri: POST_LOGOUT_REDIRECT_URI
    }));
   
    module.exports = router;
   

3. 通过将现有代码替换为以下代码片段来更新“index.js”路由：

    /*
     * Copyright (c) Microsoft Corporation. All rights reserved.
     * Licensed under the MIT License.
     */
   
    var express = require('express');
    var router = express.Router();
   
    router.get('/', function (req, res, next) {
        res.render('index', {
            title: 'MSAL Node & Express Web App',
            isAuthenticated: req.session.isAuthenticated,
            username: req.session.account?.username,
        });
    });
   
    module.exports = router;
   

4. 最后，通过将现有代码替换为以下代码片段来更新 users.js 路由：

    /*
     * Copyright (c) Microsoft Corporation. All rights reserved.
     * Licensed under the MIT License.
     */
   
    var express = require('express');
    var router = express.Router();
   
    var fetch = require('../fetch');
   
    var { GRAPH_ME_ENDPOINT } = require('../authConfig');
   
    // custom middleware to check auth state
    function isAuthenticated(req, res, next) {
        if (!req.session.isAuthenticated) {
            return res.redirect('/auth/signin'); // redirect to sign-in route
        }
   
        next();
    };
   
    router.get('/id',
        isAuthenticated, // check if user is authenticated
        async function (req, res, next) {
            res.render('id', { idTokenClaims: req.session.account.idTokenClaims });
        }
    );
   
    router.get('/profile',
        isAuthenticated, // check if user is authenticated
        async function (req, res, next) {
            try {
                const graphResponse = await fetch(GRAPH_ME_ENDPOINT, req.session.accessToken);
                res.render('profile', { profile: graphResponse });
            } catch (error) {
                next(error);
            }
        }
    );
   
    module.exports = router;
   

添加用于调用 Microsoft Graph API 的代码

在项目的根目录中创建名为 fetch.js 的文件并添加以下代码：

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

var axios = require('axios');

/**
 * Attaches a given access token to a MS Graph API call
 * @param endpoint: REST API endpoint to call
 * @param accessToken: raw access token string
 */
async function fetch(endpoint, accessToken) {
    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log(`request made to ${endpoint} at: ` + new Date().toString());

    try {
        const response = await axios.get(endpoint, options);
        return await response.data;
    } catch (error) {
        throw new Error(error);
    }
}

module.exports = fetch;

添加用于显示数据的视图

1. 在 views 文件夹中，通过将现有代码替换为以下内容来更新 index.hbs 文件：

    <h1>{{title}}</h1>
    {{#if isAuthenticated }}
    <p>Hi {{username}}!</p>
    <a href="/users/id">View ID token claims</a>
    <br>
    <a href="/auth/acquireToken">Acquire a token to call the Microsoft Graph API</a>
    <br>
    <a href="/auth/signout">Sign out</a>
    {{else}}
    <p>Welcome to {{title}}</p>
    <a href="/auth/signin">Sign in</a>
    {{/if}}
   

2. 仍在同一文件夹中，创建另一个名为 id.hbs 的文件以显示用户 ID 令牌的内容：

    <h1>Azure AD</h1>
    <h3>ID Token</h3>
    <table>
        <tbody>
            {{#each idTokenClaims}}
            <tr>
                <td>{{@key}}</td>
                <td>{{this}}</td>
            </tr>
            {{/each}}
        </tbody>
    </table>
    <br>
    <a href="https://aka.ms/id-tokens" target="_blank">Learn about claims in this ID token</a>
    <br>
    <a href="/">Go back</a>
   

3. 最后，创建另一个名为 profile.hbs 的文件以显示对 Microsoft Graph 的调用结果：

    <h1>Microsoft Graph API</h1>
    <h3>/me endpoint response</h3>
    <table>
        <tbody>
            {{#each profile}}
            <tr>
                <td>{{@key}}</td>
                <td>{{this}}</td>
            </tr>
            {{/each}}
        </tbody>
    </table>
    <br>
    <a href="/">Go back</a>
   

注册路由器并添加状态管理

在项目文件夹根目录的 app.js 文件中，注册之前创建的路由，并使用 express-session 包添加会话支持以跟踪身份验证状态。 将现有代码替换为以下代码片段：

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

require('dotenv').config();

var path = require('path');
var express = require('express');
var session = require('express-session');
var createError = require('http-errors');
var cookieParser = require('cookie-parser');
var logger = require('morgan');

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');
var authRouter = require('./routes/auth');

// initialize express
var app = express();

/**
 * Using express-session middleware for persistent user session. Be sure to
 * familiarize yourself with available options. Visit: https://www.npmjs.com/package/express-session
 */
 app.use(session({
    secret: process.env.EXPRESS_SESSION_SECRET,
    resave: false,
    saveUninitialized: false,
    cookie: {
        httpOnly: true,
        secure: false, // set this to true on production
    }
}));

// view engine setup
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'hbs');

app.use(logger('dev'));
app.use(express.json());
app.use(cookieParser());
app.use(express.urlencoded({ extended: false }));
app.use(express.static(path.join(__dirname, 'public')));

app.use('/', indexRouter);
app.use('/users', usersRouter);
app.use('/auth', authRouter);

// catch 404 and forward to error handler
app.use(function (req, res, next) {
    next(createError(404));
});

// error handler
app.use(function (err, req, res, next) {
    // set locals, only providing error in development
    res.locals.message = err.message;
    res.locals.error = req.app.get('env') === 'development' ? err : {};

    // render the error page
    res.status(err.status || 500);
    res.render('error');
});

module.exports = app;

测试登录并调用 Microsoft Graph

你已完成应用程序的创建，现在即可测试应用的功能。

1. 从项目文件夹的根目录中运行以下命令，启动 Node.js 控制台应用：

   npm start

2. 打开浏览器窗口并导航到 http://localhost:3000。 应该会出现欢迎页：

3. 请选择“登录”链接。 应会看到 Microsoft Entra 登录屏幕：

4. 输入凭据后，你应该会看到一个同意屏幕，要求你批准应用的权限。

5. 同意后，会退回应用程序主页。

6. 请选择“查看 ID 令牌”链接以显示已登录用户 ID 令牌的内容。

7. 返回主页，然后选择“获取访问令牌并调用 Microsoft Graph API”链接。 完成后，应该会出现 Microsoft Graph /me 终结点对已登录用户的响应。

8. 返回主页，然后选择“注销”链接。 应会看到 Microsoft Entra 退出登录屏幕。

应用程序的工作原理

在本教程中，你通过向 MSAL Node ConfidentialClientApplication 对象传递一个配置对象 (msalConfig)（其中包含从 Azure 门户上的 Microsoft Entra 应用注册获得的参数）对其进行了实例化。 你创建的 Web 应用使用 OpenID Connect 协议来登录用户，并使用 OAuth 2.0 授权代码流获取访问令牌。

后续步骤

如果你想要更深入了解 Microsoft 标识平台上的 Node.js & Express web 应用程序开发，请参阅由多部分组成的方案系列：