Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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).
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.
Adaptors should not be used for outbound requests.
In general it is the application which manages interactions and requests from various Building Blocks
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
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.
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
Adaptors Perform 3 distinct functions (all synchronous):
Class 1 - URL rewriting (mapping a GovStack URL to a URL from a native API)
Class 2 - Payload mapping (transforming data payloads between GovStack and native formats)
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. \
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.
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
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.
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.
GovStack Reference Architecture document
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.
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.
See: TM Forum REST API Design Guidelines
Paraphrased from the Amazon API Mandate: https://api-university.com/blog/the-api-mandate/
All BBs must expose their data and functionality through service interfaces (APIs).
Building Blocks communicate with each other through these interfaces.
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.
It doesn’t matter what technology is used. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.
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.
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
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.
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:
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.
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.
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.
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.
When Building Blocks require callback functionality, they must use webhooks and not direct links to functions within the building block.
All Building Blocks MUST support secure HTTPS transport with TLS 1.3 and insecure cyphers disabled.
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.
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.
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.
Some blocks may require the use of security keys. Those that do must have clearly defined key rotation policies to enhance security
Database processing tools like triggers and stored procedures should be avoided.
Each building block MUST be capable of running independently, without requiring other dependencies such as external data stores or other building blocks.
Configuration MUST be done using secure processes, such as environment variables or a secure secret store.
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.
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).
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.
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.
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.
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.
Where precise timestamps are required, building blocks SHOULD leverage Network Time Protocol (NTP) to synchronize timestamps between servers.
Software development best practices are recommended for all building blocks. The following guidelines should be followed as part of the software development process.
No languages, frameworks, or dependencies should be used in a building block where that component has an EOL of less than 5 years.
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.
These should be run across the code base and dependencies, e.g. https://www.sonarqube.org/ and/or https://snyk.io/ .
Building blocks should include tests that provide both unit and integration test coverage
See https://standard.publiccode.net/ and practices outlined here:
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.
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: GovStack Use Cases
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.
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 https://digitalprinciples.org/ and https://digitalinvestmentprinciples.org/
Built on open-source software where possible
Supports open development, see https://standard.publiccode.net/
Cloud native where possible (Docker/Docker Compose/OCI containers)
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:
Stewardship is critical, see https://publiccode.net/codebase-stewardship/
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.
From Wikipedia: a variant of the service-oriented architecture (SOA) structural style – arranges an application as a collection of loosely coupled services. In a microservices architecture, services are fine-grained and the protocols are lightweight.
With any technology deployment, security is paramount. Detailed security requirements are defined in the GovStack Security Requirements. Beyond those standards, Building Blocks should have the following attributes:
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
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
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)
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
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:
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.
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.
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.
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.
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
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
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.
Number of household with internet connectivity is concentrated in the urban areas as opposed to rural areas.
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
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
New technologies treated with suspicion in local communities especially if prior experience of job losses or unintended social consequences
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
Additionally, the Principles for Digital Development are especially relevant when designing for low resource setting. Refer to https://digitalprinciples.org/ for information on these Principles.
Developed by Max Carlson, Kristo Vaher, Steve Conrad, Dr. P. S. Ramkumar, Wes Brown, Aare Laponin, Uwe Washer, and Trevor Kensey
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.
Used for encoding text https://en.wikipedia.org/wiki/Unicode
Used for dates and timestamps https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_(UTC)
Used for exchanging data
Used for specifying data models. Note that OpenAPI 3.1 has full support for JSON Schema http://json-schema.org/
Used for implementing APIs
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
Used for packaging building block components for deployment https://en.wikipedia.org/wiki/Docker_(software) https://www.docker.com/resources/what-container
Must be generated with the ISO/IEC 18004:2015 standard
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.
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.
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.
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.
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.
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.
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.
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.
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.
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):
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:
Open API, Open API Specifications, Rest API
Packaged in a container
Include a information mediator where communication flows between services that are not co-located
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.
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.
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
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.
This section provides an overview of the technical processes and architecture that must be implemented once the organizational model has been created.
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.
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.
Time-stamping authorities securely facilitate time stamping of messages. Time stamping authorities MUST support batched time stamping.
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.
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.
It is STRONGLY RECOMMENDED that a building block uses an information mediator (as described below and in the ) for any communications across the internet. An Information Mediator is not required for communication between building blocks which are co-located. In this case, communication may occur using standard API calls.
Refer to the full description of the for more information.
Within this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in when, and only when, they appear in all capitals, as shown here.
Workflow Terminology: See more comprehensive descriptions of the workflow terminology in the .