瞭解Node.js應用程式與Oracle Identity Cloud Service之間的認證

瞭解三個認證流程

Oracle Identity Cloud Service支援Node.js SDK 的三方式認證流程。在此流程中，使用者會直接與Oracle Identity Cloud Service互動。使用者登入之後，Oracle Identity Cloud Service會發出 SDK 為使用者存取記號交換的授權代碼。Node.js Web 應用程式會使用此存取記號，將存取權授予使用者應用程式中受保護的資源。三方流程使用授權代碼授權類型.

為了提高安全性，Oracle建議您使用三方流程來整合您的Node.js Web 應用程式與Oracle Identity Cloud Service以進行認證。透過使用授權代碼授權類型，您也可以存取Oracle Identity Cloud Service所保護的其他應用程式，而不需要重新驗證。

瞭解在Node.js應用程式使用 SDK 的主要使用案例

Node.js Web 應用程式實行兩個使用案例：一個用於驗證使用者，另一個用於存取登入使用者的詳細資訊。

下列資料流程圖表說明Web瀏覽器、Web應用程式以及每個使用案例之Oracle Identity Cloud Service之間的事件、呼叫與回應流程。

使用案例# 1:認證使用者

authenticate-user.png圖解說明

資料流程的方式如下：

使用者要求受保護的資源。
認證模組使用 SDK 產生Oracle Identity Cloud Service的要求-授權程式碼 URL，並將此 URL 作為 Web 瀏覽器的重導回應傳送。
Web 瀏覽器會呼叫 URL。
就會顯示Oracle Identity Cloud Service登入頁面。
使用者送出Oracle Identity Cloud Service登入證明資料.
使用者登入之後，Oracle Identity Cloud Service會為使用者建立階段作業並發出授權代碼。
Web 應用程式會呼叫後端 (或伺服器對伺服器) 來交換使用者存取記號的授權代碼。
Oracle Identity Cloud Service會發出存取記號。
系統便會建立階段作業，並將使用者重導至「首頁」。
Web 應用程式的「首頁」隨即顯示。

使用案例# 2:取得使用者的詳細資訊

get-details-user.png圖解說明

資料流程的方式如下：

使用者要求/myProfile資源。
Web 應用程式會使用 SDK 呼叫Oracle Identity Cloud Service，此 SDK 會使用儲存在使用者階段作業中的存取記號作為參數。
使用者的詳細資訊會以 JSON 物件的形式傳送至 Web 應用程式。
「我的設定檔」頁面會將 JSON 物件轉換為 HTML 內容。

瞭解方法和函數

Node.js SDK 是Node.js護照策略，您可以加入Node.js modules資料夾。此 SDK 也是以Node.js承諾為基礎。Node.js SDK 需要的所有協力廠商相依性都定義在 SDK 的 package.json檔案中。您必須在Node.js Web 應用程式中至少使用這組模組。

"dependencies": {
    "async": "^2.1.2",
    "bunyan": "^1.8.5",
    "cache-manager": "^2.2.0",
    "json-web-token": "^2.1.3",
    "jsonwebtoken": "^7.1.9",
    "jwk-to-pem": "^1.2.6",
    "jws": "^3.1.4",
    "lru": "^3.1.0",
    "passport": "^0.3.2",
    "promise": "^7.1.1",
    "querystring": "^0.2.0",
    "request": "^2.79.0",
    "rsa-pem-to-jwk": "^1.1.3",
    "util": "^0.10.3"
  },

Node.js Web 應用程式是使用Node.js express和express-handlebars模組所開發，而該模組會以每個 URL 的app.get()函數形式實行 URL 路由。

Node.js SDK 需要使用Oracle Identity Cloud Service連線資訊載入的 JSON 變數。Node.js Web 應用程式使用ids變數來儲存此資訊：

var ids = {
    oracle: {
         "ClientId": '123456789abcdefghij',
         "ClientSecret": 'abcde-12345-zyxvu-98765-qwerty',
         "ClientTenant": 'idcs-abcd1234',
         "IDCSHost": 'https://%tenant%.identity.oraclecloud.com',
         "AudienceServiceUrl" : 'https://idcs-abcd1234.identity.oraclecloud.com',
         "TokenIssuer": 'https://identity.oraclecloud.com/',
         "scope": 'urn:opc:idm:t.user.me openid',
         "logoutSufix": '/oauth2/v1/userlogout',
         "redirectURL": 'http://localhost:3000/callback'
    }
};
 
module.exports = ids;

以下是此 SDK 之每個必要屬性的簡要說明：

名稱	描述
`ClientId`	在Identity Cloud Service主控台中註冊Node.js Web 應用程式後所產生的從屬端 ID 值。
`ClientSecret`	在Identity Cloud Service主控台中註冊Node.js Web 應用程式之後所產生的從屬端密碼值。
`ClientTenant`	您Oracle Identity Cloud Service執行處理的網域前置碼。此前置碼通常類似於`idcs-abcd1234`。
`IDCSHost`	您Oracle Identity Cloud Service執行處理的網域字尾.在程式實際執行時，% tenant % 預留位置會取代為ClientTenant屬性的值。
`AudienceServiceUrl`	您Oracle Identity Cloud Service執行處理的完整網域名稱 URL.
`TokenIssuer`	對於此屬性，Oracle建議您保留`https://identity.oraclecloud.com/`值。
`scope`	範圍會控制應用程式可代表Oracle Identity Cloud Service使用者存取或處理的資料。如果應用程式使用 SDK 來認證使用者，則範圍為`openid`。如果應用程式使用 SDK 取得使用者的詳細資訊，則範圍為`urn:opc:idm:t.user.me openid`。

應用程式同時使用logoutSufix和redirectURL屬性。SDK 不需要。

Node.js應用程式實行/oauth/oracle URL 路由。當使用者決定使用Oracle Identity Cloud Service進行認證時，Web 瀏覽器會對此 URL 提出要求。此路徑使用 SDK 來產生Oracle Identity Cloud Service的授權 URL.

//Loading the configurations
var auth = require('./auth.js');
 
//Route for /oauth/oracle
app.get("/auth/oracle", function(req, res){
    //Authentication Manager loaded with the configurations.
    am = new IdcsAuthenticationManager(auth.oracle);
    //Using Authentication Manager to generate the Authorization Code URL, passing the
    //application's callback URL as parameter, along with code value and code parameter.
    am.getAuthorizationCodeUrl(auth.oracle.redirectURL, auth.oracle.scope, "1234", "code")
        .then(function(authZurl){
            //Redirecting the browser to the Oracle Identity Cloud Service Authorization URL.
            res.redirect(authZurl);
        }).catch(function(err){
            res.end(err);
        })
});

此函數會將 JSON 參數載入變數、初始化認證管理程式，並使用Node.js SDK 的IdcsAuthenticationManager.getAuthorizationCodeUrl()函數來產生授權代碼 URL。此功能使用承諾在產生授權代碼 URL 或在瀏覽器中呈現錯誤時，重新導向使用者的 Web 瀏覽器。

下列參數是用來產生授權代碼 URL：

名稱	描述
`auth.oracle.redirectURL`	使用者登入之後，Oracle Identity Cloud Service會將使用者的 Web 瀏覽器重導至此 URL。此 URL 必須符合您在Identity Cloud Service主控台中為信任應用程式設定的 URL。請參閱註冊Node.js應用程式，瞭解有關指定Node.js Web 應用程式之重導 URL 的詳細資訊。
`auth.oracle.scope`	認證的OAuth或OpenID Connect範圍。此應用程式僅需要`openid`認證。
`state`	OAuth協定定義此參數。範例Node.js Web 應用程式使用此代碼來檢查是否可以建立與Oracle Identity Cloud Service的通訊。在此範例中，此參數的值是`1234`。
`response_type`	授權代碼授權類型所需的參數。在此範例中，此參數的值是`code`。

使用者登入之後，Oracle Identity Cloud Service會將使用者的 Web 瀏覽器重導至開發人員必須實行的回呼 URL。Node.js Web 應用程式使用/callback路由來處理此要求。

//Route for /callback
app.get("/callback", function(req,res){
    //Authentication Manager loaded with the configurations.
    var am = new IdcsAuthenticationManager(auth.oracle);
    //Getting the authorization code from the "code" parameter
    var authZcode = req.query.code;
    //Using the Authentication Manager to exchange the Authorization Code to an Access Token.
    am.authorizationCode(authZcode)
        .then(function(result){
            //Getting the Access Token Value.
            res.cookie(config.IDCS_COOKIE_NAME, result.access_token);
            res.redirect('/auth.html');
        }).catch(function(err){
            res.end(err);
        })
});

Node.js應用程式使用授權代碼來要求存取記號。存取記號會儲存為 Cookie，然後傳送至 Web 瀏覽器供日後使用。

Node.js SDK 的IdcsAuthenticationManager.authorizationCode()函數也會使用承諾 (then-catch 敘述句) 將存取記號設為 Cookie，並將瀏覽器重導至/auth.html頁面。

Node.js SDK 是以Node.js護照架構為基礎。因此，您必須將存取記號作為標頭變數轉送至/auth URL 處理程式，並將passport.authenticate()方法與Oracle Identity Cloud Service策略名稱搭配使用作為參數：

//Uses passport to create a User Session in Node.js.
//Passport sets a user attribute in the request as a json object.
app.get('/auth', passport.authenticate(config.IDCS_STRATEGY_NAME, {}), function(req, res) {
   res.redirect('/home');
});

在passport.authenticate()方法建立應用程式階段作業之後，函數會將使用者的 Web 瀏覽器重導至/home應用程式中受保護的 URL。除了/home之外，Node.js Web 應用程式還有三個受保護的URLs：/appDetails、/userInfo和/myProfile。

每個受保護的 URL 都需要檢查使用者之前是否已建立階段作業。下列函數是供這些URLs的每個app.get()函數使用。

function ensureAuthenticated(req, res, next) {
   if (req.isAuthenticated()) {
      return next();
   }
   res.redirect('/login')
}

Node.js應用程式會處理/myProfile路由，並使用passport.authenticate()方法取得階段作業中設定的資訊，如下所示：

app.get("/myProfile", ensureAuthenticated, function(req,res){
   //User Manager loaded with the configurations
   var um = new IdcsUserManager(auth.oracle);
   //Using the user id in the request attribute to render the user json in the screen.
   um.getUser(req.user.id)
      .then(function(user){
         res.render('myProfile', {
         layout: 'privateLayout',
         title: 'My Profile',
         user: req.user,
         userInfo: JSON.stringify(user, null, 2)
         });
      }).catch(function(err1){
         res.end(err1);
      })
});

起始UserManager物件之後，/myProfile路由的處理程式會使用 SDK 的IdcsUserManager.getUser()函數來取得代表使用者設定檔的 JSON 物件。應用程式會將 JSON 物件傳送至myProfile.handlebars檔案，以在 Web 瀏覽器中呈現。

若要將使用者從應用程式與Oracle Identity Cloud Service之間的 Single Sign-On 登出，Node.js Web 應用程式會實行/logout路由，如下所示：

app.get('/logout', function(req, res){
   req.logout();
   res.clearCookie();
   res.redirect(auth.oracle.IDCSHost + auth.oracle.logoutSufix);
});

此路由會讓應用程式的階段作業無效,移除先前設定的所有 Cookie,然後將使用者的 Web 瀏覽器重導至Oracle Identity Cloud Service的OAuth登出 URL.此 URL 是在 JSON 組態物件中設定。