Implement Microsoft Entra ID-based authentication in an AWS Blu Age modernized mainframe application

Field-tested and relevant Angular libraries from the Microsoft Authentication Library (MSAL) and other Microsoft Entra ID documentation that are essential to the authentication implementation. 

Configurations required on the AWS Blu Age Runtime to enable Spring Security by using OAuth 2.0.

A library that captures authenticated users’ identities and passes them to the AWS Blu Age Runtime.

Security measures that we recommend implementing.

Troubleshooting tips for commonly encountered problems with the Microsoft Entra ID setup.

A modernized application that was produced by AWS Blu Age mainframe modernization refactoring tools. This pattern uses CardDemo as a sample open source mainframe application.

The AWS Blu Age OAuth extension library, which is provided by the AWS Blu Age team during your engagement with AWS Professional Services.

An active AWS account to deploy and test the modernized application.

Familiarity with AWS Blu Age configuration files and Microsoft Entra ID fundamentals.

This pattern covers OAuth 2.0 authentication and basic token-based authorization flows. Advanced authorization scenarios and fine-grained access control mechanisms are not in scope.

Some AWS services aren’t available in all AWS Regions. For Region availability, see AWS services by Region. For specific endpoints, see Service endpoints and quotas, and choose the link for the service.

AWS Blu Age Runtime version 4.1.0 (the pattern also works with later versions that are backward compatible)

MSAL library version 3.0.23

Java Development Kit (JDK) version 17

Angular version 16.1

Microsoft Entra ID

Modernized Java Spring Boot-based backend

AWS Blu Age Runtime

Spring Security with OAuth 2.0

Angular single-page application (SPA)

AWS Mainframe Modernization provides tools and resources to help you plan and implement migration and modernization from mainframes to AWS managed runtime environments. You can use this service’s refactoring features, which are provided by AWS Blu Age, to convert and modernize your legacy mainframe applications.

AWS configuration security. Move sensitive configuration values from application-main.yml to AWS Secrets Manager. For example, configure the following properties by using Secrets Manager:

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

For more information about how you can use Secrets Manager to configure AWS Blu Age parameters, see AWS Blu Age Runtime secrets in the AWS Mainframe Modernization documentation.

Runtime environment protection. Configure the modernized application environment with proper AWS security controls:

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

Amazon CloudWatch logging. Consider adding the file 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>

For information about enabling tracing with CloudWatch, see Enable trace to log correlation in the CloudWatch documentation.

Token configuration and handling. Configure token lifetimes in Microsoft Entra ID to align with your security requirements. Set access tokens to expire within 1 hour and refresh tokens to expire within 24 hours. In the AWS Blu Age Runtime configuration (application-main.yml), make sure that JWT validation is configured properly with the exact issuer URI and audience values from your Entra ID application registration.

When a token expires and is refreshed:

For more information about the AWS Blu Age Runtime components and their updates, see AWS Blu Age release notes.

AWS Blu Age Runtime security. The oauth2-ext library provided by AWS Blu Age must be placed in the correct shared directory location ({app-server-home}/shared/) with proper file permissions. Verify that the library successfully extracts user information from JWTs by checking the SharedContext object population in your logs.

Specific claims configuration. In application-main.yml, define the claims that you need from Microsoft Entra ID explicitly. For example, to capture the user's email and roles, specify:

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

Error handling. Add error handling to address authentication failures in your Angular application; for example:

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

Session timeout configuration. Configure session timeout settings in both the AWS Blu Age Runtime and Microsoft Entra ID. For example, add the following code to your application-main.yml file:

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

MsalGuard. You must implement the MsalGuard feature for all protected routes to prevent unauthorized access. For example:

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

Routes that don’t have MsalGuard protection will be accessible without authentication, potentially exposing sensitive functionality. Make sure that all routes that require authentication include the guards in their configuration.

For information about refactoring your application by using AWS Blu Age, see the AWS Mainframe Modernization documentation.

To understand how OAuth 2.0 works, see the OAuth 2.0 website.

For an overview of the Microsoft Authentication Library (MSAL), see the Microsoft Entra documentation.

For information about user profiles on an AS/400 system, see the IBM i (AS400) tutorial.

For the OAuth 2.0 and OpenID Connect (OIDC) authentication flow in the Microsoft identity platform, see the Microsoft Entra documentation.