Developed by Max Carlson, Kristo Vaher, Steve Conrad, Dr. P. S. Ramkumar, Wes Brown, Aare Laponin, Uwe Washer, and Trevor Kensey

It is vital that GovStack be able to connect to existing applications. Likewise, existing applications should be able to connect to and utilize GovStack resources as they see fit. This must be done without compromising the easy and secure interoperability provided by the GovStack system.

GovStack has defined a process for an existing product to become compliant with GovStack. This process is outlined in this document. Note that there are various levels of compliance that are defined. Any product owners or maintainers that are interested in the compliance process can use the GovStack testing platform to begin: https://testing.govstack.global

This section contains resources can be used by existing platforms to integrate into the GovStack ecosystem. The first section describes 'Adaptors' which can be used to translate an existing API into a GovStack-conformant API. The second section describes Native GovStack implementation. Finally we describe the GovStack Testing Harness which allows products to run automated tests that have been developed by the GovStack team to determine how closely an application conforms to the specifications and expected behaviors described by the Building Block specifications.

6.1 Adaptors

Adaptors are used to map existing APIs and functionality in a Digital Public Good into a format and scheme that is compatible with the GovStack API specifications.

Adaptors may transform data formats (ie. XML to json), may transform URLs/protocols, or may be used to map GovStack APIs and data structures into sector-specific standards (ie. FHIR patient records).

6.1.1 Key Components and Definitions

Adaptor: An adaptor provides both URL and payload mapping between an existing API developed by a DPG and the GovStack API definitions for the Building Block that the DPG provides functionality for.

Workflow: The workflow Building Block is used to manage more complex transactions where multiple Building Blocks must be called to complete a request (multi-part requests) or where retry/rollback/compensating transactions must be implemented.

Information Mediator: The Information Mediator is used transfer information securely between Building Blocks where communication occurs across the internet.

6.1.2 Adaptor Requirements

1. Adaptors should not be used for outbound requests.

   1. In general it is the application which manages interactions and requests from various Building Blocks

   2. In the event that a Building Block needs to make a direct request from another Building Block, it is recommended to use the Workflow Building Block to manage and URL and data mapping

2. Adaptors should always be tied to specific products. We will not have universal adaptors. Adaptors will be used to transform data based on specific APIs that have been defined by GovStack.

   1. Adaptor technologies may be re-used for different adaptors or we may have a paradigm where a generic adaptor can be configured via config files

3. Adaptors Perform 3 distinct functions (all synchronous):

   1. Class 1 - URL rewriting (mapping a GovStack URL to a URL from a native API)

   2. Class 2 - Payload mapping (transforming data payloads between GovStack and native formats)

   3. Class 3 - Synchronous 1:many calls and composition of responses into a single response

      Note: async and/or complex transactions would require the use of the Workflow Building Block

Please refer to this document for additional context/information and example scenarios for adaptors. \

6.2 Native GovStack Implementation

The highest level of integration involves existing products implementing APIs that can be directly consumed by other GovStack Building Blocks. This means that the application will provide APIs that are in alignment with the API specifications for the Building Blocks that they are supporting.

The following diagram shows a complete GovStack deployment with API gateways for citizen access via web or mobile and for existing applications to be able to call GovStack APIs on demand. The workflow building block is used as an adapter, exposing existing applications as GovStack resources via OpenAPI:

Here, citizens and existing applications are provided API access for requests into GovStack via a common API Gateway, while the workflow Building Block adapter provides outgoing API access to existing applications from GovStack Building Blocks.

6.3 GovStack Testing Harness

The GovStack team has created a testing platform that allows existing products to validate their APIs against the GovStack specifications. The testing platform consists of a set of tests (written in Gherkin) that can be run against one or more candidate products. These tests are run on a Continuous Integration (CI) platform and are executed automatically whenever changes are made to the GitHub repository for the Building Block.

The test platform will provide a detailed output of the test results, showing which tests are passing and failing for each candidate product.

The testing platform can be accessed at https://testing.govstack.global

6.3.1 Adding a new test to the Harness

New tests may be created for a Building Block. These tests are stored in the 'test' directory of the Building Block GitHub repository (GitHub repositories for the various Building Blocks can be found here). A new tests can be added by creating a .feature file in the features directory. All tests are written using Gherkin. Note that supporting code to run these tests should be stored in the 'support' folder under features.

New tests will automatically be run when a test cycle is started for a Building Block.

6.3.2 Adding a new product to the Test Harness

A new candidate product can be integrated into the test harness by adding a new folder to the 'examples' directory of the Building Block GitHub repository (GitHub repositories for the various Building Blocks can be found here).

The 'examples' folder provides configuration files that will launch the product in the test (CI) environment using docker and docker compose. Testing a new product requires the addition of a new Dockerfile (or set of Dockerfiles) that will build the product, and a docker-compose file and docker-entrypoint.sh file that will launch and configure the product in the test environment so that it is ready to receive the test requests.

For more detailed information on how to create new tests or integrate new products into the test harness, please refer to this document, which is geared toward developers and technical teams.

The following diagram provides an example of a GovStack implementation

This digram shows an example of what a GovStack implementation may look like in practice. Several concepts that are important to GovStack are shown in this diagram:

• A GovStack implementation may consist of multiple ‘applications’, each serving a distinct purpose. The value that GovStack provides is that these applications do not have to be developed from scratch, but rather leverage core functionalities that are provided by various Building Blocks. And these Building Blocks may be used in multiple applications.

• Applications may access outside services through the Information Mediator. Access to these services are configured within the Information Mediator per organization. One application may have permission to access data provided by a particular ministry that another application may not access.

• A GovStack application can be used by different types of users. The roles and permissions for various user groups must be managed by the application itself (using )

• Building Blocks may be based on existing applications or Digital Public Goods (DPGs). These DPGs may have an API that conforms with the GovStack API specification for that Building Block. If not, an can be used to map the existing API to the GovStack API

• The Application frontend and backend may use any mechanism to communicate (REST, GraphQL, etc). However, all GovStack API calls should be done using standard REST protocols.

3.1 GovStack Components

In a GovStack implementation, there are several different types of components. In addition, there are components that must be developed to support the testing and compliance process for a particular building block. This document provides a definition of these various components as well as detailing which components are generic (may be used for multiple use cases) and which are specific to a particular use case. This document will also flag any components that are specific to the GovStack sandbox/demonstration platform.

3.1.1 Use Case Dependent

• Application Frontend. For a particular use case, a user interface will be implemented to provide necessary information to the user and collect any needed information from the user.

• Application Backend. For a use case, the application backend will manage the flow and business logic needed. The backend will access any local data and make calls to GovStack Building Blocks as needed.

• Repositories. An application may have a local repository that contains data that is specific for that use case.

• BB Emulator. This component is applicable only to the GovStack sandbox/demonstration platform. In some cases, a simple/lightweight implementation of a Building Block has been created to provide the needed BB functionality for a particular use case. This reduces the infrastructure load for the sandbox.

3.1.2 Generic

These components may be adapted to a country specific context, but can be generic across multiple use cases in a particular GovStack implementation.

• BB candidate software. This is a specific software platform that functions as one or more building blocks in a GovStack implementation.

• Adapter. The adaptor provides a mapping from an existing software platform’s API to the format that is specified by the GovStack BB spec for a particular Building Block

• BB Configuration files. These are the Docker files and startup scripts that allow a product to be automatically launched and configured in a GovStack environment.

• Test Harness Scripts. These scripts configure any data or environment that is needed for a candidate application to be able to pass the tests for a particular Building Block in the testing application

• Repositories. As noted, some repositories may contain use-case specific data. However, there may also be repositories that are needed by multiple applications or use cases.

This document is intended to provide guidance for building block working groups and developers of products that will be integrated into a GovStack implementation. It also provides guidlines for implementers and system integrators who are deploying solutions that leverage the GovStack approach. It provides guidelines and principles that should be considered by all building blocks and cross-cutting requirements that must be considered for any GovStack project.

This will accelerate the collaborative development of best-of-breed digital public goods, enhancing efficiency and transparency across the world - especially in low-resource settings.

2.1 GovStack and the Building Blocks Approach

GovStack aims to provide a reference architecture for digital governance software to support sustainable development goals. Rooted in a "Whole-of-Government" approach, the GovStack Framework provides a methodology for leveraging common technology components and infrastructure to more easily create and deploy interoperable digital platforms which can address high-priority use cases across multiple sectors. The guidelines and requirements described in this document provide a framework for the development of digital building blocks oriented toward this goal.

2.2 Criteria for Building Blocks

The following provide criteria and definitions for Building Blocks, developed by organizations whose work is focused around achievement of the Sustainable Development Goals (SDGs). The criteria are drawn from the , developed by the International Telecommunication Union (ITU) and the Digital Impact Alliance (DIAL), as well as the developed by the Digital Public Goods Alliance (DPGA):

A Building Block:

• Refers to software code, platforms, and applications that are interoperable, provide a basic digital service at scale, and can be reused for multiple use cases and contexts.

• Serves as a component of a larger system or stack.

• Can be used to facilitate the delivery of digital public services via functions, which may include registration, scheduling, ID authentication, payment, data administration, and messaging.

• Building blocks can be combined and adapted to be included as part of a stack of technologies to form a country’s Digital Public Infrastructure (DPI).

• Building blocks may be open source or proprietary and therefore are not always DPGs.

"Building blocks can be as simple as a common set of rules or protocols (for example email programs like Simple Mail Transfer Protocol - SMTP), or complex (for example an open-source health information system like the DPG, District Health Information Software - DHIS2)“

Characteristics of building blocks:

• Autonomous: building blocks provide a standalone, reusable service or set of services, they may be composed of many modules/microservices.

• Generic: building blocks are flexible across use cases and sectors.

• Interoperable: building blocks must be able to combine, connect, and interact with other building blocks.

• Iterative evolvability: building blocks can be improved even while being used as part of solutions.

Per the DPGA definition, to be considered a building block, solutions must meet the following technical requirements determined by the GovStack Initiative which includes:

1. Open API, Open API Specifications, Rest API

2. Packaged in a container

3. Include a information mediator where communication flows between services that are not co-located

2.3 Building Block Layers

Building blocks are software modules that can be deployed and combined in a standardized manner. Each building block is capable of working independently, but they can be combined to do much more:

Building blocks are composable, interoperable software modules that can be used across a variety of use cases. They are standards-based, open source and designed for scale.

Each Building Block represents, as much as possible, the minimum required functionality (MVP) to do its job. This ensures each Building Block is usable and useful on its own, and easily extensible to support a variety of use cases.

A Building Block is composed of domain-driven microservices, modeled as closely as possible on existing roles and processes. This helps ensure each building block is as useful as possible in the real world.

Building Blocks exchange data using lightweight, human-readable data that can easily be extended where needed. Data models and APIs are described in a lightweight manner that’s human-readable, allowing them to be easily and quickly understood and validated.

2.4 Cross-Building Block Communication

A building block is only so useful on its own. In practice, building blocks MUST be connected together in a secure, robust, trusted manner that facilitates distributed deployments and communications with existing services.

2.4.1 Federation and Data Exchange Requirements

Each building block deployment SHOULD use an Information Mediator to federate and communicate with other data consumers and providers, particularly when communicating between services that are not co-located. This ensures the confidentiality, integrity, and interoperability between data exchange parties. An Information Mediator MUST provide the following capabilities:

• address management

• message routing

• access rights management

• organization-level authentication

• machine-level authentication

• transport-level encryption

• time-stamping

• digital signature of messages

• logging

• error handling

• monitoring and alerting

• service registry and discovery

2.4.2 Organizational Model

In order to effectively deploy a software solution using the Information Mediator, several policies and processes will need to be applied. This section briefly describes that organizational processes that must be in place.

First, a central operator will be identified and created. This organization will be responsible for the overall operation of the system, including operations and onboarding new members. Policies and contractual agreements for onboarding need to be created.

Next, trust services need to be set up internally or procured from third parties, including timestamp and certificate authorities. This provides the necessary infrastructure to support distributed deployments.

Finally, members can be onboarded and provided with access to the Information Mediator and methods to register the services that they provide as well as discover services that are available.

Once agreements are in place, members can deploy new services in a decentralized, distributed manner. Before deploying a new service, the central operator must be notified of any changes to access-rights, including organization and machine-level authentication before it can publish or consume data.

2.4.3 Technical Architecture

This section provides an overview of the technical processes and architecture that must be implemented once the organizational model has been created.

1. A Central Operator is responsible for maintaining a registry of members, the security policies for building blocks and other member instances, a list of trusted certification authorities and a list of trusted time-stamping authorities. The member registry and security policies MUST be exposed to the Information Mediator.

2. Certificate authorities are responsible for issuing and revoking certificates used for securing and ensuring the integrity of federated information systems. Certificate authorities MUST support the Online Certificate Status Protocol (OCSP) so that an Information Mediator can check certificate validity.

3. Time-stamping authorities securely facilitate time stamping of messages. Time stamping authorities MUST support batched time stamping.

4. The Service Registry provides a mechanism for building blocks to register the services that they provide and for other building blocks to discover and consume those services. Any services provided or consumed by a Building Block that leverages the Information Mediator architecture MUST use this service registry functionality.

2.5 Keywords and Definitions

2.5.1 Building Block-specific definitions

The following provides definitions for terms that are used by various building blocks.

Registration: Any approval/license/certificate issued by a public entity as a result of a request/declaration made by a user of the public service. The result of a “registration” is usually a number and/or a document (called certificate, license, permit, authorization, registration, clearance, approval, etc.)

Authentication: This is the technical process of establishing that the credentials (i.e. username, password, biometric etc.) provided by a party (user, system, other) is valid and that the party can be granted basic access to system resources with default access rights. Note that authorization also needs to be applied for a party to access protected resources.

Authorization: This is the technical process of establishing whether or not an authenticated party has rights to access a given protected resource. Access rights can typically be granted or revoked administratively on a read-only and/or read-write and/or execute basis through an administrative provisioning process. Permissions or rights defined for a party typically manifest in an access token that is granted at the time of authentication for the party. Hence the processes of authentication and authorization are intrinsically related.

• (Workflow) Activity - a single step in a workflow process.

• (Workflow) Process - a workflow process contains one or many activities.

• (Workflow) Instance - an instance of execution for a workflow process.

4.1 Design Principles

While the following principles are relevant to many technology deployments, when leveraging the GovStack approach it is important to keep these principles in mind during all phases of design, development, and deployment.

4.1.1 Citizen-Centric

Design of systems should be rooted in the needs of the citizens/users of these platforms. A Citizen-centric technology will include the following attributes:

• User-centered design

• Right to be forgotten: everything must be deletable

The best tools evolve from empathizing, understanding and designing for the needs of end-users. Accordingly, we’ve identified a series of use cases and user journeys here:

Each use case is composed of a collection of modules, or building blocks. As you can see, a relatively small set of these building blocks can be readily applied to a wide variety of applications in low-resource settings.

4.1.2 Open

Where possible, GovStack advocates for the use of open technology, which can reduce cost and help avoid vendor lock-in. Open technology can be defined as:

• Based on open standards

• Based on Digital Development Principles, see and

• Built on open-source software where possible

• Supports open development, see

• Cloud native where possible (Docker/Docker Compose/OCI containers)

4.1.3 Sustainable

Any Building Blocks should be developed in a manner which is sustainable and ensures that the technology will continue to be updated and maintained. Some core considerations for sustainability are:

• Continuous funding for maintenance, development and evolution, which results in lower long-term costs

• Uses microservices-based architecture instead of monolithic.

  • This increases interoperability, development and deployment speed and reliability.

4.1.4 Secure

• Building Blocks are audited and certified before being made available

• Development processes and standards enforce quality and security

• Different certification levels reflect level of standards-compliance

• Regular security scanning and auditing

• Public ratings and reviews

• Comprehensive logging and exception handling

4.1.5 Accessible

It is vitally important that technology solutions be usable by all. Some characteristics of accessible design include:

• Meets users where they are: web, mobile, SMS and/or voice. UI supports accessibility technologies, e.g. screen readers.

• SSO allows for signing in once for multiple services

• Deployment and development processes and standards are open to contributors

• Community-driven development tools for documentation and support

• Blueprints, templates and documentation

4.1.6 Flexible

GovStack is rooted in the concept that Building Blocks should be re-usable and configurable, such that they can support multiple use cases with minimal effort:

• Building Blocks can be reused in multiple contexts

• Each Building Block is autonomous

• Building Blocks are interoperable, adhering to shared standards

• Building Blocks should be easy to set up

• Standardized configuration and communications protocols should be used to connecting Building Blocks

• Building Blocks can be provided as a service (ICT opportunity)

4.1.7 Robust

Deployments of Building Blocks should follow these principles:

• Any client-facing functionality should operate in low-resource environments:

  • Occasional power

  • Low bandwidth

  • Low-reliability connectivity

• Easily scalable for high availability and reliability

• API-only based decoupling

• Asynchronous communications pattern decoupled through rooms is ideal

• Eventual consistency for data

4.2 Considerations

As with any software implementation, there are constraints and limitations in the GovStack approach that must be addressed. In any country context, there will be deficiencies that present challenges to any technology implementation. In the context of GovStack, the constraints and deficiencies that may be present must be considered at the outset of any project.

The following list of potential deficiencies that may be encountered with high-level descriptions should be kept in mind during the development and deployment of any Building Block. Each building block specification SHOULD specify mitigations for these issues:

4.2.1 ICT Governance

Poor or non-existent National ICT governance structure that makes decisions and ensures accountability framework to encourage desirable behavior in the use of ICT in the country. However, this may be described in documents but the implementation is suboptimal or not enforced.

4.2.2 Government ICT policy or Framework

No strategic policy framework for the acquisition and use of IT for social and economic growth in the country. The policy might be at the development stage and where the policy exists, the policy implementation is lagging or non-existent.

4.2.3 ICT infrastructure

The development of IT infrastructure in the country is lagging behind or sub optimal because of poor policies and insufficient investments in the ICT sector. Low coverage of power or the national grid and little penetration of alternative sources of energy especially in the rural.

4.2.4 Financial Resources and Investments in ICT

Limited funding for ICT projects and initiatives. ICT intervention may not be prioritized. No institutionalized or routinized support for ICT projects/ interventions by the government.

4.2.5 ICT Projects/Initiatives

ICT projects and intervention are implemented in a silo, none standard approaches and most of the ICT interventions are proprietary and high cost ventures from private institutions. No national standard architecture for interoperability/ integration of systems

4.2.6 Capacity development and social instruments

Low ICT literacy level among user, None or little research and development done by the national institutions/ academia on the use and scale up ICT in the country. Very few ICT professionals to support large scale ICT projects at national level

4.2.7 Connectivity/Internet access

Lack of or minimum network coverage by GSM and or broadband technologies. Low cellular subscribers per capita and very low internet subscribers per capita. The percentage fibre connectivity in the country is low. A greater percentage of the population do not have computers, laptops or smart phones.

4.2.8 Access to information

Number of household with internet connectivity is concentrated in the urban areas as opposed to rural areas.

4.2.9 Cost competitiveness

Technologies, which are not always ready-for market, are often more expensive than incumbent technologies, without the necessary supportive infrastructure. Competition from existing technologies, including unsustainable technologies

4.2.10 Knowledge and skills

New technologies require specialized knowledge and skills, which are often lacking in host countries where education levels in science, engineering and technology can be low, and emerging areas. ICT specialists is low

4.2.11 Social Legitimacy

New technologies treated with suspicion in local communities especially if prior experience of job losses or unintended social consequences

4.2.12 Cultural barriers

New technologies are seen as a challenge to cultural traditions and communal activities. Technology can also face barriers such as language, role of women in the society, lack of entrepreneurs or dependencies created by decades of development aid

Building blocks are responsible for meeting all cross-cutting requirements or specifying why specific requirements do not apply. Govstack compliance and certification processes will validate these requirements.

5.1 Follow TM Forum Specification REST API Design Guidelines Part 1 (REQUIRED)

See: TM Forum REST API Design Guidelines

Some key principles from these design guidelines are as follows:

• APIs MUST not include Personally Identifiable Information (PII) or session keys in URLs - use POST or other methods for this

• MUST support caching/retries

• Resource identification in requests Individual resources are identified in requests, for example using URIs in RESTful Web services. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server could send data from its database as HTML, XML or as JSON—none of which are the server's internal representation.

• Resource manipulation through representations. When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource's state.

• Self-descriptive messages Each message includes enough information to describe how to process the message. For example, which parser to invoke can be specified by a media type.

5.2 Follow TM Forum Specification REST API Design Guidelines Parts 2-7 (RECOMMENDED)

See: TM Forum REST API Design Guidelines

5.3 Communicate with other BBs only via API (REQUIRED)

Paraphrased from the Amazon API Mandate: https://api-university.com/blog/the-api-mandate/

1. All BBs must expose their data and functionality through service interfaces (APIs).

2. Building Blocks communicate with each other through these interfaces.

3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.

4. It doesn’t matter what technology is used. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.

5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.

Building blocks MUST NOT use shared databases, file systems or memory for data exchange with other building blocks.

5.4 APIs must be Versioned (REQUIRED)

Use semantic versioning when documenting changes to API definitions. Any breaking changes to APIs MUST use a different endpoint, as shown here: e.g. /api/v1 and /api/v2

See https://semver.org/

5.5 Documentation must be Provided (REQUIRED)

Documentation on the installation and use of the Building Block MUST be provided. Where possible, this documentation SHOULD be stored alongside code in a repository. Documentation MAY be generated from code where applicable.

5.6 Provide an OpenAPI specification (REQUIRED)

Each building block’s service APIs MUST be defined and exposed using a standardized machine-readable language. External APIs are described using the OpenAPI 3.x specification. See the following resources for additional information:

• Definition of the OpenAPI standard

• Swagger OpenAPI 3.0 Specification

5.7 Building blocks must be deployable as a container (REQUIRED)

• Each building block MUST be ready to be deployed as independent container images. Source code and build instructions SHOULD be committed to a public code repository where possible.

• A building block may be composed with Kubernetes or docker compose. All build files must be included alongside the source code.

5.8 Include all deployment scripts (RECOMMENDED)

When a building block requires deployment tools such as Kubernetes or Ansible, configuration and deployment scripts should be included in the building block repository. Use of this type of deployment configuration will make individual components of the building block independently scalable and make building blocks less monolithic and more efficient.

5.9 Comply with GDPR Principles (REQUIRED)

Building Blocks MUST conform to GDPR principles, including the right to be forgotten account deletion, and privacy requirements to protect the rights of individuals. Note that these requirements may vary by region, and building blocks must conform to regulatory requirements wherever they are deployed.

5.10 Include Support for Capturing Logging information (REQUIRED)

Building Blocks MUST have a mechanism for generating logging information. This may be as simple as using STDOUT and capturing through docker logs, or may use other log sinking technologies.

5.11 Use Web Hooks for Callbacks (REQUIRED)

When Building Blocks require callback functionality, they must use webhooks and not direct links to functions within the building block.

5.12 Enforce Transport Security (REQUIRED)

All Building Blocks MUST support secure HTTPS transport with TLS 1.3 and insecure cyphers disabled.

5.13 GET and PUT APIs must be Idempotent (REQUIRED)

GET and PUT APIs (as well as HEAD, OPTIONS, and TRACE) must be idempotent, returning the same value if called multiple times. POST and DELETE APIs will not be idempotent as they change the underlying data. Reference https://restfulapi.net/idempotent-rest-apis/ for more information.

5.14 Use Stateless APIs wherever Possible to Enhance Scalability (RECOMMENDED)

API calls SHOULD be able to be made independently of one another. Each API call should contains all of the data necessary to complete itself successfully.

5.15 Include Transaction/Trace/Correlation IDs (RECOMMENDED)

Transactions that cross multiple services SHOULD provide a correlation ID that is passed with every request and response. This allows for easier tracing and tracking of a specific transaction.

5.16 Include Clearly-Defined Key Rotation Policies (RECOMMENDED)

Some blocks may require the use of security keys. Those that do must have clearly defined key rotation policies to enhance security

5.17 Databases should not Include Business Logic (RECOMMENDED)

Database processing tools like triggers and stored procedures should be avoided.

5.18 Use only Unicode for Text (REQUIRED)

5.19 Use ISO8601/UTC for Timestamps (REQUIRED)

5.20 Building Blocks must be Autonomous (REQUIRED)

Each building block MUST be capable of running independently, without requiring other dependencies such as external data stores or other building blocks.

5.21 Use Secure Configuration (REQUIRED)

Configuration MUST be done using secure processes, such as environment variables or a secure secret store.

5.22 Design for Asynchronous First (RECOMMENDED)

Designs should support occasional connectivity/low bandwidth, and should allow for asynchronous communication between building blocks. A Publish/Subscribe design pattern can be used to handle changes, allowing loosely-coupled solutions to be assembled without changing existing APIs.

5.23 Use Standardized Data Formats for Interchange (REQUIRED)

JSON SHOULD be used for data models/services wherever possible. See https://www.json.org/json-en.html. Where JSON exhange is not possible, building blocks must use other standard data formats (such as XML).

5.24 Use Existing Standards for Data Interchange, Where Available (RECOMMENDED)

If an existing standard is available, it should be used, e.g. DICOM/Hl7/FHIR for healthcare. TMForum has a large library of standardized APIs and data models that can be used.

Building blocks and building block solutions MUST leverage existing standards, especially those listed in the Standards section below.

5.25 Use I/O Sanitization (RECOMMENDED)

Building blocks SHOULD validate all incoming data to ensure that it conforms with the expected format and type. APIs should also sanitize incoming data, removing any unsafe characters or tokens.

5.26 Provide a Compliance Test Mock/Example Implementation (OPTIONAL)

A building block MAY provide a mock testing implementation of API functionality to show example endpoints and data payloads. See https://github.com/GovStackWorkingGroup/bb-template/tree/main/examples for additional information.

5.27 Building blocks should be Localizable (RECOMMENDED)

Where a building block has a human user interaction, it SHOULD be able to present information to the user in their local language. Building blocks should be designed to support multiple locales.

5.28 Use NTP Synchronization (RECOMMENDED)

Where precise timestamps are required, building blocks SHOULD leverage Network Time Protocol (NTP) to synchronize timestamps between servers.

Other Considerations

Software development best practices are recommended for all building blocks. The following guidelines should be followed as part of the software development process.

EOL SHOULD be at Least 5 Years

No languages, frameworks, or dependencies should be used in a building block where that component has an EOL of less than 5 years.

Preference for TIOBE Top 25 Languages

See https://www.tiobe.com/tiobe-index/

Where possible, building blocks SHOULD be written using commonly used languages to ensure ongoing maintenance and support are as easy as possible. Building blocks MAY leverage less common languages, such as shell scripting where needed.

Regular Security and Code Quality Audits SHOULD be Run

These should be run across the code base and dependencies, e.g. https://www.sonarqube.org/ and/or https://snyk.io/ .

SHOULD Include Unit and Integration Test Coverage

Building blocks should include tests that provide both unit and integration test coverage

SHOULD Follow Best Practices for Public Code

See https://standard.publiccode.net/ and practices outlined here:

• Code in the Open

• Bundle Policy and Source Code

• Create Reusable and Portable Code

• Welcome Contributions

• Maintain Version Control

• Require Review of Contributions

• Document Your Objectives

• Document your code

• Use plain English

• Use open standards

• Use continuous integration

• Publish with an open license

• Use a coherent style

• Pay attention to codebase maturity

GovStack Reference Architecture document

The following standards MUST be used in the development of any Building Block. Adhering to common standards as listed below promotes interoperability and facilitates efficient data transfer between Building Blocks.

7.1 Unicode

Used for encoding text https://en.wikipedia.org/wiki/Unicode

7.2 ISO8601/UTC

Used for dates and timestamps https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)

7.3 JSON

Used for exchanging data

7.4 JSON Schema

Used for specifying data models. Note that OpenAPI 3.1 has full support for JSON Schema http://json-schema.org/

7.5 REST

Used for implementing APIs

7.6 OpenAPI 3.1 (AKA Swagger)

Used for specifying and documenting APIs. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md Note that OpenAPI 3.1 supports inline JSONSchema for model definitions

7.7 Docker/Docker Compose/OCI Containers

Used for packaging building block components for deployment https://en.wikipedia.org/wiki/Docker_(software) https://www.docker.com/resources/what-container

7.8 QR code

Must be generated with the ISO/IEC 18004:2015 standard

Govstack architecture enables an application to call services of another application within Govstack and get responses containing information from the called application. In many cases, control over the User Interface may need to be passed from an application to another Building Block. For example, if a user is doing a biometric or multi-factor authentication, the ID Building Block can present the UX to the user for that process. If a user is sending or receiving a payment, the UX can be handed off to the Payment Building Block for the user to enter account information for the payment. In general UI level switching may be necessary because

a. The called service may collect inputs from the user directly through its own UI as it is not preferred to exposed collected data collection to the calling application for security reasons.

b. It may be unreasonable to expect that the calling application designs screens of other Building blocks it calls, considering diverse requirements, standards, policies, etc., in respective domains.

c. Building blocks may be developed by different entities and evolve independently. Hence tight integration is not preferred, loosely coupled but secure interoperability is needed.

If the applications needing a service and the application providing the service are not co-located, then some control and data exchanges are needed at UI level, a secure authentication mechanism is needed before the service is provided. A few authentication mechanisms relevant to UI level switching between independent applications are discussed below:

Considering for example, a citzen already registered in a Govstack logs into the energy deparment's application to pay an eletricity bill. The application will submit the user's login credentials to an Identity server at its backend and gets in return a session token for that user, if authenticated successfully. On its UI the application presents a due electricity bill along with "Pay" button. When the user clicks the "pay" button, the application UI redirects the user to a payment building block ui to collect relevant payment. After payment is remitted the payment building block redirects back to the Energy dept application to confirm successful payment after which the application may present a receipt generated for the user.

Given that context, the following ways are possible for UX switching:

1. OpenID Connect based Single Sign-On (SSO)

A Single Sign On (SSO) system can be used, which allows an authentication token to be passed from the application to another Building Block. An authorization server is used to handle the initial user login and the access token received from the auth server can be passed to other Building Blocks and used to authorize access to the Building Block functionality.

1. OpenID Connect based Single Sign-On (SSO): SSO allows users to authenticate once and access multiple applications without the need for repeated login prompts adopting popular SSO protocols such as OAuth authorization and OpenID connect. OAuth framework allows users to grant access to their resources without sharing their credentials with the requesting application. It enables a user to authenticate with one application (called the "identity provider" or "authorization server") and obtain an access token. This access token can then be used to access protected resources in other applications (called "resource servers") without requiring the user to authenticate again. OpenID Connect facilitates SSO by allowing users to authenticate once with the identity provider and then access multiple applications without repeated login prompts. This improves user experience and reduces the need for managing multiple sets of credentials. The OpenID Connect builds upon OAuth 2.0 to provide user authentication as well as authorization. It allows for identity information to be exchanged between the identity provider and relying applications. When a user authenticates with the identity provider, the relying application (service provider) receives an ID token containing information about the user. This ID token can be used to authenticate the user in the relying application by cross verification with the identity server.

This mechanism has some inherent advantages such as:

Enhanced User Authentication: OpenID Connect provides a standardized and robust mechanism for user authentication. It allows for the exchange of identity information between the identity provider and relying applications, enabling stronger authentication and verification of user identities.

Standardized Protocol: OpenID Connect is widely adopted and standardized, making it easier to implement and integrate with various applications and platforms. It provides clear guidelines and specifications, reducing the complexity of authentication implementation.

User Profile and Attributes: OpenID Connect allows for the retrieval of user profile information and additional attributes from the identity provider. This can provide valuable user data to relying applications for personalization, authorization, and user-specific functionality.

There are some inherent disadvantages of OpenID Connect as well:

Authentication: The called application gets user authentication, but not authentication of the calling application, especially when the two applications are not colocated physically.

Increased Complexity: Implementing OpenID Connect can be more complex compared to token-based authentication or secure proxy methods. It requires understanding the underlying OAuth 2.0 framework and configuring the identity provider and relying applications accordingly.

External Dependency: OpenID Connect relies on an external identity provider for user authentication. This introduces a dependency on the availability and reliability of the identity provider. If the identity provider experiences issues, it can affect the authentication process for the relying applications.

Single point of failure: Centralized Identity server may lead to single point of failure, but leads to consistency and focus on managing security concerns at one place in the architecture.

2. IFRAME based Secure Proxy Authentication

In this case the calling application UI has an embedded screen component (iframe) that internally points to the called application’s webserver URL. Information within the iframe can be isolated from the main application or may exchange select information through triggered “events” exposed between them. An iframe (inline frame) is a HTML element that allows one to embed one HTML document within another. In the context of authentication and secure redirection between UIs of different web applications, iframes are typically used as a part of the secure proxy mechanism. Specifically, iframes can be used within the secure proxy to load and display content from a different web application or domain while maintaining the security boundaries between the two applications. The iframe can serve as a container for displaying the UI of the target application within the UI of the calling application. The use of iframes in this context is often employed to achieve seamless integration and user experience between different web applications, allowing for the rendering of UI components from multiple sources within a single interface.

Assuming the user has already logged into the parent (calling) application, then some action in the main application screen (like clicking "pay" button may invoke the iframe, the application verifies role based access permissions of the user to invoke payment BB service and then transfer control to the IFRAME, which inturn invokes the UI of the called application/BB which is linked to the iframe at build time. The Payment BB receives the request, presents its ui in the iframe and finishing its business it posts a status update event in the IFRAME with relevant details. The IFRAME relays the event to calling application and then the application will process the details and further steps appropriately.

The secure proxy mechanism provides several advantages:

Centralized Security: By intercepting and controlling client requests, one can enforce security policies consistently across multiple applications and services. The calling application owns the responsibility to use the secure proxy as a central point for authentication and authorization, while the called applications need not handle these concerns and rely on the calling application as source of truth.

Simplified Logic: With a secure proxy handling authentication and authorization in the parent application, called applications can focus on their core functionalities rather than implementing these security mechanisms independently. This simplifies application development and maintenance.

However, it has some limitations and challenges:

The calling application places trust and control in the calling application hence the Risk of serving a calling application that is already compromised.

Since applications and BBs may be typically separate third party products their developments may not be synchronized.

It is important to note that the secure proxy mechanism introduces an additional component to the architecture, which requires proper configuration, maintenance, and monitoring. It also adds an extra network hop and potential performance overhead, so it's crucial to ensure that the proxy infrastructure is appropriately scaled and optimized to handle the expected traffic.

The specific implementation of the secure proxy mechanism can vary based on the chosen proxy software or infrastructure components.

1. Key-based, decentralized Authentication

This method involves generating and exchanging dynamically generated key between the applications. Assuming the user has already authenticated and logged into first application the user starts transaction in that application. When the user clicks a relevant button (e.g. "pay") on the screen of that application, the application obtains a unique temporary key from the target application by making a specific api request through the information mediator. Then the application's frontend redirects to the URL of webserver of the target BB/application and passes the key along with other relevant data. The called application validates the key internally before providing the UI to complete payment transaction. After completion the BB's backend returns the passed/failed status to its front end ui. The UI then redirects back to the calling application returning the status as a payload. JSON Web Tokens (JWT) is a commonly used token format.

This mechanism has some advantages:

Simplicity and Flexibility: Token-based authentication, such as JWT, is generally simpler to implement and understand compared to OIDC. It provides flexibility in how tokens are generated, validated, and managed, allowing for customization based on specific requirements.

Decoupled Architecture: Key-based authentication enables a decoupled architecture where the authentication process is not dependent on the identity provider. It also distributes key-based authentication process load across called BB/Applications and not on centralized server. Hence is also not dependent on a single-point-of-failure.

Scalability: Key-based authentication can be more scalable since it does not require communication with an identity provider for authentication. The server can verify the token locally, reducing external dependencies and potential bottlenecks.

Dynamic provisioning: Since what is contained in a key is decided by the called application, it is possible to generate unique keys for each service call (instead of session wide tokens) enabling higher level of security.

There are some inherent disadvantages of Token-Based Authentication as well:

Lack of Standardization: Although JSON Web Tokens (JWT) signed by JSON Web keys (JWK) are standard formats for encapsulating unique authentication information, the actual payload of a key is not a standardized specification for authentication. This can result in varied implementations and interoperability challenges when integrating with different systems and applications.

Authentication: The called application gets authentication of the calling application because it gets request for key through the backend via Information mediator, which allows only registered applications to send requests. However, this does not authenticate the user. It trusts that the calling application has appropriately authenticated the user.

Additional Development Effort: Implementing token-based authentication may require more development effort to handle aspects such as token generation, validation, and session management. Customization and maintenance of these components can be time-consuming.

4. Hybrid Model

This is a combination of openID connect and Token based connect models and hence advantages of both user and application authentication. In this case the user logs in into the the calling application/building block(in this example, Registration), which authenticates the user credentials from an identity server and obtains a unique session token for that user. The registration process may collect required details and present a “payment” button to the user. When the user clicks it, the application will send a request for a one time key from the called building block(in this example, the Payment building block). It then redirects to the url of payments BB page and passes the user token and the key as part of the payload it needs to transfer to payments BB. The payments BB now verifies the key to make sure a valid registered application is sending the request and then authenticates the user token with the identity server to ensure an authorized user is requesting the service. After confirming this, it will put up the required UI page for collecting user payment. Once the payment process is complete it will redirect back to the calling application screen url, along with the payload containing the same token, key along with success/failure status code. This switching can be multilevel in the sense that the same protocol can be used by payments building block to switch to another building block at the front end if required. In such a case the returning path shall also be in the reverse order of the forward switching path, so that appropriate keys are used in each nested branch.

Any of these mechanisms may be used, depending on the implementation. In general GovStack recommends option 1 or option 4.