VERSION 1.0.1 MANDATORY
Contents
1. Introduction
This version of the OOTS includes support for an updated Evidence Preview Service feature. A component that implements the service is referred to using the term Preview Space. The Preview Service includes functionality for redirecting the user to a Preview Space on the side of the Evidence Provider and a return back to the Evidence Requester after completion of the preview steps. The service provides the possibility for preview of evidences by the user, re-authentication for record matching purposes and protection against identity swaps.
The requirement for the user to have the possibility for preview is specified in Article 14(3)(f) of the Single Digital Gateway Regulation, but is subject to exceptions based on Union or national law, according to article 14(5) of that regulation. The national law of this article 14(5) is the law in the Member State of the Evidence Requester, not the Member State of the Evidence Provider, as it relates to the Member State in which the user is executing the procedure.
The Once-Only Implementing Regulation, article 15(1)(b)(iii) specifies that preview is to be provided on the side of the Evidence Provider, not of the Evidence Requester. To be able to provide preview, the Evidence Provider needs to know whether or not preview is required. The Evidence Provider is not subject to the legislation of the Member State in which the Evidence Requester is based. It therefore needs to be informed about the requirement for preview by the Evidence Requester. Article 13(1)(k) of the IR and section 4.5.1 of these technical design documents specify that this information is provided using the Boolean "PossibilityForPreview" indicator in the evidence request.
Preview is a right for but not an obligation on the user. However, article 11(3) and 16 or the Implementing Regulation specify that the Evidence Provider may require re-authentication of the user. In addition to preview of evidences, the Preview Space also support re-authentication. This means that the user may be required to visit the Preview Space for re-authentication even if the request indicated that no preview possibility is needed.
The Preview Service has the following main features:
The service is provided by or on behalf of an Evidence Provider.
The service complements and supports the Data Service of the Evidence Provider.
A single Preview Space may serve more than one Data Service and more than one Evidence Provider.
A Data Service may use different Preview Spaces (for example, for different evidence types).
The operation of the preview service is linked to the regular processing of the Data Service as further detailed in 2 and 3 below.
The operation of the preview service is linked to the regular processing of the Online Procedure Portal as further detailed in 5 below.
The Preview Space may be implemented as an integrated feature of a Data Service component or as a standalone component.
Use of the service by a user for a particular evidence request is identified by a preview URL (Uniform Resource Locator). This URL is also the means for the user to access the service.
The preview URL shall be unique to the request and therefore to the user, requested evidence type, evidence requester and evidence provider that the request relates to. However, the specific format for the URL is up to the implementation.
The preview URL is communicated by the Data Service to the Online Procedure Portal, along with other preview metadata as described below in section 4, as a response to an initial evidence request.
- To retrieve evidences in situations involving preview, a second evidence request is issued to the Data Service. This request includes the Preview URL.
Any pieces of evidence selected for use in the procedure are returned by the Data Service to the Online Procedure Portal, as a response to a second follow-on request that includes a previously provided preview URL. This response is made after the user completes his or her interaction with the Preview Space for the specified URL.
The Preview Space may ask the user to re-authenticate himself or herself as an additional security control, complementing and confirming the prior authentication of the user on the side of the Online Procedure Portal. This is an implementation and/or policy decision.
The Preview Space may use re-authentication to help to uniquely identify the user, in case the identity attributes in the evidence request (based on the authentication of the user to the Online Procedure Portal) are not unique to a single person. It may be that, after re-authentication, it can be concluded that there are no pieces of evidence matching the identified user and that therefore there are no pieces of evidence to preview.
- The user should use the same eID for re-authentication to the Preview Space as he or she used to the Online Procedure Portal, in order to avoid mismatches in identity matching of the identity attributes in the request.
The Preview Space shall allow the user to decide, for each piece of evidence matching the evidence request, whether or not to use it in the procedure.
Before deciding whether or not to use a piece of evidence, the Preview Space shall offer the user the option to preview it. However, under the SDG regulation the user is not obliged to preview.
The details of user experience, interaction and user interfaces are out of scope for this specification but this does not affect interoperability.
- Any evidences selected by the user in the Preview Space are returned in an evidence response message. This message is a response to the second request message.
- As a result of a user decision not to use one or more pieces of evidence available for preview in the Preview Space , the number of pieces of evidences returned by the Data Service may be reduced.
- If there are no pieces of evidence to preview or if the user decides not to use any piece of evidence, the evidence response shall contain an empty registry object list.
- The Preview Space shall also facilitate the smooth navigation of the user back to the Online Procedure Portal to allow him or her to continue the online procedure that he or she was executing as described in section 5 below.
- After returning to the Online Procedure Portal, the user may need to re-authenticate if his or her login session expired.
The Preview Space, like all OOTS components, may be integrated indirectly, using integration middleware.
Some preview-related functionality of Online Procedure Portal, Data Service or Preview Space may be provided by Intermediary Platforms.
2. Evidence Preview Service Flow
The OOTS Preview feature consists of two separate but related evidence request-response message flows, executed in sequence. The first of these flows is a machine-to-machine flow, in which the response is to be returned immediately. The second of these flows occurs in parallel to an interactive preview browsing session. The response is only sent after completion of that session, which in many cases could be minutes after the request.
The following diagram includes an operation of preview feature and the expected processing of the Preview Space and Data Service. Some variations and exceptions are included and others explained in the summary table following the diagram. Note that some functionality may be provided by Intermediary Platforms (not shown in the diagram).
Step | Description | Notes |
1 | The procedure starts when the user, while executing an electronic procedure, is offered to use the OOTS to retrieve evidence. | This step is provided for context purposes only. The diagram omits the user authentication steps and the interaction with common services. |
2 | The evidence request is sent to the Data Service. | As a result of the preceding steps (authentication, interaction with common services), the Online Procedure Portal constructs a an evidence request containing a query:QueryRequest as specified in section 4.5.1. Unlike the similar evidence request in step 12, this request does not include the “PreviewLocation” Slot. |
3 | Upon receiving the request, the Data Service extracts the user identity attributes and may perform initial record matching and determine if any evidences may be available for the user. | Depending on capabilities of the Data Service, the Data Service may be able to query evidences based on the user's identity attributes or a subset of them and determine if any evidences associated with these attributes exist. Also depending on capabilities of the Data Service, or the capabilities of a Matching Service, it may be determined if re-authentication is needed. It may depend on the values of the eIDAS attributes or the absence or presence of optional eIDAS attributes. |
4 | No evidences are available for the subjects with the provided identity attributes: response set to empty list. | If the Data Service has the capabilities described under (3) above, and no evidences are associated with any data subject which has identity attribute values in the request, then use of the Preview Service is pointless. The Data Service can immediately reply to the evidence request by setting the list of registry objects to the empty list. No evidence is exchanged and no preview redirection is needed. For example, if a university has digitized, and made available for automatic exchange, its diplomas issued since a particular recent date, then a simple check on "DateOfBirth" could help users who graduated before the start of digitization avoid a pointless redirection and re-authentication to the Preview Space. Note that this is independent of the value of the "PossibilityForPreview" flag. After this step, the Data Service can proceed immediately to step 27. |
5 | Data subject is identified unambiguously, evidences are available, no preview or re-authentication required. | If the flag "PossibilityForPreview" is set to false and the data subject is unambiguously defined, the Data Service may immediately return the evidence. No use of the Preview Service is required. As an example, some company data is public, so the evidence is not sensitive information. Some Member States using legal person identities use the company registration number as eIDAS "Unique Identifier", so the identity is unambiguous. No preview or re-authentication are needed. The evidence can be returned immediately. After this step, the Data Service can proceed immediately to step 27. |
6 - 26 | Preview is required and/or re-authenticated is required | If the flag "PossibilityForPreview" is set to true, or if the data subject identity is not uniquely matched, the Preview Service is needed. If the flag "PossibilityForPreview" is set to true and the data subject is unique matched, the Data Service MUST NOT return the evidence without use of the Preview Service. |
6, 8 | The Data Service and the Preview Service prepare and coordinate for the evidence preview. | In these steps, a unique preview URL is generated and shared between the Preview Space and the Data Service. This serves to allow the two services to synchronize their operation in the second flow. Therefore the URL MUST be uniquely linked to the evidence request. |
8 | The Preview Service stores data. | Data is to be stored to prepare the Preview Space for the visiting user and to allow identity matching and request validation. Stored data should include:
Alternatively, the data could be stored by the Data Service and retrieved (see step 11) by the Preview Space, or in a separate component. |
9 | The preview URL is returned to the Online Procedure Portal | The message format is that of an evidence error response message, see section 4.5.3, where:
|
10, 11 | The Online Procedure Portal informs the user that the Data Service indicated that he or she needs to navigate to the Preview Space. | This can be done by presenting a clickable hyperlink, derived from the "PreviewLocation" and "PreviewMethod" as described in section 4 below. If provided, the content of the "PreviewLocationDescription" slot can be used in the link. The Online Procedure Portal can filter the natural language alternatives to match its presentation language or (if known) user preference. |
12-28 | The second request-response flow is executed. | In parallel, the user interacts with the Preview Space. |
12 | The Online Procedure Portal sends a second evidence request. | For all rim:Slots except IssueDateTime, this evidence request have the same content as the first request. The eDelivery message that carries the request should have the same values for conversation identifier and other values. In addition to this, unlike the evidence request in step 2, this request does include the rim:Slot “PreviewLocation”. Its content is that of the rim:Slot “PreviewLocation” in the first response exchanged in step 6. The content is an exact copy of the preview URL as returned in the error response message. The slot therefore does not include the return URL. This request shall not contain any "PreviewMethod" or "PreviewLocationDescription" slots. The receiving Data Service should validate this and return an error if validation fails, and alert the Preview Space. While the diagram show this step as preceding the user redirection of step (10), the request may be delayed due to operational circumstances. However, this is not an issue as the request is only needed to allow generation of a second response (in step 22), which in practice will be many seconds if not minutes later. |
13 | The user follows the link to the Preview Service. | The link should include the return URL and HTTP method as described in section 5 below. If not provided, or the link is not using the https scheme, the user should be informed as there may be no (secure) way for the user to return. |
14 | Retrieve and validate data | Using the data from the initial request, stored in step 4, the Preview Service determines that the link has not expired and obtain data from the original request, including user identity attributes. If the link has expired, or expires while the user is using the Preview Service (not shown), the Preview Service shall inform the user. It shall also, through the Data Service, return an evidence error message of type rs:TimeoutExceptionType to cancel the second request sent under step 9. |
15-20 | Re-authentication is required | |
15-17 | The user is identified | While the preview URL should be unique, is exchanged securely to the Online Procedure Portal and should only be known to the user, proof of knowledge of the URL may be deemed insufficiently secure. Furthermore, the identity attributes in the original request may not uniquely identify the data subject. Therefore, the Preview Space may re-authenticate the user using either a national eID of the Evidence Provider Member State, or using eIDAS nodes. If re-authentication fails, the Preview Space should:
If the identity attributes of the user as expressed in the original request (steps 2, 4, 11 above) do not match the attributes obtained from the national re-authentication, the Preview Space should:
By setting a cookie, the Preview Space can recognize repeat visits of a user, such as following separate preview links relating to separate queries to the same procedure and user session and obviate the need for repeated authentications. |
18 | Match identity to identity attributes in the request | As specified in chapter 2.1.3.2, there is a requirement to check that the identity as established during re-authentication matches the identity expressed using attributes in the evidence request. |
19-20 | Handle failure of identity swap checks. | If identity swap check fails then, instead of any evidences, an error response is generated using an Exception of type AuthenticationExceptionType , “Failed Authentication”, error code EDM:ERR:0001. The user does not get access to any evidences but instead is to return to the Evidence Requester (step 26). |
16, 17 | Find (list of) piece(s) of evidence | Now that the user is successfully and uniquely authenticated, the list of pieces of evidence for the user for the selected type of evidence for the selected evidence provider can be retrieved for preview. In the diagram, this is done by using the Data Service as a back-end to the Preview Space, but this is an implementation-specific choice. Note that this list can be the empty list. |
21-23 | Interact with user | If there are pieces of evidence available for preview, the Preview Space interacts with the user, allowing him or her to decide which if any pieces of evidence to preview and/or use in the procedure. |
24, 25 | Provide decision | Once the user has made his or her decision, this is relayed to the Data Service. The selected pieces of evidence (if any) are packaged in an evidence response message as defined in section 4.5.2. |
26 | Return user | In parallel, the Preview Space presents a return link that allows the user to return to the Online Procedure Portal. The link is constructed from the return URL as described in section 5 below. The return URL only provides access in the context of a valid authenticated user session. |
| 27, 28 | Construct evidence response and send using eDelivery | This step requires the second evidence request (step 9) to have been received and processed successfully. The response query:QueryResponse/@requestId is set to the query:QueryRequest/@id of the request. |
29 | Complete exchange | Once returned, the user can continue his or her procedure. |
3. Coordination of Evidence Preview Service and Data Service
The Evidence Preview Service and the Preview Space that implements it shall coordinate their operation with the Evidence Query Service functionality of the Data Service. The details of this are up to the implementation of the two services but shall meet the following requirements:
For the purposes of the OOTS, the Preview Service only exists to support the Data Service.
For evidence requests that do not contain a preview URL, the Data Service and the Preview Service shall establish a preview URL. The format of the URL is described in section 4 below. The Data Service shall return the preview URL as defined under step 5 in the diagram in section 3 above.
The Preview Space shall only allow access for preview URLs that it issued and communicated to the Online Procedure Portal and the user using an evidence error response message as described under section 2.
The Preview Space and Data Service shall agree on any timeout values after which previously issued preview URLs are no longer valid. In particular, any time limits on access to the Preview Service for an evidence request shall not exceed the timeout intervals of the Data Service.
Access to the Evidence Preview Service for a particular set of pieces of evidence of a specific type shall be limited to users of OOTS and shall be available only after a request for evidence of that type has been made to a Data Service.
When the Data Service provides a response to an evidence request, the response shall include all and only those pieces of evidence that the user decided to use. This selection is made to the Preview Space and communicated to the Data Service.
Within timeout intervals, the Data Service shall not provide an evidence response to the evidence request before the user has decided whether or not to use any matching piece of evidence.
4. Preview Location Metadata
Preview Location Metadata is provided by the Data Service (in coordination with the Preview Service) to the Online Procedure Portal, as content of the following three slots in the rs:Exception in the the evidence error response:
A mandatory Slot “PreviewLocation” with a rim:SlotValue of type rim:StringValueType. This Slot provides the URL of the server on which the Preview Space is available for preview related to the evidence request. This slot is reused in the second evidence request message.
A mandatory Slot “PreviewMethod” with a rim:SlotValue of type rim:StringValueType. Its value encoded the HTTP method to be used to access the preview location. Recommended values are GET or POST. For backwards compatibility, PUT should be supported. The value is insensitive.
An optional Slot “PreviewLocationDescription” with a rim:SlotValue of type rim:InternationalStringType. This provides additional descriptions, in possibly multiple natural languages, of the preview location. At a minimum, a description should be provided in an official language of the Union that is broadly understood by the largest possible number of cross-border users.
The specific format for the preview URL, as communicated by the Data Service to the Online Procedure Portal, is up to the implementation of the Preview Space, but shall meet the following requirements:
The URL shall specify secure HTTP (“https://”) as transport. The use of "http://" URIs is not allowed.
- The URL shall not include a fragment component (see RFC 3986 section, 3.5).
- The URL may include a query component (see RFC 3986 section, 3.5). A query component is indicated by the first question mark ("?") character and terminated by the end of the URI. The content shall consist of "key-value" pairs, separated by the "&" symbol. This is the format used by HTML links and used by forms using the GET method to transport form inputs. There shall be no different key=value pairs in a query component that use the same key. The order of key=value pairs shall not be significant. Values shall not contain spaces.
- To be able to safely transmit the preview URL in the XML error response, unsafe characters need to be encoded using XML encoding. For example, a preview URL for use with the GET method could include multiple parameters and their values, and therefore include the & character. This character shall be encoded using a & character reference.
- To be able to safely transmit in REST queries a query component that includes a return URL as value for the returnurl parameter, unsafe characters shall be plus quote-encoded. For example, the substring https:// is to be quoted as https%3A%2F%2F.
- The URL shall be unique to the request and therefore to the request parameters including the user identity attributes, requested evidence type, evidence requester and evidence provider that the request relates to.
The URL shall not include query parameters with the names “returnurl” or “returnmethod”. This is because parameters with those names are appended by the Online Procedure Portal as described in section 5 below.
- The URL should be unpredictable. This can be done by including a random version 4 UUID (RFC 4122) text value in the component part.
The Preview Space shall apply the following minimal access life-cycle policy on preview URLs:
- URLs shall not be accessible before the related first loop evidence request has been received by the Data Service.
- Users shall be able to access the URL using a Web browser (user agent) for a time-limited period after the URL has been made accessible and transmitted back to the Online Procedure Portal.
- Once the user successfully finishes using the Preview Space for the accessed URL, i.e. he of she has confirmed to have finished previewing any associated pieces of evidence, decided whether or not to use them, and completed any other activities, the outcome shall be considered final and communicated to the Data Service. If the user (or anyone else) revisits the URL after such a previous successful access, he or she will not be able to restart the Preview Space interaction.
- If the user has accessed the Preview Space for the accessed URL, but not successfully finished his or her interaction for this URL, and the URL has not yet timed out, he or she shall be allowed to revisit the link.
- The URL will cease to be accessible after its expiration.
5. Coordination of Evidence Preview Service and Online Procedure Portal
To support preview, the Online Procedure Portal needs to provide the following functionality:
Recognize, in the first flow, evidence error response messages of type rs:AuthorizationExceptionType that contain a “PreviewLocation” slot as indications of the use of the Preview Space.
Provide a departure page for the user to navigate to the Preview Space.
Process the language specific information of the preview location description metadata to allow the launch page to be customized to the user’s language choice (if known).
Provide a return address URI to which the user can return after completing his or her interaction with the Preview Space.
- If the value of PreviewMethod is GET:
- Add the return address, in encoded form, as a value of the “returnurl” query parameter, in the preview URL prior to presenting the link to the user. This allows the Preview Space to return to the Online Procedure Portal, when finished previewing.
Also add the HTTP method of the return address, as a value of the “returnmethod” query parameter in the preview URL. The allows the Preview Space to return the user to the Online Procedure Portal, when finished previewing, using the appropriate method.
- The body of the GET request is empty.
- If the Preview URL included a query component, the two key=value pairs are appended to the existing query component. If the Preview URL did not include a query component, a query component consisting of the two key=value pairs is added to the URL.
- If the value of PreviewMethod is PUT or POST:
- Add a Content-Type request header with value application/x-www-form-urlencode.
- Include the URL encoded query component in the request body.
- Calculate the length of the body and set the Content-Length HTTP request header accordingly.
- Confirm that the user accessing the Online Procedure Portal using the return URL is the user that is executing the associated procedure. If the login session of the user at portal has expired while he or she was away, using the preview service, the user must be re-authenticated.
To allow the user to return back from from the Preview Space to the Online Procedure Portal, the provided returnurl and returnmethod values and return method shall be created and processed analogously to how the PreviewLocation and PreviewMethod values are used to navigate to the Preview Space. The returnmethod is used to determine the method to be used to return the user. Since there are no query parameters, even with PUT or POST methods the body is empty and no Content-Type header is set.
Note that the return URL is only communicated as part of the user flow towards the Preview Space. It is not appended to the URL content of the "PreviewLocation" slot in the second evidence request message.
The format of the return address URI shall follow the requirements for the preview URL as specified in section 4 above.
The Online Procedure Portal shall apply the following minimal access life-cycle policy on return URLs:
- Return URLs shall not be accessible before the second request is issued and the user is presented a link to the preview space.
- Users shall be able to access the URL using a Web browser (user agent) for a time-limited period.
- The URL will cease to be accessible after its expiration.
6. Optimizing Preview for Multiple Evidence Requests (Informative)
When executing an online procedure and using the OOTS, a user may want to retrieve multiple pieces of evidence. For example, a student may want to make available two diplomas that he or she obtained from different universities. This may result in two parallel evidence requests being sent to two different Data Services, in response to which two separate preview URLs for the two requests may be returned to the Online Procedure Portal.
In implementing OOTS, some Member States intend to implement a shared Preview Space service that can be used by multiple Data Services. If the two universities that issued the two diplomas to the student both use the shared service, the generated preview URLs, while different, will link the user to the same Preview Space. The Preview Space may optimize the user experience by establishing a user session (using cookies) when the user accesses the first preview URL and authenticates himself or herself to the Preview Space. This obviates the need for the user to authenticate again when he or she follows the second preview URL. Whether or not a Preview Space supports this feature is implementation-specific and out of scope for this specification.
7. References
Regulation (EU) 2018/1724 of the European Parliament and of the Council of 2 October 2018 establishing a single digital gateway to provide access to information, to procedures and to assistance and problem-solving services and amending Regulation (EU) No 1024/2012 (Text with EEA relevance.).
https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=uriserv:OJ.L_.2018.295.01.0001.01.ENG.
COMMISSION IMPLEMENTING REGULATION (EU) /... setting out technical and operational specifications of the technical system for the cross-border automated exchange of evidence and application of the "once-only" principle in accordance with Regulation (EU) 2018/1724 of the European Parliament and of the Council. C/2022/5628 final. https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=PI_COM%3AC%282022%295628
RFC 3986. Uniform Resource Identifier (URI): Generic Syntax. https://datatracker.ietf.org/doc/html/rfc3986.
RFC 4122. A Universally Unique IDentifier (UUID) URN Namespace. https://datatracker.ietf.org/doc/html/rfc4122