9.5. PDND Signal Hub Endpoints¶
- Within the PDND platform, the Signal Hub serves as an intermediary component between PDND Providers and their PDND Consumers to facilitate real-time data variation notifications. To enable this functionality, the PDND Manager, acting in the role of PDND e-Service Provider, offers the following specialized PDND Signal Hub e-Services:
the Signal Collection e-Service which is used by PDND e-Service Providers to deposit Signals, since the PDND e-Service Provider acts as Consumer of the Signal Collection e-Service;
the Signal Distribution e-Service which is used by PDND e-Service Consumers to retrieve collected Signals, since the PDND e-Service Consumer also acts as Consumer of the Signal Distribution e-Service.
In order to protect the privacy of the Signal's subject, the PDND Manager requires each PDND e-Service Provider to pseudonymize the subject's identifier used within the Signals and set up a pseudonymization endpoint for their PDND e-Service. This pseudonymization endpoint is used by e-Service Consumers to use the pseudonymization algorithm in order to calculate the Signal subject's pseudonym. Only the PDND e-Service Provider and its PDND e-Service Consumers are able to link a Signal to the subject's personal data, while the PDND Manager only handles pseudonymized identifiers.
For detailed technical specifications and implementation guidelines, please refer to the Signal Hub Guide.
- In the context of the IT Wallet, Authentic Sources interact with the Signal Hub to notify Credential Issuers about changes in the status and/or value of attributes associated with Digital Credentials. Specifically,
the Authentic Source will deposit Signals in the Signal Hub, thus playing the role of PDND Consumer of the Signal Collection e-Service;
the Credential Issuer will retrieve Signals from the Signal Hub, and will thus play the role of PDND e-Service Consumer of the Signal Distribution e-Service.
Note
In the context of IT Wallet, due to the particular nature of the data exchanged, the pseudonymization of the Signal's subject is not needed since it is already an opaque identifier unrelated to the Digial Credential's subject. Thus, the Authentic Source does not need to set up a pseudonymization endpoint for its e-Services.
Authentic Sources that leverage PDND MUST use the Signal Hub e-Services.
Below it is provided the description of how the Authentic Sources and Credential Issuers interact with the Signal Hub e-Services together with the detailed formats of the requests and responses.
9.5.1. Prerequisites¶
Before using the Signal Hub, all Authentic Sources MUST:
have registered as Providers of their e-Service with the PDND;
have registered as Consumers of the Signal Collection e-Service of the Signal Hub;
Before using the Signal Hub, all Credential Issuers MUST:
have registered as Consumers of the relevant Authentic Sources' e-Services;
have registered as Consumers of the Signal Distribution e-Service of the Signal Hub;
9.5.2. Signal Hub e-Services¶
This section describes the endpoints available for the Signal Hub Collection and Distribution e-Services, including their functionalities and the expected request and response formats.
9.5.2.1. Signal Collection e-Service¶
Authentic Sources in the IT Wallet ecosystem use the Signal Collection e-Service to:
notify the Credential Issuer of a change of status and/or value of a specific attribute associated with a Digital Credential issued by the Credential Issuer;
notify the Credential Issuer of the availability of the attributes related to a specific Digital Credential which a User requested in its Wallet.
The last case, referred to as deferred issuance, happens when the Credential Issuer has requested a Digital Credential's attributes from the Authentic Source (invoking the Get Attribute Claims PDND endpoint) and the Authentic Source cannot respond immediately with the requested attributes. Thus, the Authentic Source notifies the Credential Issuer via the Signal Hub at a later time that the requested attributes are now available.
The Signal Collection e-Service endpoint is used by Authentic Sources to deposit Signals to the Signal Hub via a Signal Collection request. The latter MUST be a POST request with Content-Type
set to application/json
, whose header MUST have the parameters described in Signal Hub Guide and whose body MUST contain the following parameters:
Parameter Name |
Description |
---|---|
signalId |
REQUIRED. A positive 64 bit integer number referencing the identifier of the Signal in chronological order. |
objectType |
REQUIRED. Using this field the Authentic Source MAY use to further specify the Signal. |
objectId |
REQUIRED. The subject to which the Signal is bound. If the Signal has
|
signalType |
REQUIRED. Signal Type. It MUST be one of the following:
|
eserviceId |
REQUIRED. e-Service to which the Signal is bound. It MUST correspond to the e-Service Id value the Authentic Source is a Provider of. |
Note
In the deffered issuance flow, i.e., when the Authentic Source notifies the Credential Issuer of the availability of the Digital Credential's attributes via Signal Hub; both entities MUST keep track of the Credential Issuer's jti
value used in the Agid-JWT-Signature of the get attributes
request. This is necessary since the objectId
of the Signal MUST be set to that jti
value when the Signal has signalType
with value CREATE
.
A non normative example of the Signal Collection request can be found at Signal Hub push.
The Signal Collection e-Service response, acknowledging the correct parsing of the request, is specified in Signal Hub push, and has Content-Type
set to application/json
. The payload contains the body parameter:
Parameter Name |
Description |
---|---|
signalId |
REQUIRED. The identifier of the Signal that has been successfully collected by the Signal Collection e-Service. |
If any error occurs during the request parsing, the response MUST adhere to the error format defined in Signal Hub push-yaml.
Note
A complete OpenAPI Specification of the Signal Collection e-Service is available Signal Hub push-yaml.
The Authentic Source MUST implement the necessary logic to handle the requests to the Signal Collection e-Service endpoint, in doing this it has to consider the following aspects:
Signals are sent per PDND e-Service, therefore the Authentic Source SHOULD implement a Signal deposit cycle for each e-Service ID it is a PDND Provider of;
Signals are labeled by a unique identifier, the
signalId
, which is a positive 64 bit integer number. ThesignalId
MUST be incremented by 1 for each new Signal the Authentic Source wishes to deposit in the Signal Collection e-Service endpoint. It is up to the Authentic Source to keep track of the lastsignalId
it has sent. Signals with lowersignalId
values are considered older by the Signal Collection e-Service endpoint and raise an error when received.
9.5.2.2. Signal Distribution e-Service¶
Credential Issuers in the IT Wallet ecosystem use the Signal Distribution e-Service to:
check for changes in the status and/or value of a specific attribute associated with a Digital Credential issued by the Credential Issuer itself;
check for the availability of attributes related to a Digital Credential requested by a User.
The Signal Distribution e-Service endpoint is used by Credential Issuers to retrieve Signals from the Signal Hub via a Signal Distribution request. The latter MUST use an HTTP request using the method GET and the following parameters:
Path Parameters:
eserviceId
. REQUIRED. e-Service to which the Signal is bound. It MUST correspond to the e-Service Id value the Credential Issuer is a Consumer of.Query Parameters:
signalId
. OPTIONAL. Integer representing the last Signal number processed by the Credential Issuer. The Signal Distribution e-Service will respond with Signals having progressively greatersignalId
values. If not specified, the default value is the lowestsignalId
value available in the Signal Distribution e-Service.
size
. OPTIONAL. Integer representing the maximum number of Signals to be returned in the Signal Distribution response. If not specified, the default value is10
.Headers parameters: these are those described in Signal Hub pull.
If the Signal Distribution request is correctly processed, the e-Service will then respond with status code
HTTP 200 OK if the request is correctly formed and there are no more Signals to request;
HTTP 206 OK if the request is correctly formed but there are more Signals to request.
Regardless of the response code used, the response has Content-Type
set to application/json
an the header parameters indicated in Signal Hub pull. The body parameter lastSignalId
, referencing the signalId
of the last Signal transmitted by the Signal Distribution e-Service is added to the response's payload.
In Signal Hub pull can be found non normative examples of a Signal Distribution requests and responses.
If any error occurs during the request parsing, the response MUST adhere to the error format defined in Signal Hub pull-yaml.
Note
A complete OpenAPI Specification of the Signal Collection e-Service is available Signal Hub pull-yaml.
The Credential Issuer MUST implement the necessary logic to handle the Polling of the Signal Distribution e-Service endpoint, in doing this it has to consider the following aspects:
Signals are queried and retrieved per PDND e-Service, meaning that the Credential Issuer MUST implement a poll cycle for each e-Service ID;
the retention period of Signals in the Signal Hub is specified in Signal Hub Guide. Signals older than the specified retention period are not available for retrieval;
the Signal Hub does not keep track of the last
signalId
notified to a specific Credential Issuer. Each Credential Issuer MUST keep track of the lastsignalId
it has received for each PDND e-Service ID;the Signal Distribution e-Service endpoint returns Signals in batches. The maximal size the batch is specified in Signal Hub Guide. The Signal Distribution e-Service will indicate if additional Signals are available for retrieval.
9.5.3. Signals Processing¶
After the Signals have been successfully recovered by the Credential Issuer, the latter MUST process them as follows:
For each Signal, the Credential Issuer MUST check the
SignalType
value:
if the Signal
SignalType
isUPDATE
, the status and/or value of the attribute associated with a Digest Credential need updates;if the Signal
SignalType
isCREATE
, the requested attributes of a specific Digital Credential are now available;If the
objectId
does not correspond to any valid identifier known to the Credential Issuer, the Signal MUST be ignored. Otherwise, if it corresponds to a known and valid identifier, the Credential Issuer MUST use the Get Attribute Claims PDND endpoint of the Authentic Source to retrieve the updated information and, if applicable, apply the new status to the corresponding Credential.When the Signal has been processed, the Credential Issuer will either move to the next Signal and update its
signalId
counter; or, if there are no more Signals to process, it will resume the Pull cycle.
Warning
Given Signal Hub's currently supported security patterns, if the Authentic Source requires the AUDIT_REST_02 security pattern from the Credential Issuer, the latter MUST revoke the Digital Credential referenced in Signals with signalType
UPDATE
since it cannot contact the Authentic Source to retrieve the updated information without having authenticated the User before.