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

The GovStack initiative aims to build a common understanding and technical practice on fundamental reusable and interoperable digital components, which we collectively refer to as Building Blocks. Our effort is expert-driven and community-based, and includes the participation of multiple stakeholders to bring together expertise for strengthening a government's cross-agency architecture view.

Our focus is to enable countries to kickstart their digital transformation journey by adopting, deploying, and scaling digital government services. Through the digital "building blocks" approach, governments can easily create or modify their digital platforms, services, and applications by also simplifying cost, time, and resource requirements.

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 authorization services described here)

• 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 adaptor 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 SDG Digital Investment Framework, developed by the International Telecommunication Union (ITU) and the Digital Impact Alliance (DIAL), as well as the definition of Building Blocks 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.

It is STRONGLY RECOMMENDED that a building block uses an information mediator (as described below and in the Information Mediator Building Block specification) 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.

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

Refer to the full description of the Information Mediator Building Block for more information.

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

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 BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

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 Terminology: See more comprehensive descriptions of the workflow terminology in the Workflow and Business Process Automation Building Block specification.

• (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.

Developed by David Forden, Jean-Reynald Vivien-Gayout de Falco, Dr.P.S.Ramkumar and Max Carlson

The GovStack community understands that there are a wide variety of people from different backgrounds that have valuable insight into the work GovStack is doing. Therefore, we provide multiple ways in which people from those different backgrounds can interact and give us their insight. Here are three:

1. Proposing changes via the Give Feedback form

To ensure giving feedback on the specifications is as accesible as possible to the widest audience, we have created an online form that will take your feeback and direct it to the right people within the project automatically.

1. In the navigation menu above, click the Give Feedback link

2. Enter your contact details so that people in the project can follow up with further questions on your feedback

3. Note that the page you were browsing has already been entered into the form on your behalf. If this is not the page on which your feedback is relevant, please edit the link as needed

4. Please give your feedback, remembering to describe the problem as you see it, giving one or more alternative suggestions if you have them, and desccribe why the change is required

5. On submission, the form will reply with a link to a Jira issue we have automatically created on your behalf. This is where the GovStack project team will work on the feedback. You are welcome and encouraged to register and participate in the discussion in the comments.

2. Proposing changes via a pull request

Some members of the community will have experience using git to directly interact with specification content and you may do so with the following process.

Note that the content in the GovStack specifications follows the Markdown standards applied by the GitBook tool.

1. Check our issue queue first to see if anyone else has already reported this issue.

2. Create a new issue and tell us about the problem that you see.

3. The maintainer of this section will be alerted and work with you to decide what changes should be made

4. If invited to do so, create a pull request in the appropriate GovStack GitHub repository, including the issue number and short description in the pull request title, for example: {Jira issue number} - {short description of the change}- an example would be gov-001 - Adding contribution information. Note that pull requests that do not mention an associated issue number will not be alerted to our maintainers

5. Once the issue describes the reason for a change and links to the change you propose, a maintainer for that building block is alerted

6. The maintainer will work with you to ensure that the change meets our standards for inclusion

7. We value all contributions to the project and, even if the change is not accepted, we always strive to give feedback that helps you understand the decisions taken.

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 Security Requirements document provides cross-cutting guidance for any GovStack implementation, whether an individual Building Block or a full GovStack solution to address one or more use cases. It provides a reference for security concerns and requirements for how to implement and deploy secure solutions.

This document also describes a set of 'Authorization Services' that should be implemented for any GovStack implementation. The authorization services provide secure communication between building blocks as well as a mechanism for user authentication and definition of roles and permissions for users.

2.1 Cross-Cutting Security Requiremetns

Security requirements address all cross-cutting security issues and concerns for the whole GovStack digital platform including every layer, every building block and all applications. Although other building blocks address “some” security aspects such as “Identity building block” (addressing the foundational identity aspects and document workflows etc.) the resultant solutions delivered by all building-blocks (including the “Identity building block”) MUST comply with the standards and requirements set by this security requirements document. This document covers security requirements of two types:

• Build-time Security: These are considerations for embedding security during development of building blocks and applications.

• Deployment time Security: These are considerations for enforcing security measures in deployed systems during run-time.

These may consist of cross cutting functionalities that can be utilized for various building blocks and specific requirements for the Security Building Block itself, to provide secure internet access for user interaction with applications and building blocks in Govstack.

The security requirements are based on the NIST CyberSecurity Framework and defined herein through review of GovStack use cases and best practices for securing and hardening government infrastructure. It MUST also be noted that the security building block defines the core requirements to implement policy based API security and management across the internal building blocks as well as external applications and 3rd party services consumption. This is based on the architectural assumption that all inter-building block communication/integration with external applications and users MUST be through REST APIs.

2.2 Authorization Services

Though these security requirements are cross-cutting, this document also provides guidance on how to implement core 'Authorization Services' within a GovStack implementation. These services provide the mechanism for user authentication, tracking the specific permissions and roles that a user has and managing access to the various Building Blocks that are consumed by the application. The functions of the Authorization Services include the following:

• User authentication

• Management of access to Building Block APIs

• API Gateway functionality which will manage incoming requests

• Identity and Access Management and/or Role-Based Access Control.

These modules are described in Sections 7 and 8 of this document (Authorization Services and Additional Security Modules)

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

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: 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.

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 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)

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:

• 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.

4.1.4 Secure

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

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

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.

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.

In order to enable the delivery of GovStack use cases, a mechanism must be defined that provides the appropriate level of access to the various building blocks by different users and organizations. This includes defining information sharing across service or organizational boundaries, enforcing appropriate roles and permissions for users, allowing user session information to be passed between building blocks, and enforcing secure access between Building Blocks (either co-located within a service, or across applications/organizations using an Information Mediator).

Note: Additional technical detail and example scenarios can be found in this document

7.1 Key Requirements

• Authentication and IAM/Roles/Permissions should be managed by an Authorization Service (functionality extracted from current Security spec) using well-defined standards like OpenID Connect (OIDC).

  • This service will handle login, defining roles and permissions, and returning a set of roles/permissions for a user session

  • This service may be implemented as a standalone Building Block or as part of the Application that is controlling the user flow.

• After user login and retrieval of roles/permissions for that user

  • The Application is responsible for managing any outbound calls based on the roles/permissions for that user - whether to internal BBs or cross-organizational requests through IM.

  • The Application will manage the API keys/credentials needed to access any local BB APIs that it calls

  • We will not pass user/session information when making API calls to local BBs

  • We will not pass JWT tokens or roles when making API calls through Information Mediator

• JWT/tokens need to be exchanged between different UIs/applications - If we need to pass control over to another app to fill in some information (giving consent, etc) - use OIDC

• The Information Mediator is used to facilitate communication between different organizations. The authorization and level of access is defined at the organization level, not the user level (ie. this particular organization has permission to access this set of data)

  • The security server will hold/manage credentials and API keys that are needed for accessing remote services

  • An organization can also allow access to an individual user based on a foundational ID

• IM is needed when going outside of a local network (ie. across the internet)

7.2 Accessing the API of an existing DPG or Product which is functioning as a Building Block:

• Set up an account/set of credentials in the other DPG/application that allows access to the APIs

• The authorization services (either within the application or separate functionality) will hold the login credentials in some type of secret storage (.env file or similar mechanism)

• When calling an API in the DPG, the Application should first call the DPG login API (there must be an API exposed for login) and then hold the token that is needed for API calls

• The Application will pass the appropriate token on subsequent API calls to the DPG

7.3 User Role and Permission Management

Within a GovStack implementation, an Identity and Access Management (IAM) or Role-Based Access Control (RBAC) system must be in place. This will define the level of access and permissions that a particular user (or group of users) will have within the GovStack system. The requirements for IAM/RBAC are described in Section 8.2 of this security specification

7.4 Definitions

Service: An API or endpoint provided by a Building Block or internal microservice of the Application

Application: One or more Building Blocks that may be combined with a UI and/or internal services which implement some business logic to provide a set of related services.

Use Case/User Journey: A system involving one or more UX components that allows a user to access multiple services which may be co-located or require the use of an information mediator to access a set of services/applications.

Organization: An entity that maintains one or more applications or services that may be consumed by other organizations

User: An individual that is accessing a particular application or set of services

Information Mediator: Connects applications across the internet, allowing services that are owned by different organizations to share data securely and using agreed-upon rules

Foundational Identity: a unique identifier for an entity that corresponds with a national identification system

Functional Identity: a login or user account that is associated with a particular application or set of services

Session: a set of information (or token) that provides context to a particular user interaction with an application (ie. keeping track of a logged-in user and what they have permission to do while they are logged in for a particular period of time)

The following standards are applicable to all aspects of the security building block and cross-cutting across other building blocks. Note that these are not technical standards but the process framework standards that shall be used to guide security decisions on the project::

• All of the implementation processes and guidance MUST follow the NIST CyberSecurity Framework (see )

• All of the security issues and concerns to be addressed are related by number to the core requirements above. The detailed definitions can be found in the document entitled Digital Platform Security for GIZ, ITU DIAL GovStack (see )

• It is assumed that the maximum level of information security required is what is known as CUI (Controlled Unclassified Information). Processes dealing with CUI must conform with NIST SP 900-171 Rev.2 (see )

The key security functionalities outlined here describe the required facilities that this security building block MUST provide as well as security compliance measures that must be implemented by all building blocks. Note that specific API definitions are not likely to be created by the security building block as any interfaces required are to be based on open standards and implemented as part and parcel of acquired solutions. A good example of this is the adoption of standards like OAuth2 and OpenIDConnect for authentication and authorization. The functional requirements for the implementation of an appropriate API Management and Gateway services solution can be found in a separate section of this document below.

The basic framework by which security is addressed for GovStack is largely based on the (hitherto referred to as NIST CSF) and the standard (hitherto referred to as NIST 800-171) for managing controlled unclassified information (CUI) but does also incorporate other security related requirements. The GovStack security requirements are also informed by and should be compatible with the (hitherto referred to as ISO-27001).

The Specific GovStack Security Related Concerns is organized in terms of the major functions of the NIST CSF which is defined by NIST as 3 major approaches/facets for implementation:

4.1 Specific GovStack Security Related Issues

This section of the document provides a specific list of the concerns, principles, procedures and actions (collectively termed as security related issues) that have been identified for GovStack along with:

• How each issue maps to the existing building blocks and their respective working groups

• What type of organizational risk is anticipated if the issue is not addressed (i.e. high/medium/low)

• Which target phase of the project the issue must be addressed in (i.e. first/second) - third phases are usually never completed

• How feasible it is to address the issue in a limited-resource or low-resource setting (predominantly related to costs) - see the document for the definitions associated with low-resource settings.

A general description and/or discussion of the issue that needs to be addressed and the various alternatives available for addressing it (not exhaustive). The security issues are organized by the 5 NIST functions (Identify, Protect, Detect, Respond, Recover).

4.2 Security Issues by NIST Function

4.2.1 IDENTIFY

4.2.1.1 Authentication and Authorization

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity Description: Authentication and Authorization MUST be addressed across the board. It is likely to be built-in to API Management and Gateway and accessed by mobile and web applications using a token based approach. All communications from all clients (web/mobile/BB clients etc.) MUST be via API so this is a sensible point of implementation given the stateless nature of applications. Authentication and authorization MUST also be addressed at an application access level for each and every application (web/mobile/desktop etc). It would be wise to utilize the same framework and capabilities for this. Comments: Each building block MUST implement centralized authentication and authorization (minimally proxied or implemented via the common IAM solution and/or API Management and Gateway services).

4.2.1.2 Multi-Factor Token and Password Strength/Complexity Management

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Credential strength management is likely built-in to API Management and Gateway. All communications from all clients (web/mobile etc.) must be via API so this is a sensible point of implementation also. Each application MUST provide the ability to determine credential strength at the time of registration and thus permit or deny the offered credential. Comments: Each building block MUST implement Multi-Factor Token and Password Strength/Complexity Management for an indeterminate array of factors including biometric (this is to be implemented through leveraging a common IAM solution).

4.2.1.3 Access Control (RBAC, MAC, DAC)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Access control is also likely built-in to API Management and Gateway. All communications from all clients (web/mobile etc.) must be via API. The thin client nature of web and mobile dictates that all resources will exist behind API interfaces so this is the most sensible point to address it (i.e. either they have access to the API or they do not). Comments: Each building block MUST implement role based access control for all exposed API’s and resources (minimally proxied or implemented via the API Management and Gateway services)

4.2.1.4 Provisioning, Deprovisioning and Management of Identities and access rights

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Will need a process based solution for this. This selection will largely depend on the identity management and API management infrastructure chosen but will likely need to be a customized process that integrates provisioning across a number of products and services. Comments: Each building block MUST implement the ability to provision, deprovision and manage Identities and access rights (this may or may not be centralized for the whole architecture as a unified provisioning process).

4.2.1.5 Access and Authorization Audit, Logging, Tracing, Tracking

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Likely built-in to API Management and Gateway. All communications from all clients (web/mobile etc. must be via API) Comments: Each building block MUST implement access and authorization audit, logging, tracing and tracking with alerts (minimally proxied or implemented through the API Management and Gateway services).

4.2.1.6 End User Device Registration, Deregistration, Re Registration and Device Platform Security

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Significant functionality provided by MOSIP - TBD Comments: Each building block dealing with physical devices MUST implement end user device registration, deregistration, re-registration and device platform security guidance/requirements to end users.

4.2.1.7 Biometric Security Credentials, Devices, Registration, Deregistration, Validation and device platform security

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Significant functionality provided by MOSIP - TBD Comments: Each building block dealing with biometric credentials MUST implement biometric security credential management, registration, deregistrations, re-registration, validation and device platform security etc. such as above for biometric capture devices.

4.2.1.8 Non-repudiation and Certificates (X509, OpenID and SAML etc.)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Likely built-in to API Management and Gateway but may also require certificate server etc. All communications from all clients (web/mobile etc. must be via API) Comments: Each building block MUST implement a framework for non-repudiable transactions using certificates and federation protocols (X509, OpenID and SAML 2.0 etc.)

4.2.1.9 Single-Sign-On and 3rd Party Security

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Identity/Security Description: Likely built-in to API Management and Gateway. All communications from all clients (web/mobile etc. must be via API) Comments: Each building block MUST be able to implement single-sign-on integration with 3rd party security.

4.2.2 PROTECT

4.2.2.1 Authentication and Authorization

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All Description: Applies to all connections throughout all components such as:

Web/Mobile UI<->API, Web/Mobile UI,<->Auth, BB<->API<->BB, Workflow<->API Comments: Each building block MUST implement SSL and TLS based connections for all TCP connectivity both external to the building block, and internally between components in a selective manner depending on data requirements.

4.2.2.2 Data Sovereignty/Residency Controls and Hosting, Transmission, Backup and Recovery

Organizational Risk Rating: Medium Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: All Description: Probably needs to be addressed during country rollouts due to data sovereignty regulations but needs to be catered for in the architecture options. Comments: Each building block where dealing with citizens data MUST provide the ability to implement data sovereignty/residency controls, hosting, transmission, backup and recovery in compliance with specific national laws and guidelines in each country.

4.2.2.3 Network Security, Protocols and Firewall implementations

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Cloud Infrastructure and Hosting Description: Infrastructure oriented but could be addressed at least in part by software defined networking (SDN) which can be part of a modern PaaS such as OKD Comments: Each building block shall comply with the overall secure networking architecture that will be deployed in place with each country implementation. Issues such as network security, networking protocols and firewall implementations etc. shall be defined as a part of the recommended architecture showing the various zones and separations required.\

4.2.2.4 Application Services Security (multi-tenancy etc.)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Likely best implemented as a feature of the chosen PaaS framework such as OKD Comments: The components for each building block are required to be deployed in containers according to the architecture description. The chosen container orchestration platform and PaaS solution shall provide the means to implement Application Services Security (such as multi-tenancy etc.)

4.2.2.5 VPN and Secure Network Access Controls

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Infrastructure oriented but could be addressed at least in part by software defined networking (SDN) which can be part of a modern PaaS such as OKD Comments: Each building block MUST comply with a defined set of VPN and Secure Network Access Controls. This will be based on the location of event producers and consumers on the network and hope the various segments of networking are sliced and protected. These standards are to be defined as a part of the target architecture implementation for each country.

4.2.2.6 Network Vulnerability Scanning

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Can be sourced from open source tooling such as OpenVAS, Wireshark etc. Comments: A suite of open source tools are to be adopted for the purposes of Network Vulnerability Scanning. These tools MUST be acquired by the project and centrally deployed in each country to ensure adequate network service security is in place.

4.2.2.6 Network Vulnerability Scanning

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Can be sourced from open source tooling such as OpenVAS, Wireshark etc. Comments: A suite of open source tools are to be adopted for the purposes of Network Vulnerability Scanning. These tools MUST be acquired by the project and centrally deployed in each country to ensure adequate network service security is in place.

4.2.2.7 Software Defined Networking and Network Slicing

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Infrastructure oriented but could be addressed at least in part by software defined networking (SDN) which can be part of a modern PaaS like OKD Comments: The project MUST adopt a software defined networking solution as a part of the core deployment architecture. This can and SHOULD be implemented as a part of the chosen PaaS solution.

4.2.2.8 Operating Systems, Services Security and Immutability

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Infrastructure oriented but could be addressed at least in part by OS like Centos which can be part of a modern PaaS such as OKD Comments: The project MUST deploy all services (typically microservices) on an immutable operating system infrastructure. Typically this can and SHOULD be provided as part and parcel of the chosen PaaS solution. The reason for this is such that if a security breach does happen then the operating system running the component cannot be modified by the offender.

4.2.2.9 Network, Service and Transaction Observability and Visibility

Organizational Risk Rating: Medium Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Can be addressed as part and parcel of a modern PaaS solution such as OKD including a service mesh such as ISTIO Comments: The project MUST implement a PaaS infrastructure that supports Network, Service and Transaction Observability and Visibility for protection against flaws and faults. This is so that complex transactions involving multiple components (likely microservices) can be observed and traced for the purposes of debugging and auditing. This would typically be implemented at least in part by a service mesh feature of the PaaS along with other integrated components for visualization such as the Jaeger open source tracing facility and the Kiali open source visualizer for example.

4.2.2.10 Man-in-the-middle (MITM) Attack Prevention (AKA Session Hijack)

Organizational Risk Rating: Medium Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low Building Block Mappings: All Description: Needs to handle insecure WIFI, email spam filtering, virus scanning and ad-blockers etc. at all levels. Comments: Needs to handle insecure WIFI, email spam filtering, virus scanning and ad-blockers etc. at all levels.

4.2.2.11 Cloud Platform Configuration Management and Securing Configurations

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All Description: Can be addressed as part and parcel of a modern PaaS solution such as OKD (which has secure encrypted stores for credentials) Comments: Each building block MUST adopt the facilities of the chosen PaaS for implementing Cloud Platform Configuration Management and Securing Configurations. For example authentication credentials for common components like databases need to be managed appropriately and simply across multiple environments through DevOps automated deployment etc.

4.2.2.12 Insider threats and internal audit-ability

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: The same security protocols, data encryption, protections and monitoring to be applied consistently both internally and externally. Comments: Each building block MUST adopt the same consistent security and privacy implementation measures to protect against Insider threats and internal audit-ability as those adopted for external exposures. This is a general statement.

4.2.2.13 Denial of service attack prevention

Organizational Risk Rating: Medium Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: High Building Block Mappings: All/Cloud Infrastructure and Hosting Description: Can be managed by implementing open source tools/services such as CrowdSec and DDOS Deflate, Fail2Ban, HAProxy, DDOSMon, NGINX etc. Note that HAProxy is built into PaaS solutions like OKD - TBD. Note that a number of API Gateway products are built around NGINX Comments: The project must implement an open source Denial of service attack prevention solution across all interfaces exposed to the public internet for each country deployment. This can be implemented through a reverse proxy web server environment using open source tools such as Fail2Ban, DDOS Deflate or HAProxy.

4.2.2.14 API Endpoint Security Policy Management and Gateway Services (both internal and external)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: The implementation of a centralized API Management and Gateway solution is probably not negotiable. All API interfaces both internal and external must be managed through this facility. Architecture will likely require a separate gateway for both internal and external services. Comments: The project MUST implement centralized API Endpoint Security Policy Management and Gateway Services (both internal and external). The reason for this is to implement a consistent layer of security for API interfaces that can be both managed centrally and alleviate the service developers from the implementation complexity of security. This can and SHOULD be implemented through an open source API Management and Gateway services product.

4.2.2.15 Virus/Malware and Ransomware Attack Prevention and Detection

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: Requires extensive and probably commercial software in many layers. Comments: The project MUST implement protection from and detection of Virus/Malware and Ransomware Attack. This likely requires a commercial solution suite as open source offerings are insufficient and not suitable for massive country-wide deployments w=such as GovStack.

4.2.2.16 Credential Theft Prevention

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: Can be addressed as part and parcel of a modern PaaS solution such as OKD (which has secure encrypted stores for credentials). Requires implementation through all development procedures and CI/CD etc. Comments: The project MUST implement credential theft prevention as part and parcel of its selected PaaS infrastructure. This is essentially an encrypted keystore that can host sensitive credentials and provide access to them with policy based security.

4.2.2.17 SQL Injection Attack Prevention

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: Can be addressed through open source tools such as those provided by the OWASP Foundation. Plugins for OWASP tools are available for PaaS solutions like OKD Comments: The project MUST implement SQL Injection Attack prevention as part and parcel of any and all applications development across building blocks. This can be implemented through open source tools such as those provided by the OWASP Foundation. This can and SHOULD be implemented as plugins through the PaaS solution and fully integrated into the DevOps toolchains for the project build and deployment.

4.2.2.18 Containing, Managing and Mitigating Hardware/Firmware Vulnerabilities and Known Exploits (directory traversal, rowhammer, spectre, meltdown, LazyFP etc.)

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low-Medium Building Block Mappings: Security Description: Typically these types of attacks are best mitigated by the use of commercial open source subscriptions as they close the window of vulnerability. New CVE’s happen every month and are becoming more common as IT advances. The upstream open source projects like OKD will eventually get the patches but it will be some time after commercial open source product patches are released to those with enterprise subscriptions. Comments: The project MUST implement solutions for Containing, Managing and Mitigating Hardware/Firmware Vulnerabilities and Known Exploits (directory traversal, rowhammer, spectre, meltdown, LazyFP etc.). This can and SHOULD be implemented through plugins to the PaaS solution and DevOps toolchain for the project to ensure that every single component deployed is scanned for known CVEs.

4.2.2.19 Data Privacy/Loss/Leakage/Confidentiality (individuals and organisations)

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: For the most part this involves end-point protection. Some tools are available in open source but it requires multiple layers of implementation and is thus more expensive. Comments: The project SHOULD implement solutions for prevention against Data Privacy/Loss/Leakage/Confidentiality (individuals and organisations). This likely requires expensive commercial packages rather than open source tooling.

4.2.2.20 Data Security (at rest and in transit - i.e. encryption and obfuscation etc.)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: Needs to be considered for each data store and each connection in the architecture. It is a very broad topic that must be addressed in the context of the data confidentiality requirements for each country implementation. Will be relatively expensive for resource-limited settings but it is a necessity. Comments: The project MUST implement solutions for Data Security (at rest and in transit - i.e. encryption and obfuscation etc.) consistently across all datastores and connections within and surrounding all building blocks.

4.2.2.21 Cross-site Scripting (XSS) Attack Prevention

4.2.2.22 Replication and Perimeter/Edge Data and Services Security

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: This is complex and applies to large architectures with multiple data centers and perimeter services. Every single element of the networks and trusts must be examined for vulnerabilities. There is no simple one-shot solution for this as it involves multiple data centers and multiple layers communicating and replicating potentially sensitive data. The degree to which this is addressed is commensurate with the relative sensitivity of the data and services involved. Comments: The project MUST provide Replication and Perimeter/Edge Data and Services Security. This assumes that practically all national deployments will have multiple sites that must be protected from breaches and leakages as a result of technology services deployed to distribute and consolidate data.

4.2.2.23 Social Media, Social Network and Social Engineering Threats and Prevention

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: This is a complex subject that requires not only technical intervention but extensive training for everyone involved in the processes of eGovernment. Comments: The project MUST provide protection from Social Media, Social Network and Social Engineering Threats. This is not only a technology services issue but also applies to standard operating procedures and requires extensive user education.

4.2.2.24 Centralized PAAS Management, Monitoring and OTA Automated Update

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security/Cloud Infrastructure and Hosting Description: Can be addressed as part and parcel of a modern PaaS solution such as OKD - TBD (which has over the air update capabilities along with centralized management and monitoring). Comments: The project MUST provide Centralized PAAS Management, Monitoring and OTA (over-the-air) Automated Update for infrastructure and applications components. This is to ensure that patches to emerging and common vulnerabilities are addressed in the smallest window possible and the whole architecture is not exposed through such vulnerabilities. This can and SHOULD be addressed as part and parcel of the selected PaaS infrastructure.

4.2.2.25 Digital Service Registry Security

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security/Registration Description: Can be addressed as part and parcel of a modern PaaS solution such as OKD - TBD (which has an embedded services registry) - there may be other registries required that are also impacted. There needs to be careful delineation of functionality and terminology used for registries as there are many implications in PaaS environments such as for service exposure through software defined networks etc. Comments: The project and all building blocks utilizing registries of any kind (particularly digital service registries) MUST provide Digital Service Registry Security. This means ensuring that the protocols, interfaces and connections to such centralized services are controlled in accordance with the other requirements for connections and API etc.

4.2.2.26 Surrounding Networking Software Infrastructure Security (DNS, DHCP , PXE, BootP services etc.)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security/Cloud Infrastructure and Hosting Description: Each core network service must be addressed in its own right. There is too much to discuss here but these services are critical, exposed, prone to vulnerabilities and must be secured with the highest possible standards applied. Comments: The project MUST address the general Surrounding Networking Software Infrastructure Security (DNS, DHCP , PXE, BootP services etc.) for each and every country rollout. These services are particularly vulnerable as some of them are exposed to insecure zones (especially DNS).

4.2.2.27 Cloud Provider Infrastructure Security (hardware layer, infrastructure layer, virtualisation, container and platform layer, application layer)

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security/Cloud Infrastructure and Hosting Description: Each cloud service must be addressed in its own right. There is too much to discuss here but these services are critical, exposed, prone to vulnerabilities and must be secured with the highest possible standards applied. Comments: The project MUST provide protection against common vulnerabilities in Cloud Provider Infrastructure Security (hardware layer, infrastructure layer, virtualisation, container and platform layer, application layer etc.). This is specific to each public cloud provider where utilized but a common source of threats since they involve complex suites of services that are stitched together (most often by the implementer not the cloud provider) in multiple layers to form the solution architecture.

4.2.2.28 Mobile and Wireless Networking Security/WIPS

4.2.2.29 Compressed and Encrypted Information Transmission via Messaging and Email etc. to external or internal 3rd parties along with any other potential forms of critical information leakage.

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security/Cloud Infrastructure and Hosting Description: This is principally the same as endpoint security to prevent information leakage. Comments: The project (including all building blocks MUST provide protection against private information leakage through Compressed and Encrypted Information Transmission via Messaging and Email etc. to external or internal 3rd parties along with any other potential channels for critical private information leakage.

4.2.2.30 Anti-Phishing and Anti-Spam

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: Phishing and the associated spam are two of the most common digital platform security problems and must be dealt with. A number of open source solutions exist such as OrangeAssassin, MailScanner and Apache SpamAssassin. These are commonly used by many commercial sites all around the world. Comments: The project MUST provide Anti-Phishing and Anti-Spam tooling. These are some of the most common sources of security issues and can be dealt with using open source tools such as Orange Assassin, MailScanner and SpamAssassin.

4.2.2.31 Physical Security and Access Controls to Facilities

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: Physical security is a must for all on-premise facilities and almost goes without saying. The extent to which physical security is implemented must comply with national government hosting standards in each country. Comments: The project MUST provide physical security measures for access to physical facilities.

4.2.2.32 Portable and Removable Media Controls

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: This is commonly known as endpoint security and must be dealt with comprehensively either at hardware level (by disconnection) or in software that allows policy and procedure for removable media to be controlled. Comments: The project MUST provide portable and removable media controls to protect against information leakage.

4.2.2.33 Backup Security and Backup Information Controls

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: This is a complex and diverse area to address as there will be several data repositories and databases in the deployed infrastructure including both CUI and regular non-CUI information. Backups are one of the areas that create large exposure for information loss and must be addressed consistently and thoroughly.

This must include encryption of backups and the physical security of backups as well as the policy, procedure and controls to ensure that leakage risk is minimized. Comments: The project must provide backup information controls and security to prevent information leakage and tampering etc. through the backup and recovery processes. This applies to all building blocks.

4.2.3 DETECT

4.2.3.1 Vulnerability Management and Security Automation

Organizational Risk Rating: Medium Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: Several open source and commercial tools are available to address this in terms of scanning for vulnerabilities in all layers of the solution including containers for example. The process and tools for this need to be addressed specifically depending on the technical components of the final solution architecture. Comments: The project MUST provide tools to detect, manage and automate the resolution of common vulnerabilities in all layers (applications components down to infrastructure components) before they eventuate as deployed in the solution. There are many open source scanning tool options available for this purpose. CISA defines the standards for this and refers to many of the available open source tools.

4.2.3.2 Applications Development, Deployment, DevSecOps and Container Image Security

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: This needs to be built-in to the CI/CD process to ensure that only secured images are deployed to production. Most modern PaaS offerings such as OKD - TBD are also shipped with a rudimentary suite of tools to accomplish this. Comments: The project MUST provide a secure DevSecOps process for code deployment. This applies to areas surrounding Applications Development, Deployment, DevSecOps and Container Image Security scanning (i.e. what's inside the container) before applications components are deployed.

4.2.3.3 Compliance Checking and Scanning (PCIDSS/HIPAA, CIS etc.)

Organizational Risk Rating: Medium Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low-Medium Building Block Mappings: Security Description: These are global standards for security compliance checking and several tools are available in the market to address this. Both commercial and open source options are available. Comments: The project MUST provide tooling support for Compliance Checking and Scanning (PCIDSS/HIPAA, CIS etc.). A number of open source tools and commercial off-the-shelf tools are available for this purpose. This compliance checking MUST be conducted on a regular basis for all building blocks dealing with financial, healthcare and personal data in accordance with the aforementioned PCIDSS, HIPAA and CIS standards.

4.2.3.4 Security Risk Profiling

Organizational Risk Rating: Low Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low-Medium Building Block Mappings: Security Description: Several tools are available in this space with varied ways of addressing the concerns including threat modeling Comments: The project SHOULD provide tools for Security Risk Profiling. Several such tools are available and offer assessment of security risks through techniques such as threat modeling.

4.2.3.5 Threat/Intrusion Detection and Prevention

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: Several open source tools are available to address this space admirably including for example Snort, Bro, Kismet, OSSEC and Open DLP etc. These are VERY effective, VERY mature and easily adopted. Comments: The project MUST deploy tooling for Threat/Intrusion Detection and Prevention in the infrastructure and other layers. Several such tools are available in open source (Snort, Bro, Kismet, OSSEC etc.)

4.2.3.6 Login Notifications and Alerts etc. (new device or IP etc.)

Organizational Risk Rating: Medium Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security Description: This should be managed with the basic user device profile and an alert sent via email and other channels whenever a login is made from a new endpoint, giving the user the option to lock the account. Comments: The project across all building blocks SHOULD provide Login Notifications and Alerts etc. (new device or IP etc.) where email or other notifications would be sent to recipients with warning messages when authentication is performed from a new device. This also involves keeping a registry of registered devices for each user/party/actor (albeit internal or external and the ability for them to lock their account if the authentication was achieved by an unknown party.

4.2.3.7 Open Source Intelligence (OSINT) Platforms/Tools and Processes

Essentially OSINT puts the hackers' tools into the security analysts protection arsenal. Comments: The project SHOULD provide Open Source Intelligence (OSINT) Platforms/Tools and Processes in order to perform security assessments on open source usage. This essentially incorporates the hackers tools into the protection and detection arsenal (see the evolution of Metasploit and other white hacker solutions in open source).

4.2.3.8 Information gathering and Security Data Visualization

Organizational Risk Rating: Low Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low Building Block Mappings: Security Description: This is an emerging area of value that largely comprises of the following types of visualizations but there are no comprehensive open source tools available:

Perimeter Threat

Network Flow Analysis

Firewall Visualization

IDS/IP S Signature Analysis

Vulner ability Scans

Proxy Data

User Activity

Host-based Data Analysis Comments: The project SHOULD provide tooling for Information gathering and Security Data Visualization for maintaining security observability through operations. Many different visualizations are available through various commercial tools but no comprehensive open source solution is available.

4.2.3.9 Fraud Detection and Management

4.2.4 RESPOND

4.2.4.1 Incident Response and Management - applies to attempted and successful intrusion, fraud, hacking, phishing incidents and all other forms of security incident

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: Incident Response and Management (ticketing etc.) - applies to attempted and successful intrusion, fraud, hacking, phishing incidents and all other forms of security incident Comments: The project MUST provide Incident Response and Management (ticketing etc.) - This applies to both attempted and successful intrusion, fraud, hacking, phishing incidents and all other forms of security incident. This applies across all building blocks and must be built-in to the infrastructure and processes of each building block when any incident is detected.

4.2.4.2 Security Sandbox Solution - used to test responses to potential/predicted security incidents

Organizational Risk Rating: Low Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low Building Block Mappings: Security Description: This would involve creating a sandbox environment to test and resolve security issues thus requiring a complete sandbox of all the security tools mentioned here. Comments: The project MUST provide a Security Sandbox Solution - used to test responses to potential/predicted and actual security incidents.

4.2.5 RECOVER

4.2.5.1 Critical digital infrastructure business continuity considerations (terrorism, sabotage, information warfare, natural disasters etc.) - processes and how to recover digital infrastructure.

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Low-Medium Building Block Mappings: Security Description: This is more of a planning and execution exercise and simply must be built-in to the overall deployment game plan for every single piece of software infrastructure and data infrastructure along with the processes and procedures as well as test recoveries to ensure that an adequate recovery response can be attained on demand. Comments: The project MUST deal with Critical digital infrastructure business continuity considerations (terrorism, sabotage, information warfare, natural disasters etc.) - i.e. provide the technical ability and processes required in order to recover the complete digital infrastructure. This applies to all building blocks and must also endure recovery testing on a regular basis.

4.2.5.2 Specifically Security Related Concerns surrounding BIA/DRP/BCP (disaster recovery, business continuity etc.) - how to recover to specific data versions using logging tracking and tracing information to determine the best path.

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: This is similar or the same as the concern above and simply elaborates it further. Comments: The project MUST deal with Specifically Security Related Concerns surrounding BIA/DRP/BCP (disaster recovery, business continuity etc.) - what this means is how to recover to specific data versions using logging, tracking and tracing information to determine the best recovery path. This also covers the security of the backups themselves to prevent fraud, tampering and information leakage during storage or recovery for example and MUST address the exact data security requirements stipulated throughout this document but in the context of backups.

4.2.5.3 Cloud Security Posture Management (automation of identification and remediation of risks with public cloud services)

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Low-Medium Building Block Mappings: Security Description: This is a more advanced and aggregated way of determining the overall security posture in respect to public cloud based deployments and takes into account all of the risks. There are a number of open source solutions available such as OpenCSPM (cloud security posture management). Really only applicable with deployments on public clouds but becoming essential. Comments: The project SHOULD implement Cloud Security Posture Management (automation of identification and remediation of risks with public cloud services). Open source tools such as OpenCSPM are available.

4.2.5.4 Digital Service Registry State Recovery

Organizational Risk Rating: High Target Deployment Phase: First Feasibility for Limited/Low Resource Settings: High Building Block Mappings: Security/Registry Description: It seems the concept of registry is morphing into something more generic than it was originally (which seemed to be a service registry). The state recovery for this is contingent on the technology solution that the Registration BB takes. Losing the state of this registry due to a security issue is a key risk that MUST be mitigated. Comments: The project MUST provide the ability for specific Digital Service Registry State Recovery (point-in-time). Registries are one of the most likely early targets of cyber-criminals. This applies predominantly to the Registry building block.

4.2.5.5 Controlled Unclassified Information (CUI) Registries, Repositories and Processes (i.e. marking, safeguarding, transporting, disseminating, reusing and disposing of controlled unclassified information)

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: This is all about how information is controlled throughout systems based on its secrecy/privacy classification.

4.2.5.6 Controlled Unclassified Information (CUI) domain isolation (isolation for sub-networks and security domains etc. handling CUI)

Organizational Risk Rating: High Target Deployment Phase: Second Feasibility for Limited/Low Resource Settings: Medium Building Block Mappings: Security Description: See above - requires a physically separate domain for hosting such information. Comments: This is related to the above but the project SHOULD provide Controlled Unclassified Information (CUI) domain isolation (isolation for sub-networks and security domains etc. handling CUI). \

Developed by Laurence Berry (Komo.international), Betty Mwema (Government Digital Service of the United Kingdom), Dr. P. S. Ramkumar (ITU)

9.1 Key Decision Log

A historical log of key decisions regarding this Building Block.

9.2 Future Considerations

A list of topics that may be relevant to future versions of this Specification

9.3 Links and Additional Resources

A list of links and resources relevant to the Security Specification

This document has been developed as guidance to kick-start the design and development of services that use and combine GovStack applications and Building Blocks, as well as other components while maintaining a seamless and consistent user experience.

This guidance supports teams in identifying and implementing the foundations for designing user-centered, accessible, consistent, and technically robust services. Intended to help teams align to the GovStack Design Principles and the Implementation Playbook.

2.1 Current scope

Specifications for how to implement accessible, responsive, multi-modal Building Blocks and provide a consistent service.

• Guidelines for designing interfaces (like meeting WCAG accessibility guidelines).

• Screen flows for common user journeys (like registration).

• Guidance on technical choices (like how to design for low bandwidth, high latency environments, unreliable connectivity, local storage, local persistence of data security using DOMs, etc.).

• Patterns for managing client-side validation.

2.2 Good practice UI/UX guidelines for Service Design

The guidelines act as a template checklist for assuring the quality of a service's design and delivery. Each point in the guideline has/links to additional guidance.

2.3 Service patterns

We chose to define high-level service patterns rather than anything more specific like a design system or user interface components, this is to maintain flexibility to work around each organization's needs and existing design assets and front-end frameworks.

Any Building Block must follow the security requirements that are outlined in the Cross-Cutting Requirements section of this document. In addition, specific security related functionality should be provided in any GovStack implementation. An API Gateway may be provided to manage communication between building blocks as well as any incoming requests from external systems. The API Gateway will work with the Information Mediator Building Block and provide additional controls and security while coordinating API calls between the application and various Building Blocks.

Note: The API Gateway functionality is connected to the GovStack Adaptor concept which is described in Section 6 (Onboarding Products) of the Non-Functional Requirements document

Second, some type of Identity and Access Management or Role-Based Access Control should be implemented as part of a GovStack solution, as desribed in Section 7.4 of this Security specification.

The functional requirements for both of these components are described below.

8.1 API Management and Gateway Functional Requirements

Although API Management and Gateway services are an architectural element, this section of the document also describes the detailed functional requirements for implementing API management, governance and gateway services for GovStack. Explicitly, the communications between all building blocks (BB’s) and applications shall be via open API based access.

The goal of this endeavor is to address primary security concerns centrally and create a consistent way of implementing a modern cloud-ready architecture to publish API’s to 3rd parties (both internal and external), govern and manage the access to API’s both internally and externally by policy and create centralized and secure point of access to each and every API endpoint exposed through GovStack. These functional requirements do not define specific APIs (API’s themselves are implemented by other building blocks) - these functional requirements only define the functionality that must be implemented within the bounds of the security building block and how it needs to be applied to other building blocks.

8.1.1 Multiple API Gateway (REQUIRED)

The ability to implement segregated gateways for both internal and external API traffic. This means that the internal API driven integration traffic and the external API access traffic is to be segregated into separate gateway infrastructure components and access controlled by networks and network access policy.

8.1.2 Standards Based Identity and Access (REQUIRED)

The ability to implement standardized authentication, authorization and encryption protocols including federated identity (OAuth2, OpenID Connect, SAML2, SSO, SSL, TLS etc.). These standards MUST be supported and incorporated into any chosen API Management product out-of-the-box for controlling access to API interfaces.

Note that the native API interfaces for each building block's components may be implemented in clear text with no authentication and/or encryption etc. so long as the access to these interfaces is firewalled by network and network policy such that it is ONLY accessible through the API Gateway. This is intended to simplify, standardize and expedite API development, deployment and management.

Note that the APi interface specifications for the APi gateway and API management services are based on open standards based identity and access which is in turn based on OpenAPI 3.0. The following link describes how OAuth2 is used in OpenAPI 3.0 standards based identity and access: https://swagger.io/docs/specification/authentication/oauth2/. It is this style of standards based identity and access that is required to be supported, Note that additional API interfaces may be exposed by the API Management and Gateway solution but they would predominantly be targeted for incorporation into the DevOps CI/CD tool chain not exposed to other BBs.

8.1.3 Identity Store Plugins (REQUIRED)

The ability to utilize separate identity stores as repositories for identity and perform proxied authentication to such repositories (for example LDAP) using multiple credentials including digital identity certificates.

8.1.4 API Protection Features (REQUIRED)

The ability to support many security and protection features such as Standard API keys, App-ID key pair, IP address filtering, Referrer domain filtering, Message encryption, Rule-based routing, Payload security, Channel security, Defense against common XML and JSON attacks, Low- to no-code security configuration, PCI compliance.

Note that this is not an exhaustive list and additional policy protection features may strengthen the value of any given solution.

8.1.5 Centralized API Policy Based Access (REQUIRED)

The ability to implement policy based access management for API endpoints. The policy MUST be able to be implemented centrally then applied across multiple gateways and all API endpoints.

8.1.6 API Endpoint Transformation (REQUIRED)

The ability to support multiple standards for proxying endpoints and exposing them as standard OpenAPI endpoints (see Ref 1) including transformations such as XML ↔ JSON and SOAP ↔ REST

Note that this is not an exhaustive list of the required transformations and that additional transformations may reinforce the strength of a solution’s flexibility and adaptability.

8.1.7 Alternative API Protocols (REQUIRED)

The ability to support multiple common protocols such as JMS, WS, MQTT.

Note that this is not an exhaustive list and that additional alternative protocols supported may strengthen the value of the proposed solution.

8.1.8 API Versioning and Lifecycle (REQUIRED)

The ability to support multiple API versions and control multiple API versions and API lifecycle management.

Note that there are many potential features available to strengthen the solution proposition such as version dependency management and deployment rollback etc.

8.1.9 API Call Traffic Shaping (RECOMMENDED)

The ability to implement traffic transformation and traffic shaping. This is typically implemented as single/dual rate, private (per node) and shared (by multiple nodes) shapers.

Note that additional traffic shaping capabilities may strengthen the solution proposition.

8.1.10 API Call Rate Limiting (REQUIRED)

The ability to implement rate limiting for API calls on an API-by-API basis. This limits the rate at which API’s can be called by a consumer (for example 100/second etc.) and usually has many flexible options and caters for policy driven rate limits based on busy times etc. Principally it comes down to the offered SLA.

Support for complex SLA construction may strengthen the solution proposition.

8.1.11 API Call Quotas (RECOMMENDED)

The ability to implement quotas for API calls from specific clients (daily, weekly, monthly etc.). This restricts the number of API calls a client can make and also often includes flexible options so that a complex SLA can be constructed.

Support for complex SLA construction may strengthen the solution proposition.

8.1.12 API Call Logging, Monitoring and Alerts (REQUIRED)

The ability to implement logging and monitoring of API calls with reporting and administrative alerts. Typically extensive functionality with multiple logging levels is implemented.

Support for flexible levels of logging (for example debug, trace etc.) may strengthen the solution proposition.

8.1.13 API Call Analytics (RECOMMENDED)

The ability to implement advanced analytics with out-of-the-box charts and reporting on demand along with the ability to trigger alerts based on analytics.

The strength, flexibility, feature set and appeal of the analytics and charting capabilities may strengthen the solution proposition. Note that this can optionally be implemented as a separate tooling layer perhaps using tools such as Prometheus and Grafana etc.

8.1.14 API Virtualization (RECOMMENDED)

The ability to implement virtualized API endpoints. API virtualization is the process of using a tool that creates a virtual copy of your API, which mirrors all of the specifications of your production API, and using this virtual copy in place of your production API for testing.

Note that this is NOT API mocking but provides an actual endpoint for solution testing to proceed unhindered.

8.1.15 API Developer Portal (RECOMMENDED)

The ability to publish API specifications through a developer portal using open standards. Includes features such as portal availability across deployment types (on-premise, cloud, etc.), interactive API documentation, developer metrics, developer portal templates, portal customization (HTML, CSS etc.), ability to withdraw developer keys, either temporarily or permanently.

Note that advanced developer portal features may strengthen the value of the solution proposition.

8.1.16 Flexibility in API Deployment Architectures (REQUIRED)

The ability to support a diverse array of deployment architectures including standalone, on-premise cloud and public cloud models including the ability to support a fully integrated microservices architecture based on containers. The architecture should also allow for the separation of key components and interfaces for meeting complex network security needs.

Note that the more flexible the deployment architectures are, the stronger the solution proposition.

8.1.17 Advanced DevOps Artifact Deployment (RECOMMENDED)

The ability to support advanced DevOps deployment techniques such as “canary deployment”, “blue-green deployment” and “AB testing”.

Additional advanced deployment scenarios and innovations will strengthen the value proposition of the proposed solution.

8.1.18 File Storage Integration (RECOMMENDED)

The ability to implement file storage platform integration such as S3 etc. - not exhaustive.

Note that flexibility in the support for storage integration across additional file storage standards will strengthen the value of the solution proposition.

8.1.19 API Monetization (OPTIONAL)

The ability to monetize API calls by specific 3rd parties or partners for the purposes of simply raising capital or creating partnership incentives through 3rd party portals. Features such as billing support, support for multiple models of revenue generation, low- to no-code monetization configuration, third-party payment system integration, prepay and/or postpay invoicing, multi-currency support and tax compliance are negotiable.

Note that the more advanced the monetization features are, the higher the solution value proposition is.

8.1.20 High Availability (REQUIRED)

The solution provided and any associated components MUST be highly available and utilize clustering technology in order to provide a minimum of 24x7x365 service with 99.99% availability (AKA 4 9’s).

8.1.21 Open Source Based (RECOMMENDED)

The offered solution MUST be based fully on open source components. The vendor may offer subscriptions for support so long as the offered solution does not require those subscriptions in order to deliver the core functionality specified in this document.

8.2. Identity and Access Management (IAM) Suite Functional Requirements

8.2.1 Identity Lifecycle Management

The following diagram defines the basic lifecycle required for managing identities:

What is required is a flexible and comprehensive user lifecycle management solution which provides the following generalized features and functions:

8.2.1 User Administration Tools (REQUIRED)

These are required so that administrative users and/or help desk users can centrally manage all user profiles and records. These features include:

• Unlock accounts and reset passwords when needed

• Changing the user status

• Session management – visibility to see active users and to kill their session if needed

• Workflow - monitor all workflows and terminate them if necessary

• Review audit logs for authentication, access and changes to identity records.

• Manage user profile attributes including credentials etc.

• Manage user access rights for resources such as documents and APIs.

8.2.2 Multi-Source Identity Integration (REQUIRED)

Integration with multiple source identity systems (such as the Identity BB, databases and LDAP) to automatically initiate provisioning/deprovisioning activities related to enrollment, policy changes and un-enrollment processes.

8.2.3 Multi-Source Identity Synchronization (REQUIRED)

Multi-source synchronization of user identity data. This allows the system to integrate and synchronize with an authoritative source such as the national ID, social security system or perhaps more likely the Identity BB via an API/plugin approach. This is required for both initial load of identities and for ongoing provisioning, re-provisioning and deprovisioning etc..

The synchronization must determine which systems a user should be provisioned to/de-provisioned from, which permissions should be set or revoked for the applications that a person is entitled to and whether or not provisioning should be automatic or if an additional workflow should be triggered for human or other automated processing.

8.2.4 Identity Reconciliation (REQUIRED)

Automatic user identity record reconciliation. This is where synchronization is used to detect changes in the source system identity data and reconciliation is used to detect, compare and resolve the changes.

For example a user record has been added to a target system manually instead of using IAM.In this case reconciliation can be configured to either:

1. Add the user to the IAM system

2. Remove the user from the target system or;

3. Do nothing but flag the anomaly to an administrator

8.2.5 Self Service Portal and Workflow (REQUIRED)

A customizable, workflow driven, self-service user interface portal to enable administrators to create and manage policies, users and the various artefacts. Must support approval workflows to multiple stakeholders.

8.2.6 Advanced Password Management (REQUIRED)

The advanced password management capabilities must include the following:

• Self-service Password Reset (SSPR)

• Administrative change password

• Password synchronization with directory and other resources.

• Must work across both cloud and on-premise applications lowered costs and improved security for hybrid cloud deployments

• Ability to enforce strong password policies

• Self-service password which allows users to reset their own password without going to the help desk. Reset is via a combination of challenge/response questions, one-time link via registered email, one-time token via SMS or mobile device messaging and one-time PIN.

• Password aging with password change reminders sent via email and potentially mobile messaging.

• Password change synchronization across all target systems.

8.2.7 User Access Request Management (REQUIRED)

Whilst provisioning processes can be triggered through the automated user lifecycle management functionality, the IAM solution must also provide a self-service feature through the portal via which end-users can request access. This access-request functionality is provided through a shopping cart and service catalog design where the user has access to select the services to which they would like to request access. Applications and application-specific entitlements such as membership to an LDAP group or a role on a public cloud provider such as AWS must be supported as a part of the access grant process.

The access request feature must also include the optional selection of a “Profile Role” capability – which is a role defined for a job/position that can grant access to a number of applications that are needed for a particular job role (otherwise known as delegation).

The access request/approval workflows provided must support:

• Multiple approvers – Must be able to define as many approval steps needed and select common targets such as a supervisor, object owner or admin, and group of approvers.

• Service Level Agreements (SLA) - Must ensure that tasks are completed in a timely manner so if they are not, then they can be escalated to the appropriate person after expiry time.

The access request approval functionality must also support basic “delegated approval” and “out of office” functionality so that there are no barriers to self service access requests when the usual approvers are not available.

8.2.8 REST API (REQUIRED)

A REST (representational state transfer) based API for external integration of the provisioning and deprovisioning of users etc.. is required. It must support the same OpenAPI standards defined by the Architecture Blueprint and Functional Requirements (see Ref 1). An example of such a REST API is provided with the OpenIAM suite specification here: https://www.openiam.com/products/identity-governance/features/api/. This is intended as an example of the API style that is expected in such a suite. This is not definitive and may vary based on the proposed IAM suite.

8.2.9 Orphan Management (REQUIRED)

Organizations which are not actively using an IAM platform often have orphaned user records in their business applications. These are those records which are the result of users being given access and not having that access revoked when a person is unenrolled from a service.

Orphan management functionality consolidates all the orphaned records and provides administrators with tools to either clean up these records or link them to the correct user.

8.2.10 Access Certification (REQUIRED)

Regulatory requirements, such as GDPR, HIPPA and SOX combined with an increased focus on security are causing both public and private organizations to implement access certification policies. Scheduled access certification campaigns aid in complying with these regulatory mandates as well as improve security by guarding against the access violations which lead to security breaches.

However, when performed manually, these activities can be error prone and very time consuming for most mid to large organizations. The lack of consistency resulting from manual processes results in failed compliance audits and threats resulting from unauthorized access can slip undetected. The IAM solution must provide the ability to automate the access certification process which addresses the challenges found when performing these processes manually.

The following types of certifications must be supported by the IAM solution:

• User Access Certification

• Application Access Certification

• Group Access Certification

These campaigns can be scheduled and run at regular intervals or they can be run on demand. The Access Certification functionality in the IAM solution must provide organizations with the following capabilities:

• Human Friendly Reviews: End-users (reviewers) using the IAM solution access certification functionality must be able to perform their activities in a familiar self-service user interface. Reviewers must be able to review all the historical access in a central location as well as use tools to compare access (date, time, service etc.) between individuals.

• Closed Loop Revocations: During the certification process, reviewers must be able to revoke accounts and entitlements with a simple one-click mechanism. The closed-loop validation mechanism will then ensure that revoked access has been deprovisioned from the target applications.

• Support for Cloud, On-Premise and Hybrid Cloud: An increasing number of organizations today have hybrid environments where applications are deployed both on-premise and in the cloud. The IAM solution must provide a central identity governance platform such that the same consistent certification programs can be undertaken irrespective of the applications and infrastructure location.

• Enrollment (Joiner)

• Role Change (Mover, Additional Services)

• Unenrollment (Leaver)

• Status change

• Access request (Additional Services)

• Group creation (with group policy)

• Self-registration (with a customized external workflow to integrate with the Identity BB)

• Access Certification

The following predefined workflow templates are required to be provided:

• Multiple approvers

• Service Level Agreements (SLAs) to ensure timely completion (with automatic delegation and temporary changes in the new approvers access rights to enable time-sensitive approval)

Each of these workflows must support:

The IAM solution identity governance feature set must provide the creation of workflows to support complex processing, integration and approval steps. While custom workflows must be defined, the IAM solution must also provide default out-of-the-box workflow templates for common operations to simplify the configuration effort.

8.2.11 Workflow Creation (REQUIRED)

The IAM solution identity governance feature set must provide the creation of workflows to support complex processing, integration and approval steps. While custom workflows must be defined, the IAM solution must also provide default out-of-the-box workflow templates for common operations to simplify the configuration effort.

Each of these workflows must support:

• Multiple approvers

• Service Level Agreements (SLAs) to ensure timely completion (with automatic delegation and temporary changes in the new approvers access rights to enable time-sensitive approval)

The following predefined workflow templates are required to be provided:

• Enrollment (Joiner)

• Role Change (Mover, Additional Services)

• Unenrollment (Leaver)

• Status change

• Access request (Additional Services)

• Group creation (with group policy)

• Self-registration (with a customized external workflow to integrate with the Identity BB)

• Access Certification

8.2.12 Custom Workflows (RECOMMENDED)

Whilst the IAM solution must provide the above workflow templates, it also must include a BPMN compliant workflow engine that can be used to create new custom workflows. A graphical process designer such as the BPMN designer plugin such as one of the many available for the Eclipse IDE or similar must be included to simplify the effort required to create new custom workflows.

8.2.13 Audit and Compliance (REQUIRED)

Facilitating compliance with regulatory requirements or internal security policies is one of the principal drivers for Identity Governance. The IAM solution must provide tools to help organizations meet compliance mandates.

Organizations deploying the IAM solution as a part of GovStack are required to automate a variety of operations that sometimes utilize workflow-based approval steps.

Detailed audit logs must be associated with each of these operations so that organizations can answer the following fundamental questions:

• What access rights does a user currently have?

• When were they granted these rights?

• How or why were they granted these rights and by whom were they granted?

In addition to access information, the IAM audit logs must also track details related to authentications, password changes, life cycle status changes, system configuration changes etc.. Using the information provided by these logs, combined with the out of the box reports, and self-service tools, organizations must be able to achieve the following:

• Provide the auditors with clear evidence of compliance or otherwise.

• The ability to proactively review, detect and revoke inappropriate access from any user.

• The ability to review all access rights before granting any additional access rights.

• A centralized review and certification of applications/systems access rights across both on-premise and cloud.

8.2.14 Connectors (RECOMMENDED)

The IAM solution should provide a large range of connectors for both source and target applications out-of-the-box, The reason for this is that GovStack will be deployed in more than one country and in unknown applications environments and must be able to be integrated with many different common enterprise information systems and services both on premise and in the cloud in a simple and cost effective manner… for example:

• Microsoft (Active Directory, PowerShell, Windows, Azure AD, Exchange, SQL Server, Office 365, Azure DevOps, Dynamics365)

• Oracle (eBusiness Suite (EBS), IDCS, database)

• ERP/HR Systems (Oracle, SAP, ADP, Workday)

• Public Cloud (Amazon Web Services, Azure, Google Cloud)

• Infrastructure (Database/JDBC, GIT, LDAP (OpenLDAP, eDirectory, Active Directory, ApacheDS etc.), Linux (RHEL, CentOS, Ubuntu), REST web services, SCIM 2, scripts)

• Others (Google Gsuite, Salesforce, SAP Hana, Slack (SCIM), Tableau… not an exhaustive list)

8.2.15 Access Management (REQUIRED)

Access management is an integral part of the required IAM solution. The Access Manager must provide a scalable, secure and consistent solution to implement policy based access for applications in hybrid cloud environments for both internal (employees), citizens (external) and 3rd parties (external) alike.

The Access Manager must provide the following tools to enable these objectives:

• Web SSO. Web single-sign-on must be provided with support for SAML 2, oAuth 2, OpenIDConnect, OIDC, and a proxy to allow SSO to legacy applications. This enables web based applications to be easily configured for SSO without modification.

• Adaptive Authentication. An adaptive authentication system as follows must be provided with the following features:

  • Password-based authentication

  • Certificate-based authentication

  • MFA-SMS/E-mail/Mobile app-based OTP

  • Adaptive Authentication builds on these options to provide a robust framework where users can build rich authentication workflows using a browser-based drag-and-drop interface.

  • The flows can take into account a broad range of risk factors including device, context, user choices, geolocation, profile attributes, user behavior and foundational identity systems.

  • This allows the implementation of a solution which offers a significantly higher level of security while providing an improved end-user experience in comparison to traditional options.

• Multi Factor Authentication (MFA). While the IAM solution framework must allow the use of third party MFA products, it should also provide its own MFA solution which is pre-integrated and ready to use. The following MFA options should be provided out-of-the-box:

  • SMS-based OTP

  • E-mail-based OTP

  • Mobile app (iOS or Android) OTP plus push notification support

• Social Sign-on (as opposed to single-sign-on). The Access Manager should allow social sign-on from social identity providers such as Google, Facebook and LinkedIn. Social registration significantly reduces the registration effort by allowing select attributes to be dynamically transferred from the social provider. This may or may not be used in practice but is a desired feature.

8.2.16 RBAC Based Authorization (REQUIRED)

The IAM solution must provide a flexible RBAC-based authorization model to enforce security into applications through the Access Manager. The RBAC model must support inheritance as well as direct entitlements and provide the flexibility needed to implement complex real world requirements. The authorization service must be able to be used in conjunction with oAuth2 and the Access Gateway to enforce the authorization rules.

8.2.17 Session Management (REQUIRED)

The IAM solution must provide session management for issues like session timeout to reduce the exposure created by long running sessions. This includes API’s to extend expiring tokens etc. for application and user convenience.

8.2.18 Device Registration (REQUIRED)

The IAM solution must provide device registration such that only registered devices can be used to access services by policy.

8.2.19 Fine Grained Audit Logging (REQUIRED)

The IAM solution must provide fine grained audit logging by the Access Manager so that the explicit date, time, user and service access is logged.

8.2.20 Access Gateway (REQUIRED)

An access gateway is required in order to provide protected proxy gateway access to the web through reverse and front side web infrastructures such as Apache and Nginx web servers. This must provide the following functionality:

• SSO to legacy applications

• Session management

• Protection of APIs and application URLs by enforcing authentication and authorization rules unless a 3rd party API Management and Gateway suite is used in which case the access gateway must be configurable to utilize the 3rd party API Gateway.

8.2.21 Legacy SOA Security Features (REQUIRED)

The IAM suite should be able to implement a pure legacy SOA approach. A legacy SOA API with all required operations should be available to facilitate integrations with legacy SOAP/SOA systems. The IAM solution should provide SOA federation for controlling access to services in a legacy SOA environment using SAML, SAML 2 and WS-Security. The IAM solution must be able to enforce policies throughout SOA based services. RBAC and XACML support must be provided to allow the IAM solution to implement a flexible security model that supports the following:

• Distributed services (vs monolithic applications)

• Services distributed across organizational boundaries

• Service Interoperability

• Integration of disparate legacy SOA protocols

8.2.22 Web Access Management (REQUIRED)

The Access Gateway must be able to provide coarse-grained authorization when protecting web applications in totality. Requests must be routed through a proxy, which applies authorization rules, and forwards the request to the underlying servers, providing the application.

The model must be simple to deploy and easy to maintain. User identity must be checked and propagated through HTML header injections, HTTP query strings or HTTPS authentication headers to applications hidden behind a proxy server for the purposes of openness and compatibility. The native URL of these applications must be hidden from the public view (i.e. it is only exposed as a service name in a secure manner).

8.2.23 Single Sign On (SSO) (REQUIRED)

Each partner application, as well as internal applications and building blocks, may have their own set of security credentials and various authentication methods. Such applications may move in and out of security domains.

The user experience suffers when many login credentials must be remembered. Therefore the IAM solution must provide SSO features that allow users login once and roam unchallenged through a security realm to which they have been granted access.

This reduces the burden of many passwords and eliminates the need to individually login to each application. Users must be able to login once, and roam freely across secured domains without being challenged again. Participating security domains must never be required to give up their own credentials.

The ability to hold multiple identities, each with their own roles, permissions, access-levels and entitlements across multiple domains is required and allows for a wide network of co-operating domains to communicate seamlessly.

Authenticated subjects must be able to access restricted resources requiring multiple logins and credentials without the need to login at each domain. The IAM solutions access manager solution must not be based on a proprietary cookie. It should be based on SAML 2, which is a well-accepted industry standard for SSO.

Using SAML2 allows the IAM solutions access manager to not only provide SSO capability at the web application tier, but also across other layers such as Web Services in a completely unified way. SSO must also allow the access manager to integrate easily with existing authentication technologies that are deployed in any organization.

8.2.24 Federation (REQUIRED)

When GovStack is deployed it will need to be deployed with partners, suppliers and other organizations. For them to collaborate effectively, identity information needs to be propagated. The IAM solution must be able to manage the processes for federating users when a partner site comes on board or leaves. Federation capabilities must be provided by the IAM access manager solution. New cost recovery streams may be generated for GovStack users through enablement of trusted partnerships where authentication and authorization is carried out over federated business networks.

Federation refers to interoperation between entities in different security domains, either in different organizations, or in different tiers in the same organization.

A trust relationship must exist between the involved entities to federate identity and enable authentication across realms. Each domain may rely on different technologies and mechanisms to authenticate and authorize.

Federation enables loose coupling at the IDM level separating the way each organization/application/module/building block does its own security implementation while they adopt a common mechanism to propagate identity.

8.2.25 Security Token Service (STS) (REQUIRED)

STS is a system role defined by the WS-Trust specification. A Web Service Client interacts with the STS to request a security token for use in SOAP messages. In addition, a Web Service Provider interacts with an STS to validate security tokens that arrive in a SOAP message. An STS arbitrates between different security token formats.

The token transformation capability defined in WS-Trust provides a standards-based solution to bridge incompatible federation deployments or web services applications. Web service providers should not be required to support multiple authentication mechanisms even though they have to work with different web service clients.

The SAML standard is well recognized and the IAM solution must provide a Security Token Service that can validate SAML and SAML2 tokens to bridge different web services.

8.2.26 Role and Attribute Based Access Control (RBAC/ABAC) (REQUIRED)

The IAM solutions Access Manager must manage Groups, Roles, Permissions and Resources supporting both RBAC and ABAC. Groups are generally used to model organizational structure whereas Roles are used to model a person’s function within the enterprise. In RBAC, a subject is given one or more roles depending on the subject’s job.

Access is determined by the subject’s role. In ABAC (Attribute Based Access Control), access is determined by the attributes of the subject (person or entity), attributes of the resource being accessed, environmental attributes and the desired action attribute. ABAC is implemented based on the XACML specification with:

• Coarse-grained access control - based on subject, role and permissions

• Ease of administration - roles created for job functions

• A subject that must be assigned to a role and execute actions that are authorized for the role

• Assigned permissions for job functions based on operations rather than to resource objects

• Enablement of the creation of:

  • Relationships between Users, Groups, Roles, Resources

  • Creation and enforcement of policies

Developing an access control strategy based on RBAC provides a clean and flexible model that is easy to maintain over a long period of time.

Policies may be associated with a person’s role. For example, someone in a medical advisor role may be permitted to access applications pertinent to his or her role, but not permitted to access applications related to someone in a doctor's role.

8.3 Service APIs

This section describes external APIs that must be implemented by the building block. Additional APIs may be implemented by the building block (all APIs must adhere to the standards and protocols defined), but the listed APIs define a minimal set that must be provided by any implementation.

All APIs will be defined using the OpenAPI (Swagger) standard. The API definitions will be hosted outside of this document. This section may provide a brief description of required APIs. This section will primarily contain links to the GitHub repository for OpenAPI definition (yaml) files as well as to a website hosted by GovStack that provides a live API documentation portal. The basic assumption here is that the IAM suite will be acquired and not built. The suite MUST supply an appropriate API with documented endpoints.

IAM Suite API: An example of such a REST API is provided with the OpenIAM suite specification here: https://www.openiam.com/products/identity-governance/features/api/. This is intended as an example of the API style that is expected in such a suite. This is not definitive and may vary based on the proposed IAM suite. The detailed API documentation for OpenIAM including interface specifications can be found here: https://docs.openiam.com/docs-4.1.14/html/API/index.htm

OAuth2 API: The following link describes how OAuth2 is used in OpenAPI 3.0 standards based identity and access: https://swagger.io/docs/specification/authentication/oauth2/.

SCEP API: A description of the OpenXPKI enrollment workflow and API can be found here: https://openxpki.readthedocs.io/en/latest/reference/configuration/workflows/enroll.html. This is an example of how an API for enrolment with its associated workflow should be implemented within the Certificate Authority Server.

LDAP API: A description of the standard REST LDAP API provided by the open source 389 Directory Server here: https://directory.fedoraproject.org/docs/389ds/design/ldap-rest-api.html#ldap-rest-api . This is an example of how an open API for credential storage and retrieval using LDAP should be implemented.

8.4 Workflows

A workflow provides a detailed view of how this building block will interact with other building blocks to support common use cases.

This section lists workflows that this building block must support. Other workflows may be implemented in addition to those listed.

No specific workflow definitions are required for this building block as they will be inherited by the tools/products chosen to address each security issue/concern and fundamentally deal with the other building blocks API’s in a cross-cutting manner as in the case of API Management.

Other components of the Security BB such as the IAM Suite will also provide their own workflow tools but the details of the actual workflow need to be designed once more is known. An example of the type of default workflow provided for an IAM suite would be the basic workflow for provisioning new accounts which can be leveraged by the other BBs. This is typically a basic workflow built in a tool that can be customized to meet specific provisioning needs (perhaps with multiple administrative roles and connections to multiple external systems and modules etc.) . The following link describes an example the basic workflow for provisioning provided by Open IAM (one of the alternatives) https://www.openiam.com/products/identity-governance/features/provisioning/

Note that each building block is responsible for the defining base configurations and workflows required to be created in the IAM system that enable identity and access to be provisioned. Essentially the IAM system needs to be augmented with adapters to enable identity and access to be provisioned to target systems and resources in the way that the target applications implement their own identity and access. Alternatively where applications are built from the ground up they can leverage the IAM suite sAPI services to implement authentication and access.

These specific workflows and adapters can be defined at the detailed design stage and communicated to the Security WG for implementation in the IAM solution. It must be noted that the security WG is NOT responsible for determining the identity and access policy and the details of access for each role for example. The following need to be identified by each building block and communicated to the Security WG for implementation in the IAM suite configuration build:

• Resource Types: for example files, services, API’s, applications, modules to be protected by IAM.

• Resources: The definitions of the actual resources and their type provided by and required by each BB that are to be secured through IAM. This must include the target system or component that hosts these resources so that the correct provisioning adapter can be configured for that resource. Note that where the BB or resource has its own identity and access scheme an adapter can be written using the IAM suite API.

• Roles: the roles of users of each system that include the required resource access for that role in terms of the Resources. Each BB must account for the access they require to be provisioned to other services as a part of their process scope. In the case of provisioning a new account there is a need for a broader workflow process that is outside the scope of the Security BB which incorporates the Identity and Registration BB. For example a Doctor role may require verification and validation of certain aspects of identity prior to provisioning access to a specific service. A basic set of sequence diagrams is provided below to reinforce the understanding of what is required.

• Approval Workflows: workflow for the approval of the various identity and access requests (complete with approval roles etc).

8.4.1 Identity and Access Sequences

The following sequence diagrams depict the basic means by which authentication and access control shall be implemented across building blocks. Note that by definition an account with no access can be created by any user. via self-registration. Self-registration using basic phone/email as well as strong self registration using foundational ID are to be supported . A sequence detailing technical authentication is also included below along with sequences defining the remaining aspects of the identity lifecycle (such as provisioning and deprovisioning of access) to be supported by the IAM suite and how they will be leveraged by all building blocks. Such workflows can be articulated in full during the detailed design phase:

8.4.1.1 User authentication and authorization

This assumes the user already has an account. Authentication credentials are username or phone number and password.

The auth token could be signed with an expiration (JWT) which might allow the BB to perform the validation themselves. Additionally, if the token contains roles and/or a user ID and isn’t expired the BB could potentially rely on those.

8.4.1.2 Self-registration via phone number or email

8.4.1.3 Self-registration via foundational ID

For a specification, see the Identity and Verification Building Block Specification.

Note that role creation (e.g. farmers, doctors) is handled by the IAM solution, via either an administration UI or an API. Building blocks can create roles via the API to provision new roles.

It’s assumed the user clicked a link to access the service in the Building block UI.

The users are authorized with a valid access token for their email or phone number.

8.4.1.4 Self-deprovisioning via foundational ID

This flow assumes the user has an account and is currently authenticated.

8.4.1.5 Deprovisioning via government official

This flow assumes the user has an account and is currently authenticated.

8.4.2 Standards

The workflows MUST adhere to all standards defined in this document as well as in the GovStack architecture document (link to appropriate section in architecture document)

No specific standard workflows are required in the context of the security building block. All workflows involving identity and access for example are the responsibility of each building block working group and to be defined during detailed design. Such workflows can and should be implemented using the workflow engine built into the IAM suite and perhaps extended from or to a meta-workflow defined in the context of another BB.

8.4.3 Interaction with Other Building Blocks

The security building block predominantly deals with the cross-cutting security concerns of each other building block and defines the basis for the implementation of solutions to address these concerns. The only interaction required is for API Management and Gateway services. These interactions are depicted and documented in Architecture Blueprint and Functional Requirements (see Ref 1).

8.4.4 Example Sequence Diagrams for API Gateway Services

The sequence diagrams below depict examples of how a building block might interact with the API Management and Gateway solution. This is only relevant for the API Management and Gateway services in the context of the security building block. A higher level sequence diagram depicting API interactions for building blocks is depicted and documented in Architecture Blueprint and Functional Requirements (see Ref 1).

Note that all of the requirements stipulated in this document and its references are reciprocal in that they also apply to components such as the API Management and Gateway services implemented by the security building block. For example the API Management and Gateway services deployed by this building block MUST also address their own intrusion prevention and detection needs referencing the solution requirements defined by this document.

The requirements stipulated in this document are themselves cross-cutting in that they apply to all building blocks and MUST be cross-referenced by the Building Block Definitions for each building block in the Cross-cutting requirements section.

Having these cross-cutting requirements defined centrally in this document and its references removes the issues of inconsistent, insufficient, costly and repetitive security implementation across all building blocks.

The cross-cutting requirements described in this document, its references and this section are an extension of the high level cross-cutting requirements defined in the architecture specification document and intended to specifically define the security requirements for the whole GovStack architecture in all layers.

This section describes the additional cross-cutting requirements that apply to the security building block as well as cross-cutting security requirements for ALL other building blocks. Note that cross-cutting requirements defined here use the same language (MUST or SHOULD) as specified in the architecture blueprint document (see Ref 1).

5.1 Privacy

Personal data MUST be kept private and never shared with any parties, except where specific authorization has been granted. This also applies to all acquired security components as they will often be logging personal data along with the transactional records. That logging data must also be considered private. Where CUI (Controlled Unclassified Information) is dealt with, the NIST 800-171 Rev 2 standard shall be applied (see Ref 3)

5.2 Security Requirements

Must refer reciprocally to this document and its references.

Security requirement is a condition over the phenomenon of the environment that we wish to make true by installing the system in order to mitigate risks. A requirement defining what level of security is expected from the system with respect to some type of threat or malicious attack.

5.5 Digital ID/Certificate Functional Requirements

5.6 Certificate Authority Functional Requirements

5.7 Credential Storage (i.e. LDAP) Functional Requirements

5.8 Time Sensitive Credential (i.e. OTP) Functional Requirements

5.9 Network Scanning and Vulnerability Management Requirements

5.10 Virus, Ransomware, Malware, Spam, Phishing Protection Requirements\

5.11 Denial of Service Attack Prevention Requirements

5.12 Applications Development Vulnerability Prevention Requirements

5.13 Infrastructure Vulnerability Remediation Requirements

5.14 Data Loss and Leakage Prevention Requirements

5.15 Data Encryption at Rest and In Transit Requirements

5.16 Social Network, Media and Engineering Threat Management Requirements

5.17 Cloud Security Posture Management Requirements

5.19 Vulnerability Management and Security Automation Requirements

5.20 Security Risk Profiling and Management Requirements

See the section of this document dealing with OSINT tools

5.21 Intrusion Prevention and Detection Requirements

5.22 Open Source Intelligence Platform (OSINT) Requirements

5.23 Fraud Prevention, Detection and Management Requirements

5.24 Security Incident Response and Management Requirements

5.25 Security Testing and Sandbox Requirements

5.26 Critical Digital Infrastructure Business Continuity Requirements

5.27 Data Structures

5.27.1 Resource Model

The resource model shows the relationship between data objects that are used by this Building Block. The following resource model depicts the basic elements of identity and access management (IAM) solutions required organized into domains:

5.27.2 Data Elements

The data elements provide detail for the resource model defined above. This section will list the core/required fields for each resource. Note that the data elements can be extended for a particular use case, but they must always contain at least the fields defined here. Information about data elements will include:

• Name

• Description

• Data Type

• Required/Optional flag

• Link to applicable standard(s)

• Notes

5.27.3 Example REST Authentication API

The following is a minimal example of how OpenIAM implements REST based authentication using its REST API:

(Note: The APIs will need to include appropriate request and response version numbers, for example, see https://docs.google.com/document/d/12b696fHlOAAHygFF5-XxUJkFyFjMIV99VDKZTXnnAkg/edit#heading=h.h9ypjkyetr1i)

URL

/idp/rest/api/v1/auth/public/login

Method

POST

Request Parameters

• login: user login (optional)

• password: user password (optional)

• postbackURL: redirectURL after success login (optional)

Headers

Content-Type:application/x-www-form-urlencoded

cURL Example

curl 'http://127.0.0.1:8080/idp/rest/api/auth/public/login' -X POST --data 'login=admin&password=pass123456'

Success Response Example

{
  "primaryKey": null,
  "status": 200,
  "errorList": null,
  "redirectURL": "/selfservice",
  "successToken": null,
  "successMessage": null,
  "contextValues": null,
  "possibleErrors": null,
  "passwordExpired": false,
  "userId": "3000",
  "unlockURL": null,
  "tokenInfo": {
    "authToken": "+Y9NkOrjOWn0BehKr6Cg1F7KcFIiY=",
    "timeToLiveSeconds": -1
  },
  "error": false
}

Error Response Example

{
  "primaryKey": null,
  "status": 500,
  "errorList": [
    {
      "i18nError": null,
      "error": "INVALID_LOGIN",
      "validationError": null,
      "params": null,
      "message": "Invalid Login and/or Password"
    }
  ],
  "redirectURL": null,
  "successToken": null,
  "successMessage": null,
  "contextValues": null,
  "possibleErrors": null,
  "passwordExpired": false,
  "userId": null,
  "unlockURL": null,
  "tokenInfo": null,
  "error": true
}

5.27.4 Example OAuth2 Authentication API

The following is a minimal example of how OpenIAM implements authentication with OAuth2 by requesting an OAuth2 token:

URL

/idp/oauth2/token

Method

POST

Request Parameters

• client_secret: Value of the client secret from OAuth client configuration page

• client_id: Value of the client ID from OAuth client configuration page

• grant_type: Type of grant flow

• username: Login of requester

• password: Password of requester

Headers

Content-Type:application/x-www-form-urlencoded

cURL Example

curl -v -XPOST --data 
'client_secret=AAAAA&client_id=BBBBB&grant_type=password&username=DDDD&password=EEEE' 'http://127.0.0.1:8080/idp/oauth2/token'
Success Response Example
{
"access_token": "ffj9Ub4lP-2_W4kXAXJ9MsleMxdDi9ALo0JqQw.3hV4driKa4IWXOSJ42PEQadFpN2FnpRruFLWD3",
"token_type": "Bearer",
"expires_in": 1320,
"refresh_token": "3nlth7DevrnjjpebATKkYCirs2aiy6L6SsBF_cpyxSXgVliwXC1rsCxRg99LCr7gHgYJ.A.VU"
}

Error Response Example

{
"error": "unauthorized_client",
"error_description": "Missing required parameter: client_id or client application is not registered"
}

5.27.5 Example OAuth2 Token Renewal API

The following is a minimal example of how OpenIAM implements authentication token renewal:

URL

/idp/rest/api/auth/renewToken

Method

GET

Headers

• Authorization: with oAuth token in format 'Bearer: <token>'

• Cookie: with current valid authentication token in format 'OPENIAM_AUTH_TOKEN=<token>'

cURL Example

// Scurl -XGET -v -H 'Authorization: Bearer ssssss' -H 'Cookie: OPENIAM_AUTH_TOKEN=asdasdas' 'http://127.0.0.1:8080/idp/rest/api/auth/renewToken'

Success Response Example

{
"authToken": "asdas+asd/YagqkcJEql+asd=",
"timeToLiveSeconds": -1
}

Error Response Example

5.27.6 Example OAuth2 Authorization API

The following is a minimal example of how OpenIAM implements authorization using OAuth2:

URL

{server_url}/idp/oauth2/token/authorize

Replace {server_url} with the name of the server.

Method

GET

Parameters

• response_type: codetoken

• client_id: webconsole/Access Control/Authentication Providers/*needed provider* edit/ Client ID field

• redirect_uri: webconsole/Access Control/Authentication Providers/*needed provider* / Redirect Url. Use 'Space' or 'Enter' to separate values field.

cURL Example

curl

'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=code&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

or, just:

curl

'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=code&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

Success Response Example

redirect to redirect_uri?code=code

Error Response Example

redirect to redirect_uri with error

5.27.7 Example OAuth2 Authorization Implicit Grant Flow API

The following is a minimal example of how OpenIAM implements an implicit grant flow API style of authentication:

URL

{server_url}/idp/oauth2/token/authorize

Replace {server_url} with the name of the server.

Method

GET

Parameters

• response_type: token

• client_id: webconsole/Access Control/Authentification Providers/*needed provider* edit/ Client ID field

• redirect_uri: webconsole/Access Control/Authentification Providers/*needed provider* / Redirect Url. Use 'Space' or 'Enter' to separate values field.

cURL Example

curl -v XGET 'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=token&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

or, just:

curl 'http://dev1.openiamdemo.com:8080/idp/oauth2/authorize?response_type=token&client_id=EF4128DCC0D24ED3BAC17FC918FDDBF5&redirect_uri=http://dev1.openiamdemo.com:8080/oauthhandler'

Success Response Example

redirect to redirect_uri?code=access_token=Pcej-9OdU_wshAjTn76MP-Cj5OgY_sfdYrt&expires_in=60000&token_type=Bearer

Error Response Example

redirect to redirect_uri with error

5.27.8 Example Get OAuth2 Token Information API

The following is a minimal example of how OpenIAM implements a get operation for token information:

URL

{server_url}/idp/oauth2/token/info

Replace {server_url} with the name of the server.

Method

GET

Parameters

token: token should be created via Create token.

cURL Example

curl -v XGET

'http://dev1.openiamdemo.com:8080/idp/oauth2/token/info?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

or, just:

curl

'http://dev1.openiamdemo.com:8080/idp/oauth2/token/info?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

Success Response Example

{
"expired": false,
"client_id": "92BF26DD50D748668730F7639C4A0D3D",
"user_id": "3000",
"access_token": "Lf_Sc-YeKHB8rsGfiGcLMKJOxbTGmpbdYs5wK3i7ZhINrjJlTOHEuV-phwJ1wE7.MjWqDcx8Lpri",
"expires_in": 1709,
"expires_on": 1531332707193,
"scopes": [
{
"scopeId": "c42a190a6488010b01648810b83a005a",
"name": "dev1 - /idp/oauth2/token/info"

},
{
"scopeId": "c42a190a6488010b01648810bdfd0096",
"name": "dev1 - /idp/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810be2a0098",
"name": "dev1 - /webconsole/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810be6d009b",
"name": "dev1 - /selfservice/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810be96009d",
"name": "dev1 - /selfservice-ext/rest/api/*"
},
{
"scopeId": "c42a190a6488010b01648810bebf009f",
"name": "dev1 - /webconsole-idm/rest/api/*"
}
]
}

Error response example

// Some code{"code":401,"error":"invalid_token","error_description":"Authorization token is expired"}

5.27.9 Example Create OAuth2 Token API

The following is a minimal example of how OpenIAM would create an OAuth2 token using authorization grant flow style:

URL

{server_url}/idp/oauth2/token

Replace {server_url} with the name of the server.

Method

POST

Parameters

• client_secret: webconsole/Access Control/Authentification Providers/*needed provider* edit/ Client Secret field

• client_id: webconsole/Access Control/Authentification Providers/*needed provider* edit/ Client ID field

• grant_type: authorization_code

• redirect_uri: webconsole/Access Control/Authentification Providers/*needed provider* / Redirect Url. Use 'Space' or 'Enter' to separate values field

• code: code should be generated with Authorization code grant flow request.

Headers

Content-Type: application/x-www-form-urlencoded

cURL Example

curl -v -XPOST --data 'client_secret=client_secret&client_id=client_id&grant_type=authorization_code&redirect_uri=redirect_uri&code=code' 'http://dev1.openiamdemo.com:8080/idp/oauth2/token'

Success Response Example

{
"access_token": "MjwOxreF7e-NW_NBA6UNuB9d_4IcohdK2bUSxqZ_BxDlCG7uD.ZstmoKwvuWq1hL49pClk3dlo",
"token_type": "Bearer",
"expires_in": 1800
}

Error Response Example

{
"error": "invalid_request",
"error_description": "Code parameter is expired"
}

{
"error": "invalid_request",
"error_description": "Redirect URL does not mach to initial one."
}

5.27.10 Example Revoke OAuth2 Token API

The following is a minimal example of how OpenIAM implements OAuth2 token revocation:

URL

{server_url}/idp/oauth2/token/revoke

Replace {server_url} with the name of the server.

Method

POST

Headers

Content-Type=application/x-www-form-urlencoded

Parameters

token: token should be created via Create token.

cURL Example

curl -v XPOST --data 'token=token' 'http://dev1.openiamdemo.com:8080/idp/oauth2/revoke'

Success Response Example

{
"status": "SUCCESS",
"errorCode": null,
"errorText": null,
"fieldMappings": null,
"stacktraceText": null,
"responseValue": null,
"errorTokenList": null,
"failure": false,
"success": true
}

Error Response Example

{"code":403,"error":"insufficient_scope","error_description":"The request requires higher privileges than provided by the access token","scope":"1531291154553_/idp/oauth2/revoke"}

**5.**27.11 Example Validate OAuth2 Token API

The following is a minimal example of how OpenIAM implmenents OAuth2 token validation:

URL

{server_url}/idp/oauth2/token/validate

Replace {server_url} with the name of the server.

Method

GET

Parameters

token: token should be created via Create token.

cURL Example

curl -v XPOST --data 'refreesh_token=refreesh_token' 'http://dev1.openiamdemo.com:8080/idp/oauth2/token/refresh'

Success Response Example

{
"access_token": "j4I6p0vDxZKduJXlipXZq5LNQqY1aJWvtYp812.k6246Sn2FY3rpyos..qJtScD8.wjytm1idsnopHmb.u",
"token_type": "Bearer",
"expires_in": 60,
"refresh_token": "0q1V8ZJaayxV5qcD4JtwF5.LyQOPMaZY.cNsIuZAYQ-TXGqrZDpy6AEOhc58dwEjgHDN2Bx_J.XkVTZ"
}

Error response example

{
"timestamp": 1531449532875,
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.web.bind.MissingServletRequestParameterException",
"message": "Required String parameter 'refresh_token' is not present",
"path": "/idp/oauth2/token/refresh"
}

5.27.13 Example User Information from OAuth2 Token API

The following is a minimal example of how user information can be obtained from OpenIAM using an OAuth2 token:

URL

{server_url}/idp/oauth2/userinfo

Replace {server_url} with the name of the server.

Method

GET

Parameters

token: token should be created via Create token.

cURL Example

curl -v XGET 'http://dev1.openiamdemo.com:8080/idp/oauth2/userinfo?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

or, just:

curl 'http://dev1.openiamdemo.com:8080/idp/oauth2/userinfo?token=rdSOyor6hqJ2CrQ5QrpeXgX.ItgVEx1.nskN'

Success Response Example

{
"sub": "3000"
}

Error Response Example

{"code":401,"error":"invalid_request","error_description":"Authorization token is not found"}
{"code":403,"error":"insufficient_scope","error_description":"The request requires higher privileges than provided by the access token","scope":"1531291154428_/idp/oauth2/userinfo"}

4.27.14 Example API for Defining Resources, Roles, Access and Provisioning

The most comprehensive API available for this is delivered by OpenIAM. Unfortunately this API is currently delivered in SOAP. The purpose of this API is to provide 3rd parties the ability to create resources, roles and access within the IAM system. There are multiple options to get this done including batch upload and configuration using the administrative user interface. This would need to be addressed at implementation time using the most practical means. There does not seem to be a current use case for the BB’s to create these types of resources on the fly using the IAM API. The API definitions can be found here: https://docs.openiam.com/docs-5.1.14/html/docs.htm#API/SOAP/SOAP.htm%3FTocPath%3DAPI%2520Guide%7CPart%2520II%253A%2520SOAP%2520API%2520integration%2520services%7C_____0

3.1 User-centred design

Continuously improve services to meet the needs of users.

3.2 Accessibility and inclusion

Build services that are usable and equitable for all.

3.3 Consistency

Create user-friendly services that build trust.

3.4 Technology choices

Making decisions based on needs.

Start by understanding the needs and requirements of the solution, including users' needs, expectations, and pain points. Consider the "Person" and the "Role" are not the same. For example, the same person may use a health care application as a doctor and also as a patient but the needs of a doctor's UI/UX are different from that of a patient, and while the doctor may work on the data of multiple patients, a patient can access only self-data. You can find more examples of how to understand user needs in

User Research

Understanding user needs begins with user research. This includes techniques like surveys, interviews, user testing, and analysis of usage data. The goal is to understand the tasks users are trying to complete, the problems they face, and the goals and motivations of users in specific roles.

Question Assumptions

Always question assumptions about what users need in specific roles. Just because something is commonly done or seems like a good idea doesn't mean it is what users need. Validate every assumption with data.

Frame the Problem

Before jumping into solutions, make sure you have correctly framed the problem. Ask: What user need is this solving? Why is this a problem for our users? How do we know this?

Prioritise Based on User Needs

Not all user needs are equally important. Use data from your research to prioritise features and improvements based on what users need most.

3.1.1 Understand user needs

3.1.2 Test with users

3.1.3 Iterate based on feedback

Find opportunities to collaborate closely with users, stakeholders, and other , throughout the design process.

Empower users to take an active role in co-creating and co-designing public services.

Example activities

Engaging Stakeholders:

• Involve stakeholders early on to understand their expectations and objectives.

• Get feedback from stakeholders to review and comment on design decisions and findings.

Collaborating with Team Members:

• Conduct workshops or brainstorming sessions for diverse input.

• Have peer reviews to get the perspective of different roles in the design.

• Emphasise user needs and project goals within the team.

Involving Users:

• Carry out user research activities, like interviews and surveys, to understand user needs.

• Hold co-design sessions with users, for them to participate directly in the design process.

• Conduct with real users to identify issues and opportunities for improvement.

• post-launch.

Usability testing allows you to observe firsthand how users interact with your product. You can identify any challenges they encounter and understand the 'why' behind their behaviour. This improves user experience and can prevent costly redesigns later on.

Further reading and resources for usability testing include:

Accessibility is important because it allows services to give equal access to all citizens, comply with legal requirements, foster inclusivity, enhance user experience, avoid discrimination, and contribute to government credibility, cost savings, innovation, and international reputation.

3.2.1 Test for accessibility

There could be significant interdependencies between UI components for different accessibility requirements. The World Wide Web Consortium and Web Accessibility Initiative have developed standards for considering the needs of developers (WCAG, ATAG, UAAG), authoring tools, accessibility evaluation tools, and guidelines on how to make user agents (browsers, browser extensions, media players, readers) accessible to users.

Test for accessibility

3.2.2 Test your service with diverse users

Involve a diverse user group in the design

Support multiple languages

Foster a culture of inclusion

1. Cloud-Based Analytics

The cloud-based analytics solution, such as Google Analytics, is a straightforward and easy-to-setup method that offers robust data about your users' behavior. It's a beneficial choice for those who want to get started quickly and without much technical setup.

Setup: Begin by creating an account on the platform of your choice. You will then add the tracking code they provide to your website. Ensure this code is embedded on each page you wish to monitor.

Configuration: Within the platform, you'll set up goals or events that align with your Key Performance Indicators (KPIs). This allows the software to track specific user actions that are of interest to your business.

Monitoring: Once the setup is complete, you can start monitoring user behavior data through the platform's dashboard.

Remember to respect user privacy throughout this process, which involves informing users about the data you collect, why you collect it, and offering an option to opt out.

2. Self-Hosted Analytics

Self-hosted analytics, such as open-source platforms like Matomo or Plausible, offer more control over your data and are often favored by businesses that place a high emphasis on data privacy and security. This is particularly important if you value keeping data in-country due to regulatory or compliance requirements.

Setup: You'll need to set up these platforms on a server, which could be owned by you or rented from a hosting provider. After this, you'll add the platform-specific tracking code to your website.

Configuration: As with cloud-based solutions, you will need to define the events or goals that align with your KPIs.

Monitoring: Once configured, you can use the platform's dashboard to track user behavior and monitor your KPIs.

Server space considerations for self-hosting depend on several factors, including the amount of traffic your website receives and the level of detail in the data you are tracking. As a starting point, 1GB of space could handle over a million simple page views, but more complex tracking would reduce this. Consulting with a server or IT professional could provide a more accurate estimate based on your specific needs.

3. Start with cloud

It is also possible to start with a cloud-based solution for quick setup and immediate insights, then transition to a self-hosted solution as it's being set up. This allows you to benefit from analytics data right away, while your more robust, privacy-centric solution is being prepared.

Once you're ready to go live, continuously monitor and evaluate the performance and usability of the service, and iterate the design accordingly to drive continuous improvement and optimise user experience.

Key performance indicators (KPIs)

Determine Must-Have KPIs

At a basic level, all services should be tracking metrics such as:

• User Satisfaction - Overall, how satisfied are users with your service? This can be measured through surveys, feedback forms, or by analysing user behaviour (e.g., how often they return to your service).

• Task Completion Rate - What percentage of users successfully complete the tasks they set out to do on your service?

• Error Rates - How often do users encounter errors or difficulties when using your service?

Identify Service-Specific KPIs

In addition to these basics, each service will likely have specific KPIs relevant to its unique goals and user tasks. Identify what these are and how you can measure them.

Run a session with your team to create a performance framework.

Set Up Analytics

Use analytics tools to collect data on these KPIs. Google Analytics is a popular choice, but there are many other tools available. Make sure to set up your analytics tool to track the specific actions and events that correspond to your KPIs.

Collect satisfaction data at the end of the user journey

Implement a mechanism to collect user satisfaction data at the end of key user journeys. This could be a survey or a simple rating system.

See the pattern for collecting feedback

Collect feedback throughout the user journey

Do not wait until the end of the journey to collect feedback. Implement feedback mechanisms at key points throughout the user journey. This could be feedback forms on individual pages, live chat options, or proactive prompts asking users if they need help.

See the pattern for collecting feedback

Regularly review and act on data

Set a regular schedule to review your KPIs and user feedback. Use this data to identify issues and opportunities for improvement, and take action accordingly.

Involve diverse users in testing and feedback

Ensure your user testing and feedback collection includes a diverse range of users. Include users with disabilities and those from various backgrounds and experiences. This approach helps identify potential accessibility and inclusivity issues that might be overlooked by individuals without these experiences.

Inclusive Design Toolkit from Microsoft

Understand user capacity and identify barriers to access

To create a service that caters to all users, you must understand their unique capacities. Consider factors like:

• Time available

• Financial situation

• Ease of access to an interface (device or person)

• Interface capability and confidence

• Service process-related confidence

• Awareness of the service, its purpose, and access options

• Ability to comprehend information

• Mental health/emotional capacity

• Trust in service robustness, security, reliability

• Ability to provide required information

• Willingness to use the service, at all or in the most cost-effective way

With this understanding, identify the potential barriers users might face when accessing and using the service. These barriers could be,

• Physical: Disabilities that affect a person's ability to interact with interfaces.

• Technological: Limited access to high-speed internet, up-to-date devices, or the latest software.

• Cognitive: Cognitive impairments, learning disabilities, or language barriers that make the service hard to understand or use.

• Economic: Economic limitations that restrict access to necessary technology or internet access.

• Geographical: Limited internet access in rural or remote areas, or cultural or language differences in different regions.

• Privacy and Security: Concerns about personal data usage or protection.

Design for inclusivity

Having understood user capacity and potential barriers, you should design your service to be as inclusive as possible. This could involve simplifying processes, offering alternative access methods, or providing additional support where needed.

Consider non-digital alternatives

While digital public services offer many benefits, they may not be suitable or preferred for all users. Some users may lack the necessary technology or digital literacy, while others may simply prefer traditional methods. In these cases, consider offering alternative mechanisms for accessing the service, such as phone support or physical locations.

Consider Gender Equality and Social Inclusion (GESI)

In all aspects of your design process, ensure principles of Gender Equality and Social Inclusion (GESI) are adhered to. It means your service should be accessible and fair to all users, irrespective of their gender, age, ethnicity, disability status, income level, etc.

Example

In a public healthcare service, implementing GESI principles led to the development of a more inclusive appointment scheduling system.

It was noticed that many women, especially from lower-income backgrounds, were unable to attend appointments during standard working hours due to their caregiving responsibilities. By extending service hours to evenings and weekends, and providing childcare services, the service became more accessible to this demographic, significantly increasing attendance rates.

Further reading:

• GESI Qualitative Framework by Oxford Insights

• Design Justice principles

Share research findings with team members, senior members or strategic leaders, and even the general public whenever practical.

The aim is not just to share information but also to generate dialogue and collaborative action based on the findings.

Organise Your Findings

Begin by grouping your user insights, key takeaways, and suggestions. This could be grouped by themes, user groups, and stages in the user journey.

Create a Simple Presentation

Document your findings. Each slide could represent a key finding or insight. Remember to use clear, simple language and include visual aids where possible to increase understanding.

Schedule a Playback Session

Invite team members and stakeholders to a meeting where you'll share your findings. Make time for discussion.

Document and Share

Share the presentation along with any additional notes from the discussion. This ensures that everyone has access to the information and can refer back to it in the future.

You might even consider publishing findings openly through a blog or similar format.

Check WCAG Compliance

Make sure that the implementation of the Building Blocks and the overall digital government service meets the Web Content Accessibility Guidelines (WCAG) standards for accessibility.

WCAG provides a set of internationally recognised guidelines for creating accessible web content. Familiarise yourself with the guidelines to ensure your service meets the necessary accessibility requirements.

Web Content Accessibility Guidelines (WCAG)

Test with Accessibility Tools

Test the service using accessibility tools to identify and address any accessibility issues. These tools help simulate the experience of users with disabilities and uncover potential barriers.

Consider using screen readers, keyboard navigation, and colour contrast checkers, among other tools, to ensure your service is accessible to all users.

Service manual from the United Kingdom's Government on how to test for accessibility.

Seek Expert Assistance

If you encounter complex accessibility challenges or require specialised knowledge, consider seeking expert assistance or consultation. Accessibility experts can provide guidance and support in ensuring your service meets the highest accessibility standards. They can help identify and address accessibility issues specific to your service and provide valuable insights throughout the design and development process.

Further reading:

• Dos and don'ts on designing for accessibility

Foster a culture of inclusivity within the team and encourage ongoing education and awareness of inclusivity and diversity's best practices. [resource on co-design]

Everyone benefits

Accessible design isn't just for users with disabilities - it enhances usability for all users. Simple features like captions or clear language can help everyone.

Temporary/situational disabilities

Accessibility isn't just about permanent disabilities. Users may experience temporary or situational impairments, like a broken arm or a bright environment, where accessibility features can improve their experience.

Ageing population

Accessible design is particularly important for older adults who may experience changes in vision, hearing, and motor skills. Designing with accessibility in mind ensures your service is user-friendly for all age groups.

Legal/ethical duty

In many places, accessibility is not just an ethical duty but also legally required. Providing accessible services ensures everyone can use your service, regardless of their abilities.

Future-proofing

Accessible design often results in more robust and flexible services. By prioritising accessibility, you make your service more resilient to future changes and adaptable to different technologies or platforms.

Overhead cost

Incorporating accessibility from the start of the design process is efficient. Retrofitting accessibility features later can be more time-consuming and costly. Make accessibility a foundational part of your design process, not an afterthought.

Understanding style guide, frontend framework, and design system

• Style Guide: A style guide is a reference tool that establishes design and writing standards. It includes branding elements (logos, colour schemes), UI components, and coding standards, ensuring consistency across a product or set of products.

• Frontend Framework: This is a structured package of standardised code (HTML, CSS, JS documents, etc.) that forms the foundation for designing a website or web application. Examples include React, Vue.js, and Angular.

• Design System: A design system is an overarching guide that includes the style guide and coded UI components (often from a frontend framework). It houses design principles, visual design rules, coded components, and other standards guiding the creation of a range of products or services.

Creating a style guide is a crucial first step in building a comprehensive design system. It defines the visual aspect of the system which can later be expanded to include coded components, UX patterns, and more.

Steps to create a style guide

If a style guide does not exist already, here are the steps for its creation:

• Audit Existing Designs - Review current services to identify common components and styles.

• Create and Document Components - Develop reusable design components (like buttons or headers) and write clear guidelines for their use.

• Define Visual Styles - Document your colour palette, typography, grid system, spacing, and other visual styles.

• Ensure Accessibility - Incorporate guidelines to ensure your digital services are usable by all citizens, for example, colour contrast between text and backgrounds.

Including style guide in a supplier's Request for Qualifications (RFQ)

If you do not have a consistent style guide across government the creation, usage and, contribution to a common style guide should be included as a requirement for suppliers. This ensures the supplier's work aligns with the existing style guide and contributes to its improvement or expansion, leading to a more collaborative, efficient, and cohesive design ecosystem. As part of the RFQ:

• Include a copy of the style guide if it exists - Make sure that suppliers have a copy of the existing style guide to understand its current state and requirements.

• Require adherence to the style guide - Suppliers should demonstrate an understanding of the style guide and show how they will adhere to it.

• Encourage contributions - Request that suppliers identify potential improvements or expansions to the style guide during their work, and include a process for proposing and implementing these changes.

Identify the languages users speak

Analyse user demographics data to determine the languages spoken by your users. This data can be obtained through user surveys, usage data analysis, or from market research. You may also find legislation for languages the government must support.

Read more about using data to make decisions.

Make a plan for multilingual support

Consider the feasibility and utility of providing multilingual support. This includes the translation of key content, interface elements, instructions, and forms into the most commonly spoken languages of your user base. Automated translation services can be a cost-effective starting point, but human review is essential to ensure cultural appropriateness and accuracy.

Use simple language

Even in the primary language of the service, avoid using complex jargon and technical terms. Use plain, simple language that can be easily understood by a broad audience. This will also facilitate more accurate translations.

Language Detection and Preferences

Implement language detection based on the user's browser or system settings and offer the option for users to manually set their language preferences.

Use the Accept-Language HTTP header to detect the language preferences set by the user in their browser or device settings. This can give you a default language to serve to the user initially.

Store the user's language preference (in cookies or user profiles) so that you can load the website or app in their preferred language in subsequent visits or sessions.

Clear Language switching options

Options to switch languages are clearly visible and easily accessible across all pages of the service. Users should not have to search or dig deep into settings to find this option. See the design pattern for switching languages.

Support for right-to-left (RTL) languages

If you're offering support for languages that are read right-to-left (like Arabic or Hebrew), make sure your user interface can handle that transition seamlessly. This is not just about text direction; UI elements and navigation should also mirror to offer a consistent RTL experience.

Read more about using frontend frameworks.

GovStack Patterns - A Strong Foundation

GovStack offers a robust set of well-tested patterns for common user journeys. These can serve as a foundational structure for your services, presenting an outline for the necessary pages within your user journey and providing guidance for the content on each page.

View the design patterns

Beyond Coded Components

While these patterns offer a solid starting point, it is important to note that they do not provide coded or designed components. For implementing these aspects, refer back to our guidance on setting up a front-end framework.

Use a frontend framework

Consistency and Testing

Whether employing GovStack patterns or creating your own, maintaining consistency across your government services is key. After establishing your patterns, make sure to test the end result with users. This will ensure that your service is not only consistent but also user-friendly and effective.

Test with users

3.3.1 Use simple language

Use simple language

3.3.2 Reuse existing styles and patterns

Implement a consistent style guide

Use design patterns

Use a frontend framework

3.3.3 Provide a joined-up experience

Interoperability

Use integrations where possible

3.3.4 Share design decisions

Work in the open

The benefits of working in the open

• Transparency: Working in the open allows stakeholders, other teams, and even the public to understand how decisions are made and progress is tracked. This transparency can build trust and enable informed discussions.

• Collaboration: By making your work accessible, other teams can provide input, learn from your approach, and possibly contribute, fostering a collaborative ecosystem.

• Reusability: Openly sharing your work means other teams can reuse and adapt your processes, tools, or code, avoiding duplication of effort and accelerating development across the board.

• Feedback and improvement: Working in the open invites feedback from a wider audience, which can bring different perspectives and promote continual improvement.

Practices to consider

• Open source your code: Where possible, and with the necessary security considerations, share your code repositories publicly. This allows other developers to learn from, reuse, or contribute to your code.

• Share your processes and decisions: This can be done via blog posts, open meetings, or shared documents that detail your working practices, decision-making processes, and project progress.

• Invite feedback: Provide channels for feedback on your work, whether that's through comments on a shared document, feedback on a blog post, or interactions on a code repository.

• Promote open standards: Adhere to and advocate for open standards in your work. This not only aids in compatibility and interoperability but also supports a wider culture of openness.

By working in the open, government services can not only build more efficient and user-centric digital services but also foster a culture of collaboration and learning that extends beyond individual teams or projects.

A frontend framework, also known as a CSS framework, is a package consisting of pre-written, standardised code in files and folders. They give developers a base to build upon while still allowing flexibility with the final design. Essentially, a frontend framework provides a structured, reliable, and reusable template.

Benefits of a frontend framework

1. Efficiency: They save developers a significant amount of time by providing a foundation.

2. Consistency: By using the same framework, teams can maintain consistency across projects.

3. Responsiveness: Most frontend frameworks are built to be fully responsive right out of the box.

4. Community: Popular frameworks have a large community, which can offer support, additional tools and plugins to extend functionality.

Setting Up a frontend framework

Setting up a frontend framework largely involves downloading the framework's files and incorporating them into your development environment. The specific steps may vary depending on the chosen framework.

Choosing a frontend framework

Considerations for choosing a frontend framework include the framework's community support, ease of use, performance, and compatibility with your project's requirements. One crucial aspect to consider is the level of support for accessibility and right-to-left (RTL) language support.

Here's a comparison of three popular frameworks:

Use the framework as a foundation for your design system

Choose a frontend framework fitting your needs as the foundation for a reusable design system. This system, combining the framework's technical foundation with your specific visual styling and design guidelines, will ensure uniformity and accessibility across projects within your organisation. Regular updates to this living system will accommodate evolving needs and interaction patterns, solidifying an efficient and inclusive digital experience throughout government services.

\

Consider potential integration points and interoperability requirements early in the design process, involving relevant stakeholders, including the Building Blocks development team.

• Identify functionalities that can be provided by other services, for example, departmental registries.

• Integrate these services using their APIs.

• Test the integrations to ensure they work correctly.

• Be prepared to handle any downtime or changes to these services.