使用 Azure Active Directory B2C 在您自己的 Node.js Web API 中啟用驗證

您將可從本文了解如何建立可呼叫 Web API 的 Web 應用程式。 Web API 必須受 Azure Active Directory B2C (Azure AD B2C) 的保護。 若要授權 Web API 的存取權,您會提出內含由 Azure AD B2C 所發出之有效存取權杖的要求。

必要條件

步驟 1:建立受保護的 Web API

遵循下列步驟,建立您的 Node.js Web API。

步驟 1.1:建立專案

使用 Express for Node.js,建置 Web API。 若要建立 Web API,請執行下列動作:

  1. 建立名為 TodoList 的新資料夾。
  2. TodoList 資料夾下,建立名為 index.js 的檔案。
  3. 在命令殼層執行 npm init -y。 此命令會建立 Node.js 專案的預設 package.json 檔案。
  4. 在命令殼層中,執行 npm install express。 此命令會安裝 Express 架構。

步驟 1.2:安裝相依項目

將驗證程式庫新增至您的 Web API 專案。 驗證程式庫會剖析 HTTP 驗證標頭,並會驗證權杖以及擷取宣告。 如需詳細資訊,請檢閱程式庫的文件。

若要新增驗證程式庫,請執行下列命令,安裝套件:

npm install passport
npm install passport-azure-ad
npm install morgan

morgan 套件是 Node.js 的 HTTP 要求記錄器中介軟體。

步驟 1.3:撰寫 Web API 伺服器程式碼

index.js 檔案中新增下列程式碼:

const express = require('express');
const morgan = require('morgan');
const passport = require('passport');
const config = require('./config.json');
const todolist = require('./todolist');
const cors = require('cors');

//<ms_docref_import_azuread_lib>
const BearerStrategy = require('passport-azure-ad').BearerStrategy;
//</ms_docref_import_azuread_lib>

global.global_todos = [];

//<ms_docref_azureadb2c_options>
const options = {
    identityMetadata: `https://${config.credentials.tenantName}.b2clogin.com/${config.credentials.tenantName}.onmicrosoft.com/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
    clientID: config.credentials.clientID,
    audience: config.credentials.clientID,
    policyName: config.policies.policyName,
    isB2C: config.settings.isB2C,
    validateIssuer: config.settings.validateIssuer,
    loggingLevel: config.settings.loggingLevel,
    passReqToCallback: config.settings.passReqToCallback
}

//</ms_docref_azureadb2c_options>

//<ms_docref_init_azuread_lib>
const bearerStrategy = new BearerStrategy(options, (token, done) => {
        // Send user info using the second argument
        done(null, { }, token);
    }
);
//</ms_docref_init_azuread_lib>
const app = express();

app.use(express.json()); 

//enable CORS (for testing only -remove in production/deployment)
app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Headers', 'Authorization, Origin, X-Requested-With, Content-Type, Accept');
    next();
});

app.use(morgan('dev'));

app.use(passport.initialize());

passport.use(bearerStrategy);

// To do list endpoints
app.use('/api/todolist', todolist);

//<ms_docref_protected_api_endpoint>
// API endpoint, one must present a bearer accessToken to access this endpoint
app.get('/hello',
    passport.authenticate('oauth-bearer', {session: false}),
    (req, res) => {
        console.log('Validated claims: ', req.authInfo);
    
          
        // Service relies on the name claim.  
        res.status(200).json({'name': req.authInfo['name']});
    }
);
//</ms_docref_protected_api_endpoint>

//<ms_docref_anonymous_api_endpoint>
// API anonymous endpoint, returns a date to the caller.
app.get('/public', (req, res) => res.send( {'date': new Date() } ));
//</ms_docref_anonymous_api_endpoint>

const port = process.env.PORT || 5000;

app.listen(port, () => {
    console.log('Listening on port ' + port);
});

記下 index.js 檔案中的下列程式碼片段:

  • 匯入 Passport Azure AD 程式庫

    const BearerStrategy = require('passport-azure-ad').BearerStrategy;
    
  • 設定 Azure AD B2C 選項

    const options = {
        identityMetadata: `https://${config.credentials.tenantName}.b2clogin.com/${config.credentials.tenantName}.onmicrosoft.com/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
        clientID: config.credentials.clientID,
        audience: config.credentials.clientID,
        policyName: config.policies.policyName,
        isB2C: config.settings.isB2C,
        validateIssuer: config.settings.validateIssuer,
        loggingLevel: config.settings.loggingLevel,
        passReqToCallback: config.settings.passReqToCallback
    }
    
  • 使用 Azure AD B2C 選項,具現化 Passport Azure AD 程式庫

    const bearerStrategy = new BearerStrategy(options, (token, done) => {
            // Send user info using the second argument
            done(null, { }, token);
        }
    );
    
  • 受保護的 API 端點。 其會提供要求,內含由有效 Azure AD B2C 所發出的存取權杖。 此端點會傳回存取權杖中的 name 宣告值。

    // API endpoint, one must present a bearer accessToken to access this endpoint
    app.get('/hello',
        passport.authenticate('oauth-bearer', {session: false}),
        (req, res) => {
            console.log('Validated claims: ', req.authInfo);
        
              
            // Service relies on the name claim.  
            res.status(200).json({'name': req.authInfo['name']});
        }
    );
    
  • 匿名 API 端點。 無須提供存取權杖,即可呼叫 Web 應用程式。 其可用於以匿名呼叫的方式,偵錯您的 Web API。

    // API anonymous endpoint, returns a date to the caller.
    app.get('/public', (req, res) => res.send( {'date': new Date() } ));
    

步驟 1.4:設定 Web API

將設定新增至設定檔。 該檔案包含您 Azure AD B2C 識別提供者的相關資訊。 Web API 應用程式會使用此資訊,驗證 Web 應用程式以持有人權杖的形式所傳遞的存取權杖。

  1. 在專案根資料夾下建立 config.json 檔案,然後將其新增至下列 JSON 物件:

    {
        "credentials": {
            "tenantName": "fabrikamb2c",
            "clientID": "93733604-cc77-4a3c-a604-87084dd55348"
        },
        "policies": {
            "policyName": "B2C_1_susi"
        },
        "resource": {
            "scope": ["tasks.read"]
        },
        "metadata": {
            "authority": "login.microsoftonline.com",
            "discovery": ".well-known/openid-configuration",
            "version": "v2.0"
        },
        "settings": {
            "isB2C": true,
            "validateIssuer": true,
            "passReqToCallback": false,
            "loggingLevel": "info"
        }
    }
    
  2. 更新 config.json 檔案中的下列屬性:

區段 Key
認證 tenantName Azure AD B2C 租用戶名稱的第一個部分 (例如 fabrikamb2c)。
認證 clientID Web API 應用程式識別碼。 如需了解如何取得您的 Web API 應用程式註冊識別碼,請參閱必要條件
原則 policyName 使用者流程或自訂原則。 如需了解如何取得您的使用者流程或原則,請參閱必要條件
resource scope 您 Web API 應用程式註冊範圍,例如 [tasks.read]。 如需了解如何取得您的 Web API 範圍,請參閱必要條件

步驟 2:建立 Web Node Web 應用程式

遵循下列步驟,建立 Node Web 應用程式。 此 Web 應用程式會驗證使用者,以取得用於呼叫您在步驟 1 中所建立 Node Web API 的存取權杖:

步驟 2.1:建立 Node 專案

建立資料夾以保存您的 Node 應用程式,例如 call-protected-api

  1. 在終端機中,將目錄變更為您的 Node 應用程式資料夾 (例如 cd call-protected-api),然後執行 npm init -y。 此命令會為 Node.js 專案建立預設 packages.json 檔案。

  2. 在終端機中執行 npm install express。 此命令會安裝 Express 架構。

  3. 建立更多資料夾與檔案,達成下列專案結構:

    call-protected-api/
    ├── index.js
    └── package.json
    └── .env
    └── views/
        └── layouts/
            └── main.hbs
        └── signin.hbs
        └── api.hbs
    

    views 資料夾包含 Web 應用程式 UI 的 Handlebar 檔案。

步驟 2.2:安裝相依項目

在終端機中,執行下列命令以安裝 dotenvexpress-handlebarsexpress-session@azure/msal-node 套件:

npm install dotenv
npm install express-handlebars
npm install express
npm install axios
npm install express-session
npm install @azure/msal-node

步驟 2.3:建置 Web 應用程式 UI 元件

  1. main.hbs 檔案中新增下列程式碼:

    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no">
        <title>Azure AD B2C | Enable authenticate on web API using MSAL for B2C</title>
    
        <!-- adding Bootstrap 4 for UI components  -->
        <!-- CSS only -->
        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
        <link rel="SHORTCUT ICON" href="https://c.s-microsoft.com/favicon.ico?v2" type="image/x-icon">
      </head>
      <body>
        <nav class="navbar navbar-expand-lg navbar-dark bg-primary">
          <a class="navbar-brand" href="/">Microsoft Identity Platform</a>
            {{#if showSignInButton}}
                <div class="ml-auto">
                    <a type="button" id="SignIn" class="btn btn-success" href="/signin" aria-haspopup="true" aria-expanded="false">
                        Sign in to call PROTECTED API
                    </a>
                    <a type="button" id="SignIn" class="btn btn-warning" href="/api" aria-haspopup="true" aria-expanded="false">
                        Or call the ANONYMOUS API 
                     </a>
                </div>
            {{else}}
                    <p class="navbar-brand d-flex ms-auto">Hi {{givenName}}</p>
                    <a class="navbar-brand d-flex ms-auto" href="/signout">Sign out</a>
            {{/if}}
        </nav>
        <br>
        <h5 class="card-header text-center">MSAL Node Confidential Client application with Auth Code Flow</h5>
        <br>
        <div class="row" style="margin:auto" >
          {{{body}}}
        </div>
        <br>
        <br>
      </body>
    </html>
    

    main.hbs 檔案位於 layout 資料夾中,且應包含整個應用程式所需的所有 HTML 程式碼。 其會實作以 Bootstrap 5 CSS 架構所建置的 UI。 從頁面變更為頁面的所有 UI (例如 signin.hbs) 都會置於顯示為 {{{body}}} 的預留位置中。

  2. signin.hbs 檔案中新增下列程式碼:

    <div class="col-md-3" style="margin:auto">
      <div class="card text-center">
        <div class="card-body">
          {{#if showSignInButton}}
    
          {{else}}
               <h5 class="card-title">You have signed in</h5>
              <a type="button" id="Call-api" class="btn btn-success" href="/api" aria-haspopup="true" aria-expanded="false">
                  Call the PROTECTED API
              </a>
          {{/if}}
        </div>
        </div>
      </div>
    </div>
    
  3. api.hbs 檔案中新增下列程式碼:

    <div class="col-md-3" style="margin:auto">
      <div class="card text-center bg-{{bg_color}}">
        <div class="card-body">
    
              <h5 class="card-title">{{data}}</h5>
    
        </div>
      </div>
    </div>
    

    此頁面會顯示來自 API 的回應。 Bootstrap 卡片中的 bg-{{bg_color}} 類別屬性,可讓 UI 針對不同的 API 端點,顯示不同的背景色彩。

步驟 2.4:完成 Web 應用程式伺服器程式碼

  1. .env 檔案中新增下列程式碼,其中包含伺服器 HTTP 連接埠、應用程式註冊詳細資料,以及登入與註冊使用者流程/原則詳細資料:

    SERVER_PORT=3000
    #web apps client ID
    APP_CLIENT_ID=<You app client ID here>
    #session secret
    SESSION_SECRET=sessionSecretHere
    #web app client secret
    APP_CLIENT_SECRET=<Your app client secret here>
    #tenant name
    TENANT_NAME=<your-tenant-name>
    #B2C sign up and sign in user flow/policy name and authority
    SIGN_UP_SIGN_IN_POLICY_AUTHORITY=https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<sign-in-sign-up-user-flow-name>
    AUTHORITY_DOMAIN=https://<your-tenant-name>.b2clogin.com
    #client redorect url
    APP_REDIRECT_URI=http://localhost:3000/redirect
    LOGOUT_ENDPOINT=https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<sign-in-sign-up-user-flow-name>/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000
    

    修改 .env 檔案中的值 (如設定範例 Web 應用程式中所述)

  2. index.js 檔案中,新增下列程式碼:

    /*
     * Copyright (c) Microsoft Corporation. All rights reserved.
     * Licensed under the MIT License.
     */
    require('dotenv').config();
    const express = require('express');
    const session = require('express-session');
    const {engine}  = require('express-handlebars');
    const msal = require('@azure/msal-node');
    //Use axios to make http calls 
    const axios = require('axios');
    
    //<ms_docref_configure_msal>
    /**
     * Confidential Client Application Configuration
     */
     const confidentialClientConfig = {
        auth: {
            clientId: process.env.APP_CLIENT_ID, 
            authority: process.env.SIGN_UP_SIGN_IN_POLICY_AUTHORITY, 
            clientSecret: process.env.APP_CLIENT_SECRET,
            knownAuthorities: [process.env.AUTHORITY_DOMAIN], //This must be an array
            redirectUri: process.env.APP_REDIRECT_URI,
            validateAuthority: false
        },
        system: {
            loggerOptions: {
                loggerCallback(loglevel, message, containsPii) {
                    console.log(message);
                },
                piiLoggingEnabled: false,
                logLevel: msal.LogLevel.Verbose,
            }
        }
    };
    
    // Initialize MSAL Node
    const confidentialClientApplication = new msal.ConfidentialClientApplication(confidentialClientConfig);
    //</ms_docref_configure_msal>
    // Current web API coordinates were pre-registered in a B2C tenant.
    
    //<ms_docref_api_config>
    const apiConfig = {
        webApiScopes: [`https://${process.env.TENANT_NAME}.onmicrosoft.com/tasks-api/tasks.read`],
        anonymousUri: 'http://localhost:5000/public',
        protectedUri: 'http://localhost:5000/hello'
    };
    //</ms_docref_api_config>
    
    /**
     * The MSAL.js library allows you to pass your custom state as state parameter in the Request object
     * By default, MSAL.js passes a randomly generated unique state parameter value in the authentication requests.
     * 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.
     * For more information, visit: https://docs.microsoft.com/azure/active-directory/develop/msal-js-pass-custom-state-authentication-request
     */
    const APP_STATES = {
        LOGIN: 'login',
        CALL_API:'call_api'   
    }
    
    
    /** 
     * Request Configuration
     * We manipulate these two request objects below 
     * to acquire a token with the appropriate claims.
     */
     const authCodeRequest = {
        redirectUri: confidentialClientConfig.auth.redirectUri,
    };
    
    const tokenRequest = {
        redirectUri: confidentialClientConfig.auth.redirectUri,
    };
    
    
    /**
     * Using express-session middleware. Be sure to familiarize yourself with available options
     * and set them as desired. Visit: https://www.npmjs.com/package/express-session
     */
     const sessionConfig = {
        secret: process.env.SESSION_SECRET,
        resave: false,
        saveUninitialized: false,
        cookie: {
            secure: false, // set this to true on production
        }
    }
    //Create an express instance
    const app = express();
    
    //Set handlebars as your view engine
    app.engine('.hbs', engine({extname: '.hbs'}));
    app.set('view engine', '.hbs');
    app.set("views", "./views");
    
    app.use(session(sessionConfig));
    
    /**
     * This method is used to generate an auth code request
     * @param {string} authority: the authority to request the auth code from 
     * @param {array} scopes: scopes to request the auth code for 
     * @param {string} state: state of the application, tag a request
     * @param {Object} res: express middleware response object
     */
    
     const getAuthCode = (authority, scopes, state, res) => {
        // prepare the request
        console.log("Fetching Authorization code")
        authCodeRequest.authority = authority;
        authCodeRequest.scopes = scopes;
        authCodeRequest.state = state;
    
        //Each time you fetch Authorization code, update the authority in the tokenRequest configuration
        tokenRequest.authority = authority;
    
        // request an authorization code to exchange for a token
        return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
            .then((response) => {
                console.log("\nAuthCodeURL: \n" + response);
                //redirect to the auth code URL/send code to 
                res.redirect(response);
            })
            .catch((error) => {
                res.status(500).send(error);
            });
    }
    
    app.get('/', (req, res) => {
        res.render('signin', { showSignInButton: true });
    });
    
    
    
    app.get('/signin',(req, res)=>{ 
            //Initiate a Auth Code Flow >> for sign in
            //Pass the api scopes as well so that you received both the IdToken and accessToken
            getAuthCode(process.env.SIGN_UP_SIGN_IN_POLICY_AUTHORITY,apiConfig.webApiScopes, APP_STATES.LOGIN, res);
    });
    
    
    app.get('/redirect',(req, res)=>{    
        
        if (req.query.state === APP_STATES.LOGIN) {
            // prepare the request for calling the web API
            tokenRequest.authority = process.env.SIGN_UP_SIGN_IN_POLICY_AUTHORITY;
            tokenRequest.scopes = apiConfig.webApiScopes;
            tokenRequest.code = req.query.code;
            confidentialClientApplication.acquireTokenByCode(tokenRequest)
            .then((response) => {
                req.session.accessToken = response.accessToken;
                req.session.givenName = response.idTokenClaims.given_name;
                console.log('\nAccessToken:' + req.session.accessToken);
                res.render('signin', {showSignInButton: false, givenName: response.idTokenClaims.given_name});
            }).catch((error) => {
                console.log(error);
                res.status(500).send(error);
            });
        }else{
            res.status(500).send('We do not recognize this response!');
        }
    });
    
    //<ms_docref_api_express_route>
    app.get('/api', async (req, res) => {
        if(!req.session.accessToken){
            //User is not logged in and so they can only call the anonymous API
            try {
                const response = await axios.get(apiConfig.anonymousUri);
                console.log('API response' + response.data); 
                res.render('api',{data: JSON.stringify(response.data), showSignInButton: true, bg_color:'warning'});
            } catch (error) {
                console.error(error);
                res.status(500).send(error);
            }         
        }else{
            //Users have the accessToken because they signed in and the accessToken is still in the session
            console.log('\nAccessToken:' + req.session.accessToken);
            let accessToken = req.session.accessToken;
            const options = {
                headers: {
                    //accessToken used as bearer token to call a protected API
                    Authorization: `Bearer ${accessToken}`
                }
            };
    
            try {
                const response = await axios.get(apiConfig.protectedUri, options);
                console.log('API response' + response.data); 
                res.render('api',{data: JSON.stringify(response.data), showSignInButton: false, bg_color:'success', givenName: req.session.givenName});
            } catch (error) {
                console.error(error);
                res.status(500).send(error);
            }
        }     
    });
    
    //</ms_docref_api_express_route>
    
    /**
     * Sign out end point
    */
    app.get('/signout',async (req, res)=>{    
        logoutUri = process.env.LOGOUT_ENDPOINT;
        req.session.destroy(() => {
            res.redirect(logoutUri);
        });
    });
    app.listen(process.env.SERVER_PORT, () => console.log(`Msal Node Auth Code Sample app listening on port !` + process.env.SERVER_PORT));
    

    index.js 檔案中的程式碼,由全域變數與 ExpressRoute 所組成。

    全域變數

    • confidentialClientConfig:MSAL 設定物件,用於建立機密用戶端應用程式物件。

      /**
       * Confidential Client Application Configuration
       */
       const confidentialClientConfig = {
          auth: {
              clientId: process.env.APP_CLIENT_ID, 
              authority: process.env.SIGN_UP_SIGN_IN_POLICY_AUTHORITY, 
              clientSecret: process.env.APP_CLIENT_SECRET,
              knownAuthorities: [process.env.AUTHORITY_DOMAIN], //This must be an array
              redirectUri: process.env.APP_REDIRECT_URI,
              validateAuthority: false
          },
          system: {
              loggerOptions: {
                  loggerCallback(loglevel, message, containsPii) {
                      console.log(message);
                  },
                  piiLoggingEnabled: false,
                  logLevel: msal.LogLevel.Verbose,
              }
          }
      };
      
      // Initialize MSAL Node
      const confidentialClientApplication = new msal.ConfidentialClientApplication(confidentialClientConfig);
      
    • apiConfig:包含 webApiScopes 屬性 (其值必須為陣列),也就是在 Web API 中設定及授與 Web 應用程式的範圍。 其也有要呼叫之 Web API 的 URI,也就是 anonymousUriprotectedUri

      const apiConfig = {
          webApiScopes: [`https://${process.env.TENANT_NAME}.onmicrosoft.com/tasks-api/tasks.read`],
          anonymousUri: 'http://localhost:5000/public',
          protectedUri: 'http://localhost:5000/hello'
      };
      
    • APP_STATES:要求內含的值,其同時也會傳回到權杖回應中。 用於區分從 Azure AD B2C 所收到的回應。

    • authCodeRequest:用於擷取授權碼的設定物件。

    • tokenRequest:用於依授權碼取得權杖的設定物件。

    • sessionConfig:Express 工作階段的設定物件。

    • getAuthCode:此方法會建立授權要求的 URL,讓使用者可輸入認證,並同意該應用程式。 其會使用在 ConfidentialClientApplication 類別中所定義的 getAuthCodeUrl 方法。

    ExpressRoute

    • /:
      • 其為 Web 應用程式的項目,並會轉譯 signin 頁面。
    • /signin:
      • 登入使用者。
      • 呼叫 getAuthCode() 方法,並將登入與註冊使用者流程/原則的 authorityAPP_STATES.LOGINapiConfig.webApiScopes,傳遞給該使用者。
      • 如此會要求終端使用者輸入其登入,而若使用者沒有帳戶,可以進行註冊。
      • 此端點所產生的最終回應,包括從 B2C 貼回 /redirect 端點的授權碼。
    • /redirect:
      • 其是設定為 Azure 入口網站中 Web 應用程式之重新導向 URI 的端點。
      • 其在 Azure AD B2C 回應中,會使用 state 查詢參數,以區分從 Web 應用程式提出的要求。
      • 若應用程式狀態為 APP_STATES.LOGIN,則會使用取得的授權碼,擷取使用 acquireTokenByCode() 方法的權杖。 使用 acquireTokenByCode 方法要求權杖時,會使用取得授權碼時所使用的相同範圍。 取得的權杖包括 accessTokenidTokenidTokenClaims。 取得 accessToken 之後,可以將其放在工作階段中,稍後用於呼叫 Web API。
    • /api:
      • 呼叫 Web API。
      • accessToken 不在工作階段中,請呼叫匿名 API 端點 (http://localhost:5000/public),否則,請呼叫受保護的 API 端點 (http://localhost:5000/hello)。
    • /signout:
      • 登出使用者。
      • 清除 Web 應用程式工作階段,並對 Azure AD B2C 登出端點發出 HTTP 呼叫。

步驟 3:執行 Web 應用程式與 API

遵循執行 Web 應用程式與 API 中的步驟,測試您的 Web 應用程式與 Web API。

後續步驟