3. Security & Privacy

3.1. Introduction

OSIA defines a set of interfaces/APIs rather than a complete identity management system. It is therefore out of scope for OSIA to recommend security and privacy mechanisms beyond the APIs level.

3.2. Virtual UIN

All persons recorded in a registry have a UIN that is considered a key to access the person’s data for all records. Please note that the UIN does not have to be the same throughout all registries as long as there is a mechanism to map all different UINs among them.

3.3. Authorization

This chapter describes how to secure OSIA APIs through the usage of standard JWT but not how to generate and protect such tokens, nor how to secure a complete identity management system.

3.3.1. Principles

Securing OSIA services is implemented with the following principles:

  • Rely on JWT: “JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties” It can be “digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted”. [RFC 7519]

  • Tokens of type “Bearer Token” are used. [RFC 6750] The generation and management of those tokens are not in the scope of this document.

  • Validating the token is the responsibility of the service implementation, with the help of components not described in this document (PKI, authorization server, etc.)

  • The service implementations are responsible for extracting information from the token and give access or not to the service according to the claims contained in the token and the scope defined for each service in this document.

  • The service implementations are free to change the security scheme used, for instance to use OAuth2 or OpenID Connect, if it fits the full system security policy. Scopes must not be changed.

  • All HTTP exchanges must be secured with TLS. Mutual authentication is not mandatory.


The added use of peer-to-peer payload encryption - e.g. to protect biometric data - is not in the scope of this document.


OSIA does not define ACL (Access Control List) to protect the access to a subset of the data. This may be added in a future version.


Bearer tokens are sensitive and subject to security issues if not handled properly. Please refer to JSON Web Token Best Current Practices for advice on proper implementation.

3.3.2. Rules

All scopes are named according to the following rules:



  • application is a key identifying the interface group listed in Interfaces. Examples: notif, pr, cr, abis, etc.

  • resource is a key identifying the resource. Examples: person, encounter, identity, etc.

  • action is one of:

    • read: for read access to the data represented by the resource and managed by the application.

    • write: for creating, updating or deleting the data.

    • or another value, for specific actions such as match or verify that need to be distinguished from a general purpose read or write for proper segregation.

Scopes should be less than 20 characters when possible to limit the size of the bearer token.

3.3.3. Scopes

The following table is a summary of all scopes defined in OSIA.

Table 3.1 Scopes List






List Subscription






Create Topic


List Topics


Delete Topic






Data Access

Read Person Attributes

pr.person.read or cr.person.read

Match Person Attributes

pr.person.match or cr.person.match

Verify Person Attributes

pr.person.verify or cr.person.verify

Query Person UIN

pr.person.read or cr.person.read

Query Person List

pr.person.read or cr.person.read

Read document

pr.document.read or cr.document.read

UIN Management

Generate UIN


Enrollment Services

Create Enrollment


Read Enrollment


Update Enrollment


Partial Update Enrollment


Finalize Enrollment


Delete Enrollment


Find Enrollments


Send Buffer


Get Buffer


Population Registry Services

Find Persons


Create Person


Read Person


Update Person


Delete Person


Merge Persons


Move Identity


Create Identity


Read Identity


Update Identity


Partial Update Identity


Delete Identity


Set Identity Status


Define Reference


Read Reference


Read Galleries


Read Gallery Content



Create Encounter


Read Encounter


Update Encounter


Delete Encounter


Merge Encounters


Move Encounter


Update Encounter Status


Update Encounter Galleries


Read Template


Read Galleries


Read Gallery content






Credential Services

Create Credential Request


Read Credential Request


Update Credential Request


Cancel Credential Request


Find Credentials


Read Credential


Suspend Credential


Unsuspend Credential


Revoke Credential


Set Credential Status


Find Credential Profiles


ID Usage

Verify ID




Read Attributes


Read Attributes set


3.3.4. REST Interface Implementation

The OpenAPI files included in this document must be changed to:

  1. Define the security scheme. This is done with the additional piece of code:

          type: http
          scheme: bearer
          bearerFormat: JWT
  2. Apply the security scheme and define the scope (i.e. permission) for each service. Example:

            - BearerAuth: [id.read] # List of scopes
              description: OK
              description: Not authenticated (bad token)
              description: Access token does not have the required scope

See the different YAML files provided in Technical Specifications.

3.4. Privacy by Design

Privacy by design is a founding principle of the OSIA initiative.

The OSIA API is designed to support the protection of private citizens’ Personal Identifiable Information (PII).

The protection of PII data is a central design concern for all identity based systems regardless of where these are based.

PII data does not recognize geographical boundaries; it moves across systems and jurisdictions. Similarly, the OSIA initiative is not geographically limited. OSIA takes its strong reference point from the European Union’s GDPR regulation because this is considered by many as a best practice approach. GDPR anticipates the possible adverse consequences from the mobility of PII whether inside or outside the EU.

The General Data Protection Regulation (GDPR) is quite recent. It was introduced across the EU in 2016, before reaching its full legal effect in 2018. It is adopted by all EU governments and carries direct regulatory and legal force for any organization handling Personal Identifiable Information (PII), either in the EU or in connection with EU citizens or residents. Compliance failure in respect of GDPR carries significant financial penalties, reflecting the rights of individuals and groups, as well as the importance of the issue.

GDPR is not the only defined standard, but it is seen as a best practice one. It is exemplary approach for the safeguarding of PII; but, it should also be seen as a safeguard for a system owner/operator’s interests. It is a major driver for government leadership in Identity Management is to prevent identity fraud.

3.4.1. Privacy for end-to-end systems

For privacy the bigger goal is to protect PII across the full reach of ID systems. The OSIA API is a fundamental part and principle of the building process, providing definitions of how components are connected.

This is a part of a wider story. An end-to-end solution making use of the OSIA API should address three specific areas of concern for PII. Correct implementation of the API definition

PII data flows through systems. API based connectivity between functional components is by definition a way of sharing information, which will focus mostly on PII. The OSIA API defines what should happen between application endpoints involving OSIA framework components. It defines content and a minimum acceptable security standard for implementation. PII safeguards within the components connected by the APIs

The API concept is built around functional components: the sub-systems for Identity Management.

As well as the correct implementation or use of the appropriate API, a component should also meet PII requirements while this is present within the component. Such internal component design and PII behavior is the responsibility of the component supplier.

The customer architect responsible for an API connected solution should therefore ensure that the internal logic of an individual component is itself GDPR compliant. The API concept cannot itself provide any guarantee that components are designed with the same or sufficient internal levels of PII safeguards. What the API can do is to preserve this level of trust and prevent the creation of new vulnerabilities between these components. The workflow connecting components in an OSIA enabled solution

OSIA provides a model for an open architecture. An end-to-end identity system may use some, or all of the OSIA components. It may use additional components to move data through the system. Wherever the system uses components to move data that are not covered by the OSIA framework definition then these should support end-to-end security with the same objective of GDPR compliance.

3.4.2. PII actors

The GDPR approach provides simple definitions.

  • PII is a very wide category of information. It can be a name, a photo, a biometric, an email address, bank details, social media postings, medical data, and even an IP address;

  • The PII data belongs to a Data Subject who is a natural person that might identified directly or indirectly using the PII;

  • The usage, rules, and means of processing PII are determined by a Data Controller (e.g. the Government agency);

  • The data is processed by a Data Processor.

When a government department acts as owner of an ID system then it is a Data Controller. It may also act as the Data Processor if it operates this system ‘in house’.

However, in today’s commercial world the Data Controller is equally likely to delegate some processing to a data center or to a business service for all or part of the system. In this case these delegated parties are Data Processors, and they also subject to the PII considerations.

Suppliers of the systems purchased and commissioned by Data Controllers, and operated by Data Processors are not directly subject to the regulation.

3.4.3. Data subject rights

A GDPR data subject has several rights that should be reflected throughout the wider ID systems architecture. The right to be forgotten

A subject may ask for her data to be deleted.

Depending on the purpose and the authority of the system this right may be restricted or blocked, however the deletion of non-essential PII data may be a requirement according to some local laws. The Data Controller should be able to justify why specific items of PII need to be retained against the subject’s wishes, and when there is no reason for retention then the automated purging of unnecessary data is generally recommended.

An example impact of this for API usage is where an enrollment client holds enrollee data until receiving a response via the API from the enrollment server to the effect that any client stored data can be deleted. The Data Processor operating the client is responsible to ensure this deletion is systematically applied. Typically this may be done with a configuration in the component product used. Privacy by design

Systems should be designed to limit data collection, retention and accessibility.

This applies equally to APIs as to the system components themselves. No more data should be passed over an API than is required. A component passing or receiving data should consider how to minimize what new PII it collects, shares, and stores. The Data Controller should know by design what data is held and where; as well as which APIs are sharing what data.

An example of this principle for API usage can be where a credential management system receives PII over an API for credential production, then deletes the PII once the document is produced successfully. The system may limit its retained data to production audit data. A credential management system with a different set of responsibilities defined by the Data Controller may justify the retention of a wider set of PII, which might be replicated elsewhere in the system. A subject might ask to know where this data sits. The Controller should be able to tell the subject, and the Processor able to prove it. Breach notifications

Supervisory powers vary globally. In the EU organizations have to notify their national supervisory authority in the event of a discovered data breach involving PII. They are given a 72 hour period to do this after becoming aware of the breach. The purpose of this notice period is to allow the organization to determine the nature and the impact of the data breach.

Data subjects have the right to be informed about data breaches involving their personal data.

By following the Privacy by Design approach, detection and data exposure can be assessed more accurately and quickly. Data is typically in transit between sub-systems, then at rest or in use within a given sub-system. When correctly implemented the OSIA API concept provides assurance against breaches at the API in-transit level. Combined with the knowledge of what data is stored, and where, this Privacy by Design approach assists in the detection of breaches.

At the time of GDPR’s introduction the biggest issuing facing most organizations was not the implementation of new controls, but the discovery of where and what data was in their possession. The made it very difficult to know if data was ever compromised. Risk and impact assessments

Looking at systems overall an organization has to perform a privacy impact assessment.

This describes what PII is collected, and how this is maintained, protected, and shared. This may be done as part of a wider ISO 27000 process including risk assessment, but this is not mandatory.

Today most providers of components within the OSIA framework will provide such a privacy impact assessment statement for their products, including the GDPR controls in that product.

Taken together with the OSIA API specification then these assessments can be compiled to an overall statement of system PII compliance. Data portability

The portability of requirement was conceived for both transparency and commercial reasons.

PII held should be usable by the Data Subject upon request. For privacy it may be held encrypted in the Data Processor system, but must be provided in a structured and commonly useable format to the Data Subject under reasonable terms of access.

An example scenario might be where a Data Subject wishes to have a copy of a child’s birth record in a printed format or a format recognized by a third party. The concept of data portability may in some cases be implemented by a report service, or in some cases use an OSIA API to support the retrieval of personal attribute data to meet this demand.

3.4.4. What should OSIA API implementors do to prepare for safe PII?

  1. Appoint someone as the organization’s own GDPR or PII data expert. Someone who understands the Data Controller business requirements, and knows the technologies likely to be used for data processing.

  2. GDPR is a good example of best practice in PII Management, but it is vital to understand the current local regulatory environment. Local existing laws and regulations take precedence unless subject to GDPR, and even then local laws may be stricter.

  3. Use the OSIA API specification to understand the security organization of functional systems that might be needed and document an overall assessment of the PII privacy risk. Pay particular attention to sensitive data, and to the aggregation of PII.

  4. Ensure that component suppliers understand and support the principles of good PII management, or GDPR. Most suppliers provide a description of how this is enforced in their products or systems. They may even provide a user manual and training for this function.

  5. Document the design and lifecycle of data in the end-to-end system. The OSIA API Specification will help with this. It does not provide the full PII story, but it does provide the basis for the parts between components that the customer or its systems integrator will be responsible for.

  6. Consider the Data Subject consent requirements, based on the functions that subject data will be subject to.

  7. If the role is Data Controller, but not Data Processor then ensure that the organization used for Data Processing can understand and meet the guidelines for PII protection.

  8. Remember that good planning and execution are essential, but it might be asked to prove correct operation. Systems logs and audit data should be available. This should include API usage to indicate where data has been transferred.