Appendix D - Secretariat Application Reference Manual.pdf

Commonwealth of Massachusetts Executive Office of Health and Human Services

Chief Technology Office

EOHHS

Secretariat Application Reference Manual Version 4.0.0

Revision Date: April 30th, 2025.

Massachusetts EOHHS

Copyright 2025 by Massachusetts EOHHS, All Rights Reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without the written permission of the Massachusetts EOHHS. Products or corporate names may be trademarks or registered trademarks of other companies and are used only for the explanation and to the owner’s benefit, without intent to infringe.

Revision History

Revision Date Description

3.7 6-June-2022 Added Section 2.9 on Micro Services

3.8 5 May-2023 Added Section 2.10 on Low code/No Code

3.8.1 8 Dec-2023 Added sections 5.1 - 5.1.2 on Falcon Messaging, and sections

3.12 – 3.12.2 Vulnerability Scanning with Tenable and Veracode.

3.8.2 7-May-2024 Added new content for Informatica, Tableau, Snowflake and Dynatrace

3.8.3 21-Nov-2024 Updates to Accessibility, Vulnerability and Performance testing

4.0 31-March-2025

Additional Updates to most sections: Architecture, Technology, Enterprise Services, Development, Testing, Environment, Configuration Management, Cloud Best Practices and Appendix sections.

Remove outdated links. Updated VG4 references to VG5.

Table of Contents 1 Introduction

1.1 Business Objectives

1.1 Information Technology Objectives

1.2 How this document is organized

1.3 Intended Audience

2 Architecture

2.1 Layered Architecture Pattern

2.2 Microservices Architecture Pattern

2.3 Event Driven Architecture (EDA)

2.4 Best Practices

2.5 Key Components

2.6 Serverless Architecture

2.7 Service-Oriented Architecture (SOA)

2.8 Conclusion

3 Security

3.1 Identity and Access Management (functions)

3.2 Authentication

3.3 Identity Federation

3.4 Data Masking

3.5 Auditing and Logging

3.6 Application Intrusion Prevention

3.7 Security of Data at Rest and in Transit

3.8 Web Services Security

3.9 REST API Security

3.10 Technology Standards

3.11 Federal Security Standards

3.12 Vulnerability Scanning

4 Technology

4.1 Presentation Tier

4.2 Services Tier

4.3 Workflow Engine

4.4 Job Schedulers

4.5 Database Tier

4.6 Reports

5 Enterprise Services

5.1 Messaging System (Falcon)

5.2 Access and Identity Management Services (AIMS)

5.3 Enterprise Document Management (EDM)

5.4 Member Locator Service (MLS)

5.5 Massachusetts Health Information Exchange (HIE)

5.6 XML Gateway

5.7 Application Monitoring

5.8 Geographical Information Services (GIS)

5.9 Quality Assurance Services

5.10 Backup and Recovery

6 Application Development Methodology

6.1 New Project Request

7 Requirements Management

8 Development

8.1 Integrated Development Environment

8.2 XML Editor

8.3 Build Tools

8.4 Unit Testing Tools

8.5 Integration Testing

8.6 Code Quality

9 Testing

9.1 Functional Testing

9.2 Regression Testing

9.3 Accessibility Testing

9.4 Database

9.5 Web Services

9.6 Performance Testing

9.7 Vulnerability Testing

9.8 Defect Tracking

9.9 Performance Monitoring

9.10 Browser compatibility

10 Environment

10.1 Application Categories

10.2 Application Environments

10.3 Virtual Gateway

10.4 Virtual Data Center – VG5 AWS Cloud Environment

11 Release Management

11.1 Business Value

11.2 Service Offerings

12 Configuration Management

12.1 Key Purposes of Configuration Management

12.2 Source Control Tool

12.3 Continuous Integration (CI)

13 Change/Risk/Issue Management

14 Cloud Best Practices

14.1 Cloud Design Principles

14.2 Security

15 Appendix C - Data Dictionary

16 Appendix D - Logical Data Modeling

17 Appendix E – Physical Database Design

18 Appendix F – Data Administration

18.1 Attribute Data Content, Type, and Size

18.2 Miscellaneous Issues with Data Types, Lengths, and Formats

18.3 Additional best practices

19 Appendix G – Cloud SLA

19.1 AWS SLA

19.2 AZURE SLA

20 Appendix H – EOHHS WS Security Service Policy

1 Introduction

Information Technology (IT) strategic key initiatives mandate an infrastructure based on Cloud Computing, Service Oriented Architecture (SOA) model, and consolidation of IT services at 3 organizational levels: Commonwealth, Secretariat, and Agency. It is to be a flexible infrastructure providing the foundation to fulfill the objectives listed in following sections of this document. By allowing the agencies to follow architectural/technology standards defined in this document and reuse enterprise shared resources/services within EOHHS, it promotes effective delivery of the EOHHS applications and eliminates incompatibility within the agencies.

Purpose

This document, the Secretariat Application Reference Manual (SARM) provides guidance on the standards, technologies, and tools to be utilized at the secretariat level during application development and maintenance for the Executive Office of Health and Human Services (EOHHS).

It also provides guidelines for application architecture to ensure that individual projects conform to the overall architectural vision for EOHHS and is based on a blueprint for standard, open, reusable, and service-oriented services. This document is intended to be used across the enterprise within EOHHS to ensure that every initiative across the enterprise achieves consistently high quality.

Executive Office of Technology Services and Security (EOTSS) has established the policies, standards, and guidelines, collectively known as “policies”, that all organizations are expected to adhere to within the Commonwealth. This SARM document supplements EOTSS policies, standards, and guidelines, expanding and providing more details as necessary. If your business requirements cannot be met by the technologies and policies listed in this document, then the EOHHS Chief Technology Office should be consulted prior to a project architecture review.

EOTSS policies, standards, and guidelines can be found at:

EOTSS policies, standards, and guidelines

The SARM should also serve as a guide for procuring tools to be used for EOHHS IT projects.

1.1 Business Objectives

It is critical that the Information Systems (IS) organization provides all EOHHS sponsors / users with the ability to:

• Access business information faster, more economically, more securely, and more easily

• Respond to changing business and legislative environment

• Accommodate organizational restructuring

• Accommodate business growth and expansion

• Rapidly expose business services to interested parties

• Control the cost of business processes and IS development

• Accommodate existing information technology assets (legacy systems)

• Allow for cost-effective retirement of outdated systems

• Maintain quality and accuracy of information https://www.mass.gov/eotss-policies-standards-and-guidelines https://www.mass.gov/eotss-policies-standards-and-guidelines

1.1 Information Technology Objectives

In addition to always keeping the business objectives in focus, the following information technology objectives also need to be addressed:

• Consolidate development tools and technologies

• Improve reliability, modularity, extensibility, scalability and stability of existing and new systems

• Establish technical guidance by promoting best practices and standards

• Exploit new network computing architectures, particularly those based on Web Services standards so that future evolution of the architecture is supported

• Use packaged applications (COTS) where appropriate

• Replace obsolete and outdated technologies

• Provide integration mechanisms for non-conformant legacy systems

• Provide a repository of reusable software components that can be leveraged in projects within EOHHS

• Provide integration mechanisms for existing systems to promote the concept of service-oriented architecture

• Provide security requirements to protect the EOHHS infrastructure from unauthorized access

• Provide solutions that are based on open-standards and vendor independent implementations of those standards and specifications

• Use Open-Source Software where appropriate

• Establish a process for defining standards

• Adhere to EOTSS policies, standards, and guidelines

1.2 How this document is organized

This document consists of the following sections:

Architecture – the architectural design principles and guidelines for all phases of application development by EOHHS agencies

Security – the guidelines for the Implementation and Deployment phases of the applications developed by the agencies and their vendors.

Technology – the guidelines for the Implementation and Deployment phases of the applications developed by the agencies

Enterprise Services – the shared and standard services available at the secretariat level that shall be leveraged by the business services and applications developed by the agencies

Project Management – the methodology and collaboration tools for supporting the project management activities across the enterprise

Requirement Management – the methodology and collaboration tools for supporting requirements management across the enterprise

Development – the processes, best practices, and tools to be used during the development phase of applications

Testing – the types of tests to be executed and available tools for testing to ensure the quality of the applications during the testing phase of application development/maintenance

Environment – the information for categorizing the applications and choosing the correct environments for the application

Release Management – the guidelines for managing software releases

Configuration Management – the software configuration management process to be followed and the available tools for supporting the process

Change/Risk/Issue Management – the guidelines for managing project risks, change requests, and related issues.

1.3 Intended Audience

This document is intended for the following audience:

• Business and IT leaders, who need to start and manage business/IT strategy across the enterprise

• Enterprise Architects, who need to define standards, processes, design patterns and identify new technology, and ensure implementation compliance.

• Project Team Members, who need to map dependencies and develop a timeline that meets the business expectations

• Vendors that provide solutions in compliance with the standards defined in this document.

• Standards and Legal Teams, which need to review and understand how the applications leverage technology and standards to meet their objectives.

• Procurement Team that procures the IT tools and technologies.

2 Architecture

• This section provides an overview of the recommended architecture patterns and solutions that teams should consider when designing and implementing enterprise systems. The goal is to ensure consistency, scalability, and maintainability across the organization’s technology landscape. The patterns and solutions described here are aligned with industry’s best practices and tailored to address common use cases encountered within our organization.

2.1 Layered Architecture Pattern

2.1.1 Overview

The Layered Architecture pattern structures applications into a set of distinct layers, where each layer has a specific responsibility. This pattern follows a key concept known as layers of isolation where changes made in one layer of the architecture generally don't. Typically, these layers include:

• Presentation Layer: Handles user interface and user experience.

• Business Logic Layer: Contains the core functionality and business rules of the application.

• Data Access Layer: Manages data interaction with databases or external systems.

• Service Layer(optional): Exposes business logic via APIs or services, enabling integration with other systems.

• Persistence Layer: Handles storage systems like databases

2.1.2 When to Use

• When building web applications, enterprise applications, or mobile apps that require clear separation of concerns.

• Ideal for systems that need to be scaled in terms of functionality, as each layer can be modified or extended independently.

• When developing applications that need to interact with various types of data sources or third-party services

2.1.3 Key Benefits

Separation of Concerns:

Each layer is responsible for specific tasks (e.g., UI, business logic, data access), which reduces complexity and makes it easier to maintain and extend the system. Changes to one layer usually don’t affect others.

Improved Maintainability:

With clear boundaries between layers, it becomes easier to update or modify specific parts of the application. For instance, you can update the business logic layer without impacting the presentation layer.

Testability:

Each layer can be tested independently. Since the layers are modular, you can perform unit testing, integration testing, and end-to-end testing more effectively.

Reusability:

Components and code within a given layer can be reused across different applications or services.

For instance, business logic and data access layers can be reused in other projects or modules.

Scalability:

Layers can be independently scaled, allowing the system to handle increased load at specific levels (e.g., scaling the data access layer or business logic layer separately).

Flexibility for Future Changes:

Clear separation allows for easy adaptation to changes, such as replacing the UI with a new frontend technology or switching databases without affecting other parts of the system.

2.1.4 Best Practices

Clear Layer Boundaries:

Ensure that each layer has a well-defined responsibility. For example, the presentation layer should handle user interface logic and not contain any business logic or data access logic.

Limit Dependencies Between Layers:

Keep layers loosely coupled. Ideally, higher layers (such as the presentation layer) should only depend on lower layers (such as the business logic layer) and not directly interact with other higher layers.

Use Interfaces for Communication:

To ensure layers can be easily replaced or updated, use interfaces or abstraction layers between them. For instance, the presentation layer should communicate with the business logic layer via defined interfaces, not directly with its implementation.

Avoid Layer Spaghetti:

Layers should not directly call each other in a circular manner. For example, the presentation layer should not directly access the data layer. Each layer should interact only with the one directly below it (or in the case of service layers, via APIs).

Minimize Business Logic in the UI:

The UI layer should be focused on presenting information to the user, not performing business logic or manipulating data. Keep business rules and data handling within the business logic and data access layers.

Modularize Layers Where Appropriate:

In complex systems, break down each layer into smaller, more manageable sub-modules. For example, the data access layer can be further divided into data access and data service modules.

Test Each Layer Independently:

Ensure that each layer is tested in isolation, using mock objects or stubs for dependencies. This helps identify issues more easily and ensures that each layer is functioning as expected.

Monitor and Optimize Performance:

Since the layered architecture can introduce some overhead due to the multiple layers of abstraction, it’s important to monitor system performance regularly and optimize critical areas.

2.1.5 Key Components of Layered Architecture

• Presentation Layer (UI Layer):

o Responsibility: Manages interaction with the user, handling input/output operations (like displaying data to the user or capturing user actions).

o Components:

Web interfaces (e.g., HTML, CSS, JavaScript)

Mobile app screens (e.g., Android, iOS views)

Desktop app windows

Controllers and view models (in some frameworks like MVC/MVVM)

• Business Logic Layer o Responsibility: Contains the core application functionality and rules. It processes data according to business rules, makes decisions, and performs calculations.

o Components:

Services (handling specific business processes)

Domain models (representing business entities)

Validation logic

Workflow management (if applicable)

Transaction handling

• Data Access Layer:

o Responsibility: Manages interactions with data sources such as databases, file systems, or external APIs. It provides data to the business logic layer and handles CRUD (Create, Read, Update, Delete) operations.

o Components:

Data repositories or DAOs (Data Access Objects)

Database connection management

ORM (Object-Relational Mapping) frameworks (e.g., Hibernate, Entity Framework)

Queries and stored procedures (if necessary)

• Service Layer (Optional):

o Responsibility: Acts as an intermediary between the presentation layer and the business logic layer, especially for applications that need to expose functionality via APIs or external services.

o Components:

API endpoints (e.g., RESTful services)

Message brokers or queues (e.g., for asynchronous communication)

Data transformation and validation

Aggregation of multiple business services

• Persistence Layer (Sometimes considered part of DAL):

o Responsibility: Handles the management of the system’s persistent storage

(databases, files, or cloud storage).

o Components:

Storage providers (e.g., SQL, NoSQL, file systems)

Data caching (e.g., Redis, Memcached)

2.2 Microservices Architecture Pattern

2.2.1 Overview

The Microservices Architecture pattern breaks down an application into smaller, loosely coupled, independently deployable services. Each service corresponds to a specific business function and communicates with other services via APIs, typically using REST or message queues.

2.2.2 When to Use

• When developing large-scale, complex systems that need to scale independently.

• When teams require autonomy in deploying, updating, and maintaining individual components.

• If the organization has or plans to use containerization (e.g., Docker) and orchestration tools (e.g., Kubernetes).

• When the business needs to support frequent changes or releases in specific parts of the application without affecting the whole system.

2.2.3 Key Benefits

Scalability: Individual services can be scaled up or down independently as needed, and new components can be added without requiring downtime and disruption to the entire application.

Services can also be deployed in multiple servers which reduces the performance impact of more demanding components.

Easier to build and maintain: Components can be built and maintained by smaller teams. Each team can be cross-functional. Each microservice can be deployed independently.

Fault isolation: It is easier to identify and isolate the problem in a microservices architecture compared to a monolith.

Faster time-to-market: Microservices help enable an agile approach that can result in faster iterations and quicker releases.

Higher-quality code: Modularizing an overall solution into discrete components helps application development teams focus on one small part at a time. This simplifies the overall coding and testing process.

2.2.4 Best Practices

2.2.4.1 Single-responsibility principle:

Each microservice should be responsible for a single piece of functionality or a specific domain within the applications. The single responsibility principle helps development teams ship code faster by ensuring developers can work independently within their area of expertise.

2.2.4.2 Separate Data Stores

Ideally, multiple microservices should not share a single monolithic database. If they were, a downtime to that database would impact all dependent microservices. This isolation means that each service can evolve independently, without being tied to a shared database schema. Choose the right database for your microservice needs, better customize the infrastructure and storage to the data that it maintains, and let it be exclusive to this microservice. Ideally, any other microservice that’s accessing that data would only access it through the APIs via microservice exposure.

2.2.4.3 Fail Fast by Using a Circuit Breaker to Achieve Fault Tolerance Services often collaborate when processing requests. When one service synchronously calls another, there is always a risk that the second service might be unavailable or experiencing such high latency that it becomes practically unusable. Valuable resources, like threads, may be consumed by the caller while waiting for a response from the other service. This can lead to resource exhaustion, preventing the calling service from handling additional requests. A failure in one service has the potential to trigger a cascade of issues across other services in the application. A service client should interact with a remote service through an API gateway, which acts like an electrical circuit breaker. When consecutive failures exceed a predefined threshold, the circuit breaker trips, causing the API gateway to immediately reject all attempts to invoke the remote service for the duration of a timeout period. Once the timeout expires, the gateway allows a limited number of test requests to pass through. If these requests are successful, the gateway restores normal operation. However, if any of the test requests fail, the timeout period is reset, and the circuit breaker remains in effect. This is better than using the HTTP CONNECT_TIMEOUT and READ_TIMEOUT settings as it does not spin up additional threads beyond what’s been configured.

2.2.4.4 Loose Coupling via Asynchronous Communication

If a real-time response is not required, consider using asynchronous communication between microservices to avoid building a mesh of tightly coupled components. Integration patterns based on events and asynchronous messaging provide maximum scalability and resiliency. Make calls to your dependencies asynchronously. A microservice publishes an event to a message bus to signal either a state change or a failure. Relevant components or microservices within the system can subscribe to specific event types or topics, receiving notifications when these events occur and then processing them accordingly.

2.2.4.5 Proxy your requests via API Gateway

It is not optimal for every microservice to perform the functions like API authentication, request / response logging, and throttling, having an API gateway upfront doing these for you will add good value. Clients call API Gateway instead of your service directly to avoid making all those additional calls from your microservice and the internal URLs of your service would be concealed, giving you the flexibility to redirect the traffic to a newer version of your service from the API Gateway itself. This will even help you throttle the incoming traffic when a third party is accessing your service, as you can and reject unauthorized requests from the API gateway before they reach your microservice. You can also choose to have a separate API gateway that takes traffic from external networks.

2.2.4.6 Versioning

Microservices versioning helps manage changes to an API over time, allowing multiple versions of the API to coexist and be used at the same time. This is essential for maintaining compatibility with different clients that may depend on various versions of the API.

2.2.4.7 Separate Release Train

Within the organization, it is better to use separate release cycles and process for separate services which are not tied to other components. When different teams work on different services, trying to synchronize releases can be time-consuming and complicated. Separate release cycles enable faster deployment of individual services

2.2.5 Key Components

Below are some key components which enable any development teams to implement microservices with ease.

• Microservices Independent, self-contained services that focus on a specific business capability or functionality.

Each microservice is responsible for a single domain, and it can be developed, deployed, and scaled independently.

• API Gateway Acts as an entry point for clients to interact with the microservices. The API Gateway routes requests to the appropriate microservice, handles authentication, rate limiting, and other cross-cutting concerns like logging and monitoring.

• Service Registry and Discovery A central directory where microservices register when they start up. This registry helps other services discover and interact with them dynamically, which is crucial in a dynamic, distributed environment where services might change locations or scale up/down frequently.

• Container Registry A container registry is a repository for storing, managing, and distributing container images.

These images contain all the necessary components (code, libraries, configurations, dependencies) needed to run a containerized application or service.

• CI/CD (Continuous Integration/Continuous Delivery) Continuous Integration (CI) and Continuous Delivery and Deployment (CD) are essential practices in modern software development that streamline the process of building, testing, and deploying code

• Configuration Management A central system (e.g., Consul) to store configuration settings for microservices. This allows dynamic updates to configurations without requiring redeployment

• Containerization and Orchestration:

Microservices are often packaged in containers (e.g., Docker), allowing them to run consistently across different environments. Orchestrators like Kubernetes are used to manage the deployment, scaling, and operation of these containers in production.

2.3 Event Driven Architecture (EDA)

2.3.1 Overview

In Event-Driven Architecture, components communicate through events. This enables loose coupling of applications by introducing a middleman known as an event broker. This means that applications and devices do not need to know where they are sending information or where the information they are consuming comes from.

2.3.2 When to Use

• When you need to react to events in real time, such as handling live data streams or responding to user actions.

• When your system needs to handle a large number of events concurrently and scale dynamically.

• When one change in a system should trigger a chain of actions across multiple components. Event-driven architecture makes it easy to set up these triggers and ensure that actions are taken when specific events occur.

2.3.3 Key Benefits

Loose Coupling:

Components (producers and consumers) are decoupled because the consumer doesn’t need to know where the event originated. This leads to better flexibility and easier maintenance.

Scalability:

EDA allows independent scaling of producers and consumers. Since events are processed asynchronously, consumers can scale out based on the volume of events they need to handle without affecting the event producers.

Asynchronous Communication:

EDA promotes non-blocking operations, where the producer of an event doesn't wait for a response. This leads to high responsiveness and the ability to handle large volumes of events simultaneously.

Real-time Processing:

EDA is ideal for real-time or near real-time systems where changes in the system’s state need to trigger actions instantly.

Improved Fault Tolerance:

Because consumers are independent, a failure in one component doesn’t necessarily bring down the entire system. Systems can be designed to retry or reroute failed events, ensuring robustness.

Flexibility and Extensibility:

New consumers can be added to listen for and react to events without altering the existing producers or other consumers. This promotes system extensibility and agility in response to changing requirements.

Auditability and Traceability:

Events can be stored in event logs, creating an audit trail. This can be useful for debugging, analyzing system behavior, or providing historical data insights.

2.4 Best Practices

Define Clear Event Contracts:

Establish a well-defined schema for events to ensure consistency across producers and consumers. This will minimize errors and simplify integration between different parts of the system.

Event Granularity:

Ensure events are meaningful but not too granular (to avoid overloading the system with excessive events). For example, instead of sending every single data change as an event, aggregate or batch related events together to reduce noise.

Idempotency:

Design consumers to be idempotent, meaning that processing the same event multiple times won’t cause unintended side effects. This is important for ensuring reliability and consistency when events are retried or delivered multiple times.

Event Replayability:

Store events in an event store so that they can be replayed if necessary. This is useful for recovering from failures or reprocessing events in the event of system upgrades or migrations.

Event Filtering and Routing:

Use event routers or filters to ensure that consumers only receive the events they need. For example, different consumers may subscribe to different types of events, and an event bus should ensure proper routing of events to the right consumers.

Event Durability:

Store events in durable, fault-tolerant systems (e.g., message queues with persistence) to ensure they are not lost in case of failures. This ensures that events can be reprocessed or forwarded even after outages.

Monitor and Trace Events:

Implement monitoring and tracing to track the flow of events through the system. This helps in identifying bottlenecks, measuring performance, and debugging issues.

Handle Eventual Consistency:

Understand that EDA promotes eventual consistency, where data may be temporarily inconsistent between different parts of the system as events propagate. Ensure that consumers are built to handle this model of consistency.

Event Versioning:

Events may evolve over time, so it's important to support versioning in events to ensure backward compatibility. For example, consumers should be able to process old versions of events even when new ones are introduced.

2.5 Key Components

Event Producer:

Responsibility: Emits events when something happens in the system (e.g., a user action, data change, or external trigger).

Event Consumer:

Responsibility: Listens to and processes events emitted by producers. Consumers can perform actions in response to these events, such as updating databases, invoking workflows, or notifying users.

Event Channel (Message Broker/Event Bus):

Responsibility: Acts as an intermediary that routes events from producers to consumers. This decouples the producers and consumers, allowing them to operate independently (e.g., Kafka, ActiveMQ, SQS).

Event Store:

Responsibility: A durable store for events, allowing them to be stored, retrieved, or replayed later for auditing, debugging, or system recovery (e.g., EventStoreDB).

Event Router:

Responsibility: Routes events to the appropriate consumers, sometimes based on event type, metadata, or other routing criteria.

Event Processing Engine (optional):

Responsibility: Handles complex event processing, such as aggregating multiple events, filtering, and performing real-time analytics (e.g., Kafka streams)

2.6 Serverless Architecture

2.6.1 Overview

Serverless Architecture abstracts away the infrastructure, allowing developers to focus purely on writing functions. The underlying infrastructure, scaling, and resource management are handled by a cloud provider (e.g., AWS Lambda).

2.6.2 When to Use:

• When you have unpredictable or intermittent workloads that need to scale automatically.

• For small, discrete tasks that don’t require constant server maintenance.

• When the development team wants to minimize operational overhead and focus purely on business logic.

2.6.3 Key Benefits:

No need to manage infrastructure or scale servers.

Reduces operational complexity and costs, as resources are allocated dynamically based on demand.

Allows developers to quickly deploy and iterate on applications without worrying about infrastructure concerns.

2.7 Service-Oriented Architecture (SOA)

2.7.1 Overview:

Service-Oriented Architecture is an approach in which services are provided to other components or applications through a communication protocol. Services are self-contained, loosely coupled, and reusable.

2.7.2 When to Use:

• When building systems that need to integrate multiple applications or services across the enterprise.

• When there is a need to share business functions across diverse platforms or technologies.

• For large, distributed systems that require well-defined interfaces between different parts of the system.

2.7.3 Key Benefits

Promotes reuse of common services across applications.

Enhances system interoperability by using common communication protocols (e.g., SOAP, REST).

Scalable and maintainable by decoupling service logic from the user interface or client applications.

2.8 Conclusion

Selecting the right architecture pattern is crucial for the success of any enterprise system. The recommended patterns and solutions above provide different approaches for addressing specific technical and business requirements. Teams should consider the scale, complexity, maintainability, and business needs of their applications when choosing the appropriate pattern.

By adopting the right architecture, we ensure that our systems are scalable, maintainable, and capable of evolving in alignment with business goals.

3 Security

Care must be taken to safeguard confidential and/or sensitive information that includes Personally Identifiable Information (PII) and Protected Health Information (PHI). Social security numbers, federal tax return information and medical records are some of such confidential or restricted personal information. EOHHS applications must ensure that confidential data are always protected. While access to data, applications, and environments is limited to authorized users only, EOHHS applications must also monitor and prevent unauthorized access. This section specifies some Security guidelines that should be applied to all the EOHHS applications.

3.1 Identity and Access Management (functions)

• Identity Management (IDP) - User identity information should be managed in a centralized enterprise-wide repository for accessing by service applications (SPs) within

EOHHS.

• Users Provisioning - User Provisioning system should be established and used for security administration and help desk efficiency, for role-based access control (RBAC)access to applications, and for single sign-on and audit capabilities.

• User Authentication - Users should be reliably identified at the point of access to the network and authenticated against Enterprise User Repository.

• Single-Sign-On (SSO) - Servers participating in a transaction, or use case need to validate every access request. This does not mean that the servers should force the user of the request to login multiple times. It should be achieved using Single-Sign-on.

• Credentials Encryption - User passwords should not be transmitted in clear text in transit or at rest and should not be stored anywhere outside the security system itself.

• Access Control Information - Levels of access should be predefined and granting of the appropriate access level to specific users should be done for specific sets of information within an application. The application security should be separate from the network security, which doesn’t provide fine-grained authorization.

• Security Improvement by separating concerns – Application security logic should be separated from the business logic to ensure that future change in business logic doesn’t affect the security logic.

Public Users

Internet

Interceptor

Protected Applications

User Repository

Identity Management

Provisioning Service

Intranet

Help Desk

Create Identify Access Request

Update Identity

Audit Log Audit Log

Verify SSO Tocken

Login

Redirect

Login and

Create SSO Token

The diagram above illustrates the recommended approach to implement application security in the EOHHS environment.

Authentication To prevent or minimize unauthorized access to applications, the following guidelines are suggested:

• EOHHS application’s first level of defense should be Authentication.

• Username and password-based user credential is the form of authentication recommended.

• Define and enforce rules for strong username/password, password expiration, and account lock-out

• Provide functionality to provision the user to the system

• Store the user credentials securely (encrypted)

• Implement secure login page for users to login prior to accessing the application

• Provide functionality to validate the user’s identity.

• Implement self-password reset functionality

• Logins, logouts, failed login attempts, and password reset requests should be logged.

Authorization and access control

• Role based authorization using a least privilege model is recommended

• Prevent attempted unauthorized accesses

• Ensure that data is not cached when the user handles sensitive data

• Coarse grained access to the application login page is to be implemented outside of the application

• Fine grained access to the page fields is to be implemented inside the application

In the EOHHS environment, based on the Separation of Concern (SoC) design principle, the Application Security implementation has been separated from the core application implementation. This separated EOHHS Application Security implementation is AIMS, which is an enterprise shared service for Identity and Access Management for EOHHS applications. The EOHHS Architecture team recommends that Application development teams use AIMS to address their security needs listed above. For exceptions, the EOHHS Enterprise Architecture team must be consulted.

3.2 Authentication

All applications must be integrated with the commonwealth enterprise solution for security called Access and Identity Management Services (AIMS). AIMS provides single sign-on (SSO) capabilities, high level authorization and auditing at an enterprise level. Furthermore, AIMS provides a web service/API. AIMS is based on the Oracle Identity and Access Management solution.

Enterprise Authorization

The applications must use the Access Manager Agent to provide high level authorization into the application. The agent will enforce authorization to the application. Only users that are allowed to access a given application will be allowed into it. This level of authorization is provided via AIMS.

Application Authorization

Determining what a user can do once they have access to the application is the responsibility of application-level authorization. The application must provide its own authorization for such control.

3.3 Identity Federation

This section provides detailed guidelines, threats & mitigate approaches for Identity federation.

The guidelines are generic for any identity federation protocols and covers requirements for both Identity Provider (IdP) and Service Provider (SP) / Relying Party (RP). Some of the guidelines provided in this section are taken from NIST SP 800-63C version 2.

Federation

Federation is a process that allows for the conveyance of authentication and subscriber/user attribute information across networked systems. In a federation protocol, a three-party relationship is formed between the subscriber, the IdP (Identity Provider), and the RP (Relying Party) or SP (Service provider). Federated identity systems use assertions to accomplish this task. Assertions are statements from an IdP to a SP that contain information about a subscriber.

The SP uses the information in the assertion to identify the subscriber and make authorization decisions about their access to resources controlled by the SP. Federation Protocol defines a mechanism for an IdP to generate the Assertion.

Assertions contain a variety of information, including assertion metadata, attribute values and attribute references about the subscriber, and other information that the SP can leverage (such as restrictions and expiration time). While the assertion’s primary function is to authenticate the user to an SP, the information conveyed in the assertion can be used by the RP for several use cases — for example, authorization or personalization of a website.

3.3.1 Federation Protocols and Assertions

There are two protocols used in general and recommended by EOHHS for federation, SAML (Simple Assertion Markup Language) and OpenID Connect. Depending on the platform capabilities of IdP and SP, either one of the protocols may be selected. Based on the protocol selected, different information passes between the participants at different times.

However, all assertions SHALL include the following assertion metadata:

1. Subject: An identifier for the party that the assertion is about (i.e., the subscriber).

2. Issuer: An identifier for the IdP that issued the assertion.

3. Audience: An identifier for the party intended to consume the assertion (i.e., the

RP).

4. Issuance: A timestamp indicating when the IdP issued the assertion.

5. Expiration: A timestamp indicating when the assertion expires and SHALL no longer be accepted as valid by the RP (i.e., the expiration of the assertion and not the expiration of the session at the RP).

6. Identifier: A unique value identifying this assertion, used to prevent attackers from replaying prior assertions.

7. Signature: Digital signature or message authentication code (MAC), including key identifier or public key associated with the IdP, for the entire assertion.

8. Authentication Time: A timestamp indicating when the IdP last verified the presence of the subscriber at the IdP through a primary authentication event (if available).

Assertions MAY also include the following information:

1. Key binding: Public key or key identifier of subscriber-held key to demonstrate their binding with the assertion

2. Attribute values and attribute references: Information about the subscriber.

3. Attribute metadata: Additional information about one or more subscriber Attributes.

3.3.2 Single-Sign-On and Session management in Federation:

In a federated environment, the SP manages its sessions separately from any sessions at the IdP.

The session at the SP starts when the SP processes the federation protocol from the IdP. At the time of a federated login, the subscriber MAY have an existing session at the IdP which MAY be used as part of the authentication process to the SP, this provides Single-Sign-On to subscriber.

3.3.3 When to go for federation

Federation technology is used when the RP (Replying Party) / SP (Service Provider) and the IdP (Identity Provider) are not a single entity or are not under common administration and need a SSO (Single Sign On) across IdP administration applications and RPs.

In EOHHS, Identity federation shall be considered under following scenarios.:

1. SP’s Application(s) hosted in a separate data center from IdP.

2. SP’s system architecture does not fit with IdP’s agents / plugins requirements to enforce Authentication, Authorization and Single Sign On (SSO) policies.

3. Integration with SaaS solutions.

4. Customization restriction on COTS products to comply with IdP’s agents / plugins requirements to do Authentication, Authorization and SSO.

3.3.4 Federation Guidelines

Sl.No Responsibility Category Federation Guidelines

1 IdP Registration All SPs must be whitelisted that is registered or configured in IdP. This should identify all SPs by their domain or specific unique identifier, depending on the federation protocol in use.

Note: Whitelist is more secured approach compared to blacklist of certain SPs in the IdP.

2 IdP, SP Registration Dynamic registration of SP at IdP SHOULD be avoided.

Credibility of SP and IdP SHOULD be reviewed and verified upfront.

If dynamic registration is required for any scenarios, then a review and approval with EOHHS Security and Architecture team is required before proceeding with the design.

3 IdP, SP Registration Federation Protocols requiring the transfer of digital key information SHALL use a secure method during the registration process to exchange digital keys that needed to operate the federated relationship, including any shared secrets or public keys.

4 IdP Assertion Generation

Assertions SHALL be sufficiently unique to permit unique identification by the target Resource Provider (RP) or Service Provider (SP). Assertions MAY accomplish this by use of an embedded nonce, issuance timestamp, assertion identifier, or a combination of these or other techniques.

5 SP Federation Session

Due to the distributed nature of a federated system, the subscriber is capable of terminating sessions with the IdP and SP independently of one another. The SP SHALL NOT assume that the subscriber has an active session at the IdP past the establishment of the federated log in. The IdP SHALL NOT assume that termination of the subscriber’s session at the IdP will propagate to any sessions that subscriber would have at downstream SPs.

6 IdP, SP Federation Session and Security

Although details vary based on the exact federation protocol in use, an assertion SHOULD be used only to represent a single login event at the SP.

7 IdP Assertion Lifetime

Assertion lifetime SHOULD be less than or equal to 5 mins. The assertion’s lifetime is the time between its issuance and its expiration. This lifetime needs to be long enough to allow the SP to process the assertion and create a local application session for the subscriber but should not be longer than necessary for such establishment. Long-lived assertions have a greater risk of being stolen or replayed; a short assertion lifetime mitigates this risk.

8 IdP Assertion Security

Assertion SHOULD be signed with IdP (Identity Provider) private key to ensure message integrity.

9 IdP Assertion Security

When the Assertion is protected by a digital signature using an asymmetric key, the IdP MAY use the same public and private key pair to sign assertions to multiple SPs.

10 IdP Assertion Security

When the Assertion is protected by a digital signature using an IdP symmetric key then it SHOULD be independent for each SP.

11 IdP, SP Assertion Security

Federating with SaaS services or applications that are managed outside of EOHHS data center, IdP should encrypt assertion with SP public key. For example, a SAML assertion can be encrypted using XML- Encryption, or an OpenID Connect ID Token can be encrypted using JSON Web Encryption (JWE). For assertions that are passed directly between IdP and SP, the actual assertion MAY be encrypted.

Assertion encryption may not be required when federating with any EOHHS internally managed applications.

12 IdP Assertion Security

The digital certificates used by IdP for signing the assertion should follow EOHHS Policies for cipher suite algorithm, certification renewal, key rotation, etc., Please refer the SARM (Secretariat Application Reference Manual) for the corresponding guidelines.

13 SP Assertion Security

The digital certificates used and shared by SP SHOULD follow EOHHS Policies for cipher suite algorithm, certification renewal, key rotation, etc., Please refer the SARM (Secretariat Application Reference Manual) for the corresponding guidelines.

14 IdP, SP Assertion Security

Communications between IdP and the SP SHOULD be protected in transit using an authenticated protected channel.

Note: This type of communication is required for Back Channel federation, where SP connects to IdP with assertion identifier that is sent through the subscriber redirection to collect assertion details.

15 IdP, SP Assertion Security

Communications between the subscriber and either the IdP or the SP (usually through a browser) SHALL be made using an authenticated protected channel.

16 IdP, SP Subscriber Consent

Subscriber shall be involved in runtime decision before federating into Financial or Federal systems. When the subscriber is involved in a runtime decision, the subscriber SHALL receive explicit notice and be able to provide positive confirmation before any attributes about the subscriber are transmitted to any SP.

17 SP PII

protection

SPs SHOULD adhere to EOHHS requirements and legal procedures for handling subscriber attribute data, retention, aggregation, and disclosure to third parties.

18 IdP PII data protection

In addition to the protocol required attributes, The IdP SHALL transmit only those attributes that were explicitly requested by the SP

19 SP Vulnerability protection

The SP SHALL protect itself against injection of manufactured or captured assertion references by use of cross-site scripting protection or other accepted techniques.

3.3.5 Potential Federation Threats and Mitigation Strategies

Federation Threat/Attack

Description Example Federation Threat Mitigation Strategies

Assertion Manufacture or Modification

The attacker generates a false assertion

Compromised IdP asserts identity of a claimant who has not properly authenticated

Cryptographically sign the assertion at IdP and verify at

RP

Send assertion over an authenticated protected channel authenticating the IdP

Include a non-guessable random identifier in the assertion. Assertions MAY accomplish this by use of an embedded nonce, issuance timestamp, assertion identifier, or a combination of these or other techniques.

The attacker modifies an existing assertion

Compromised proxy that changes AAL of an authentication assertion

Assertion Disclosure

Assertion visible to third party

Network monitoring reveals subscriber address of record to an outside party

Send assertion over an authenticated protected channel authenticating the

RP.

Encrypt assertion for a specific RP (may be accomplished by use of a mutually authenticated protected channel)

Assertion Repudiation by the IdP

IdP later claims not to have signed transaction

User engages in fraudulent credit card transaction at RP, IdP claims not to have logged them in

Cryptographically sign the assertion at the IdP with a key that supports nonrepudiation;

verify signature at RP

Assertion Repudiation by the Subscriber

Subscriber claims not to have performed transaction

User agreement (e.g., contract) cannot be enforced

Issue holder-of-key assertions; proof of possession of presented key verifies subscriber’s participation

Assertion Redirect

Assertion can be used in unintended context

Compromised user agent passes assertion to attacker who uses it elsewhere

Include identity of the RP (“audience”) for which the assertion is issued in its signed content; RP verifies that they are intended recipient

Assertion Reuse

Assertion can be used more than once with same RP

Intercepted assertion used by attacker to authenticate their own session

Include an issuance timestamp with short validity period in the signed content of the assertion; RP verifies validity.

Assertion Substitution

Att…