在 AWS Blu Age 現代化大型主機應用程式中實作 Microsoft Entra ID 型身分驗證

Vishal Jaswani 和 Rimpy Tewani，Amazon Web Services

Summary

使用重構模式進行現代化的大型主機應用程式，例如 AWS Mainframe Modernization Refactor with AWS Blu Age，需要謹慎地將身分驗證機制整合到新的應用程式架構。此整合通常以後現代化活動的形式處理。任務可能很複雜，通常涉及現有身分驗證系統的遷移或外部化，以符合現代安全標準和雲端原生實務。開發人員需要考慮如何在現代化應用程式執行期環境和程式庫的限制範圍內有效實作身分驗證。現代化之後， AWS 提供方法讓您更輕鬆地整合 AWS Blu Age 現代程式碼與身分和存取管理系統，例如 Amazon Cognito 和 Microsoft Entra ID （先前稱為 Azure AD)。

此模式說明如何在身分驗證提供者為 Microsoft Entra ID 時，在現代化應用程式中實作身分驗證機制，而不必花時間進行研究和試驗。模式提供：

• 來自 Microsoft Authentication Library (MSAL) 和其他 Microsoft Entra ID 文件且對身分驗證實作至關重要的欄位測試和相關角度程式庫。 

• 使用 OAuth 2.0 在 AWS Blu Age Runtime 上啟用 Spring Security 所需的組態。

• 擷取已驗證使用者身分並將其傳遞至 AWS Blu Age Runtime 的程式庫。

• 我們建議實作的安全措施。

• 針對 Microsoft Entra ID 設定中常見問題的疑難排解秘訣。

注意

此模式使用 AWS Blu Age OAuth 延伸程式庫，該程式庫是提供給客戶做為其AWS 專業服務參與的一部分。此程式庫不屬於 AWS Blu Age 執行期。

先決條件和限制

先決條件

• 由 AWS Blu Age 大型主機現代化重構工具產生的現代化應用程式。此模式使用 CardDemo 做為範例開放原始碼大型主機應用程式。

• AWS Blu Age OAuth 延伸程式庫，由 AWS Blu Age 團隊在您與 AWS Professional Services 互動期間提供。

• 部署和測試現代化應用程式的作用中 AWS 帳戶 。

• 熟悉 AWS Blu Age 組態檔案和 Microsoft Entra ID 基本概念。

限制

• 此模式涵蓋 OAuth 2.0 身分驗證和基本字符型授權流程。進階授權案例和精細存取控制機制不在範圍內。

• 有些 AWS 服務 完全無法使用 AWS 區域。如需區域可用性，請參閱AWS 服務 依區域。如需特定端點，請參閱服務端點和配額，然後選擇服務的連結。

產品版本

此模式的開發方式是使用：

• AWS Blu Age Runtime 4.1.0 版 （此模式也適用於回溯相容的更新版本）

• MSAL 程式庫 3.0.23 版

• Java 開發套件 (JDK) 第 17 版

• 角度版本 16.1

架構

來源技術堆疊

在一般大型主機環境中，身分驗證是透過使用者設定檔實作。這些設定檔可識別系統的使用者、定義誰可以登入，以及指定使用者可以在系統資源上執行哪些函數。使用者設定檔由安全主管或安全管理員管理。

目標技術堆疊

• Microsoft Entra ID

• 現代化 Java Spring 型後端

• AWS Blu Age 執行時間

• 使用 OAuth 2.0 的 Spring Security

• 角度單一頁面應用程式 (SPA)

目標架構

AWS Blu Age 執行時間預設支援以 OAuth 2.0 為基礎的身分驗證，因此模式會使用該標準來保護後端 APIs。

下圖說明程序流程。

注意

圖表包含 Amazon Aurora 做為資料庫現代化的範例，雖然此模式的步驟中不包含 Aurora。

其中：

1. 使用者嘗試使用 Microsoft Entra ID 進行身分驗證。

2. Microsoft Entra ID 會傳回應用程式在後續呼叫中使用的重新整理、存取和 ID 字符。

3. MSAL 攔截器會在 HTTPS 請求的 Authorization標頭中包含存取字符，以呼叫 AWS Blu Age Runtime。

4. AWS Blu Age extension-oauth程式庫會使用 AWS Blu Age Runtime 組態檔案 (application-main.yml) 從 標頭擷取使用者資訊，並將此資訊放在 SharedContext 物件中，讓商業邏輯可以使用它。

   注意

   SharedContext 是由 AWS Blu Age 提供的執行期元件，可管理現代化應用程式中的應用程式內容和狀態資訊。如需 AWS Blu Age Runtime 元件和更新的詳細資訊，請參閱 AWS Mainframe Modernization 文件中的 AWS Blu Age 版本備註。如需 application-main.yml 檔案的詳細資訊，請參閱 AWS Mainframe Modernization 文件中的設定 AWS Blu Age Runtime 組態。

5. AWS Blu Age Runtime 會檢查權杖是否存在。 

   1. 如果字符存在，它會透過與 Microsoft Entra ID 通訊來檢查字符的有效性。 

   2. 如果字符不存在， AWS 則 Blu Age Runtime 會傳回 HTTP 狀態碼為 403 的錯誤。

6. 如果字符有效， AWS 則藍檔執行期允許業務邏輯繼續。如果字符無效， AWS 則 Blu Age Runtime 會傳回 HTTP 狀態碼為 403 的錯誤。

OAuth 2.0 工作流程

如需 OAuth 2.0 工作流程的高階圖表，請參閱 Microsoft Entra 文件。

工具

AWS 服務

• AWS Mainframe Modernization 提供工具和資源，協助您規劃和實作從大型主機到 AWS 受管執行期環境的遷移和現代化。您可以使用 Blu AWS Age 提供的此服務重構功能，來轉換和現代化舊版大型主機應用程式。

程式碼儲存庫

CardDemo 應用程式已更新，以示範與 Microsoft Entra ID 的整合。您可以從 GitHub 儲存庫存取此模式的程式碼。

後端組態

此模式需要變更application-main.yml 組態檔案，才能在後端應用程式上使用 OAuth 2.0 來啟用 Spring Security。 .yml 檔案如下所示：

gapwalk-application.security: enabled
gapwalk-application:
  security: 
    identity: oauth
    issuerUri: ${issuerUrl}
    claim:
      claims:
        -
          claimName: upn
          claimMapValue: username
spring:
  autoconfigure:
    exclude:
     - org.springframework.boot.autoconfigure.security.oauth2.client.servlet.OAuth2ClientAutoConfiguration
     - org.springframework.boot.autoconfigure.security.oauth2.resource.servlet.OAuth2ResourceServerAutoConfiguration
  security:
    oauth2:
      client:
        registration: 
          azure:
            client-id: {clientId}
            client-secret: ${clientSecret}
            provider: azure
            authorization-grant-type: authorization_code
            redirect-uri: ${redirectUri}
            scope: openid
           
        provider:
          azure:
            authorization-uri: ${gapwalk-application.security.issuerUri}/oauth2/v2.0/authorize
            token-uri:  ${gapwalk-application.security.issuerUri}/oauth2/v2.0/token
            jwk-set-uri: ${gapwalk-application.security.issuerUri}/discovery/v2.0/keys
      resourceserver:
        jwt:
          jwk-set-uri: ${gapwalk-application.security.issuerUri}/discovery/v2.0/keys

AWS Blu Age OAuth 延伸篩選條件程式庫

AWS Blu Age OAuth 延伸程式庫是由 AWS Blu Age 團隊在您與 AWS Professional Services 互動期間提供。

此程式庫會讀取上一個程式碼區塊中顯示的 fie application-main.yml 中的claim.claims組態。此組態是清單。清單中的每個項目提供兩個值： claimName和 claimMapValue。 claimName代表前端傳送的 JSON Web 權杖 (JWT) 中的金鑰名稱，而 claimMapValue是 中的金鑰名稱SharedContext。例如，如果您想要在後端擷取使用者 ID，請將 claimName設定為 JWT 中的金鑰名稱，該 JWT 會保留由 Microsoft Entra ID userId提供的 ，並將 claimMapValue設定為金鑰名稱，以在後端程式碼中擷取使用者 ID。

例如，如果您在 UserId中設定 claimMapValue，您可以使用下列程式碼來擷取使用者 ID：

SharedContext.get().getValue("userId", [UserId]);

最佳實務

在您實作此模式時，請考量下列重要的安全考量。

重要

此模式為身分驗證整合提供了基礎。除了本節中討論的安全措施之外，我們建議您在部署到生產環境之前，根據您的業務需求實作安全措施。

• AWS 組態安全性。 將敏感組態值從 application-main.yml 移至 AWS Secrets Manager。例如，使用 Secrets Manager 設定下列屬性：

  security:
      oauth2:
        client:
          registration: 
            azure:
              client-id: {clientId}
              client-secret: ${clientSecret}

  如需如何使用 Secrets Manager 設定 AWS Blu Age 參數的詳細資訊，請參閱 AWS Mainframe Modernization 文件中的 AWS Blu Age Runtime 秘密。

• 執行期環境保護。使用適當的 AWS 安全控制設定現代化應用程式環境：

  server: 
    tomcat: 
      remoteip: 
       protocol-header: X-Forwarded-Proto 
       remote-ip-header: X-Forwarded-For 
    forward-headers-strategy: NATIVE

• Amazon CloudWatch 記錄。考慮新增 檔案logback-spring.xml to src/main/resources：

  <configuration> 
   <appender name="CLOUDWATCH" class="com.amazonaws.services.logs.logback.CloudWatchAppender">  
     <logGroup>/aws/bluage/application</logGroup> 
     <logStream>${AWS_REGION}-${ENVIRONMENT}</logStream> 
     <layout> 
      <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern> 
     </layout> 
   </appender> 
  
   <root level="INFO"> 
   <appender-ref ref="CLOUDWATCH"/> 
   </root> 
  </configuration>

  如需使用 CloudWatch 啟用追蹤的資訊，請參閱 CloudWatch 文件中的啟用追蹤以記錄相互關聯。

• 字符組態和處理。在 Microsoft Entra ID 中設定權杖生命週期，以符合您的安全需求。將存取權杖設定為在 1 小時內過期，並將重新整理權杖設定為在 24 小時內過期。在 AWS Blu Age Runtime 組態 (application-main.yml) 中，請確定 JWT 驗證已使用來自 Entra ID 應用程式註冊的確切發行者 URI 和對象值正確設定。

  當字符過期並重新整理時：

  1. 角形應用程式的錯誤攔截器會透過 MSAL 取得新權杖來處理 401 回應。

  2. 新的字符會與後續請求一起傳送。

  3. AWS Blu Age Runtime 的 OAuth 篩選條件會驗證新的權杖，並自動SharedContext更新目前的使用者資訊。這可確保商業邏輯繼續透過SharedContext.get().getValue()呼叫存取有效的使用者內容。

  如需 AWS Blu Age Runtime 元件及其更新的詳細資訊，請參閱 AWS Blu Age 版本備註。

• AWS Blu Age 執行期安全性。 AWS Blu Age 提供的oauth2-ext程式庫必須放置在具有適當檔案許可的正確共用目錄位置 ({app-server-home}/shared/)。檢查日誌中的SharedContext物件人口，確認程式庫已成功從 JWTs擷取使用者資訊。

• 特定宣告組態。在 中application-main.yml，明確定義您需要從 Microsoft Entra ID 取得的宣告。例如，若要擷取使用者的電子郵件和角色，請指定：

  gapwalk-application:
    security:
      claim:
        claims:
          - claimName: upn
            claimMapValue: username
          - claimName: roles
            claimMapValue: userRoles
          - claimName: email
            claimMapValue: userEmail

• 錯誤處理。新增錯誤處理，以解決 Angular 應用程式中的身分驗證失敗；例如：

  @Injectable()
  export class AuthErrorInterceptor implements HttpInterceptor {
    intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
      return next.handle(request).pipe(
        catchError((error: HttpErrorResponse) => {
          if (error.status === 401) {
            // Handle token expiration
            this.authService.login();
          }
          if (error.status === 403) {
            // Handle unauthorized access
            this.router.navigate(['/unauthorized']);
          }
          return throwError(() => error);
        })
      );
    }
  }

• 工作階段逾時組態。在 AWS Blu Age Runtime 和 Microsoft Entra ID 中設定工作階段逾時設定。例如，將下列程式碼新增至您的 application-main.yml 檔案：

  server:
    servlet:
      session:
        timeout: 3600 # 1 hour in seconds

• MsalGuard。您必須為所有受保護的路由實作 MsalGuard 功能，以防止未經授權的存取。例如：

  const routes: Routes = [
      { path: '', redirectTo: '/transaction-runner', pathMatch: 'full' },
      { path: 'transaction-runner', component: TransactionRunnerComponent, canActivate:guards },
      { path: 'user-info', component: UserInfoComponent, canActivate:guards },
      { path: 'term/:transid/:commarea', component: TermComponent, canActivate:guards },
  	{ path: 'code', component: TransactionRunnerComponent  }
  ];

  沒有 MsalGuard 保護的路由無需身分驗證即可存取，可能公開敏感功能。確定所有需要身分驗證的路由在其組態中都包含防護。

史詩

設定 Microsoft Entra ID

任務	描述	所需的技能
設定 Microsoft Azure 帳戶以建立 Entra ID。	如需選項和說明，請參閱 Microsoft Azure 網站。	應用程式開發人員
在應用程式中設定 Microsoft Entra ID。	若要了解如何將 Microsoft Entra ID B2C (Azure AD B2C) 身分驗證新增至您的角度 SPA，請參閱 Microsoft 文件。具體而言： 註冊您的應用程式並記錄識別符。 透過新增和公開自訂範圍來公開 AWS Blu Age 交易端點。  在您定義範圍和 API URL 之後，請在程式碼儲存庫中 environment.ts 檔案的 apiUri和 apiScope 屬性中設定這些值。	應用程式開發人員

複製儲存庫並部署您的 AWS Blu Age 程式碼

任務	描述	所需的技能
複製 GitHub 儲存庫以取得身分驗證所需的角度程式碼。	執行下列命令，將隨此模式提供的 GitHub 儲存庫複製到您的本機目前工作目錄： git clone https://github.com/aws-samples/sample-microsoft-entra-id-based-auth-in-aws-bluage-modernized-mainframe-app.git	應用程式開發人員
在 Tomcat 伺服器上部署 AWS Blu Age 現代化程式碼以實作身分驗證。	若要設定包含 Tomcat 和 Angular 開發伺服器的本機環境，請遵循 AWS Blu Age 團隊提供的安裝步驟，做為您與 AWS Professional Services 客戶互動的一部分。	應用程式開發人員

建置身分驗證解決方案

任務	描述	所需的技能
啟用 AWS Blu Age Runtime 安全性來保護 AWS Blu Age REST API 端點。	設定 AWS Blu Age Runtime 使用application-main.yml的檔案，如下所示。如需此檔案的範例，請參閱此模式中稍早的程式碼儲存庫一節。 spring:security:oauth2:client:* 啟用 Spring Security OAuth 2.0 用戶端支援。將設定取代為 Microsoft Entra ID 設定專屬的值。 spring:security:oauth2:resourceserver 啟用 Spring Security OAuth 2.0 資源伺服器支援。 gapwalk-application.security.issuerUri 指定用於擷取組態資訊的身分提供者 URL，例如授權端點、字符端點等。 gapwalk-application.security.identity 應該設定為 oauth。 gapwalk-application.security.claim.claims 指定擷取使用者 IDs和使用者名稱所需的宣告清單。  如需範例，請參閱此模式稍早的程式碼儲存庫一節。 gapwalk-application.security 應該設定為 enabled。 spring.autoconfigure.exclude 應移除以啟用身分驗證。	應用程式開發人員
將來自您本機環境的範例程式碼併入您的 Blu Age 現代化角度程式碼基礎。	如需有關如何將範例納入 AWS Blu Age 現代化角度程式碼庫的資訊，請參閱此模式稍早的程式碼儲存庫一節。	應用程式開發人員
將程式oauth2-ext庫放在共用目錄中。	將程式oauth2-ext庫放在應用程式伺服器的 共用目錄中，以便您的 AWS Blu Age 現代化應用程式可以使用它。 執行下列命令： cd oauth2-ext/target cp extension-oauth-filter-<version>.jar /{app-server-home}/shared/	應用程式開發人員

部署身分驗證解決方案

任務	描述	所需的技能
部署前端應用程式。	執行下列命令，在本機啟動前端應用程式： npm install ng serve --ssl npm start 注意 將 --ssl 旗標新增至 ng serve命令可確保開發伺服器使用 HTTPS，這比其他通訊協定更安全，並提供更好的生產環境模擬。	應用程式開發人員
啟動後端應用程式。	在 Eclipse 中啟動 Tomcat 伺服器。	應用程式開發人員

測試應用程式。

任務	描述	所需的技能
測試登入功能。	在 存取本機部署的應用程式，http://localhost:4200以確認要求使用者確認其身分。 注意 HTTP 在此處用於示範目的。在生產或其他可公開存取的環境中，為了安全起見，您必須使用 HTTPS。即使對於本機開發，我們建議您盡可能設定 HTTPS。 應該會出現 Microsoft 登入提示，而且應該允許在 Microsoft Entra ID 中設定的使用者存取應用程式。	應用程式開發人員
在請求中測試授權標頭。	注意 下列步驟使用 CardDemo 應用程式做為範例。其他現代應用程式的測試步驟會有所不同。 CC00 在 CardDemo 應用程式中啟動交易。 使用使用者登入資料登入。例如，如果您使用的是 AWS Blu Age Level 3 自定進度研討會，則可以使用PASSWORD登入資料的名稱USER0001和密碼。 在瀏覽器的相同索引標籤中開啟開發人員工具視窗。 開啟網路索引標籤，並檢查傳送至後端 的請求http://localhost:8080/gapwalk-application/transaction。 檢查請求標頭，並確認您是否看到具有 值的授權標頭Bearer <token>，其中 <token> 是 Microsoft Entra ID 產生的值。	應用程式開發人員
測試登出功能。	選擇退出以登出，然後嘗試再次存取應用程式。它應該會顯示新的登入提示。	應用程式開發人員

故障診斷

問題	解決方案
Microsoft Entra ID 發行的權杖與 Spring Boot OAuth 2.0 安全性不相容。	如需問題的解決方法，請參閱 OAuth 部落格上的 Microsoft Entra ID OAuth 流程。 OAuth
一般字符相關問題。	若要解碼和檢視 JWT 權杖的內容，請使用 https://jwt.io/ 網站。

相關資源

• 如需有關使用 AWS Blu Age 重構應用程式的資訊，請參閱 AWS Mainframe Modernization 文件。

• 若要了解 OAuth 2.0 的運作方式，請參閱 OAuth 2.0 網站。

• 如需 Microsoft Authentication Library (MSAL) 的概觀，請參閱 Microsoft Entra 文件。

• 如需 AS/400 系統上使用者設定檔的資訊，請參閱 IBM i (AS400) 教學課程。

• 如需 Microsoft 身分平台中的 OAuth 2.0 和 OpenID Connect (OIDC) 身分驗證流程，請參閱 Microsoft Entra 文件。