Discovering Dialogs Using the Link Header

LDP containers [[!LDP]] advertise their support for dialogs using the HTTP Link header [[!RFC8288]]. Each dialog type, creation or selection, has its own link relation.

The client discovers the dialogs by making an HTTP OPTIONS request on the container.

OPTIONS /bugs/ HTTP/1.1
Host: example.com

The server response contains a Link header with URLs to the dialog descriptors.

HTTP/1.1 204 No Content
Date: Thu, 12 Jun 2014 18:26:59 GMT
Allow: GET,POST,OPTIONS,HEAD
Accept-Post: text/turtle,application/ld+json
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type",
      <http://www.w3.org/ns/ldp#Resource>; rel="type",
      <http://example.com/dialogs/createBug>; rel="http://open-services.net/ns/core#creationDialog",
      <http://example.com/dialogs/selectBug>; rel="http://open-services.net/ns/core#selectionDialog"

The client then requests the dialog descriptor which contains an oslc:dialog property whose value is a link to the HTML dialog to be displayed.

GET /dialogs/selectBug HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: text/turtle
Transfer-Encoding: chunked

@prefix oslc:  <http://open-services.net/ns/core#> .
@prefix dcterms: <http://purl.org/dc/terms/> .

<>      a                  oslc:Dialog ;
        oslc:dialog        <http://example.com/dialogs/selectBug/form> ;
        oslc:hintHeight    "600px" ;
        oslc:hintWidth     "400px" ;
        oslc:label         "Select Bug" ;
        oslc:resourceType  <http://open-services.net/ns/cm#Bug> ;
        dcterms:title      "Select Bug from Product Z" .

Discovering Dialogs Using the Prefer Header

Clients can also use the HTTP Prefer header to find the dialogs for a container. The client makes an HTTP GET request on the resource URI using the return=representation preference [[!RFC7240]] and include parameter [[!LDP]] value http://open-services.net/ns/core#PreferDialog. The server responds with the dialog descriptors in the response body. Clients should also use include parameter value http://www.w3.org/ns/ldp#PreferMinimalContainer so that the response doesn't include unnecessary data.

The following example shows a container that supports creation and selection dialogs:

GET /bugs/ HTTP/1.1
Host: example.com
Accept: text/turtle
Prefer: return=representation;
        include="http://open-services.net/ns/core#PreferDialog http://www.w3.org/ns/ldp#PreferMinimalContainer"

HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ce291112"
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type",
      <http://www.w3.org/ns/ldp#Resource>; rel="type"
Accept-Post: text/turtle, application/ld+json
Allow: POST,GET,OPTIONS,HEAD
Preference-Applied: return=representation
Vary: Accept,Prefer
Transfer-Encoding: chunked

@prefix ex:    <http://example.com/vocab#> .
@prefix oslc:  <http://open-services.net/ns/core#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix ldp:   <http://www.w3.org/ns/ldp#> .

<http://example.com/bugs/>
        a                     ldp:BasicContainer ;
        oslc:creationDialog   <http://example.com/dialogs/createBug> ;
        oslc:selectionDialog  <http://example.com/dialogs/selectBug> ;
        dcterms:title         "Bugs Records for Product Z" .

<http://example.com/dialogs/createBug>
        a                  oslc:Dialog ;
        oslc:dialog        <http://example.com/dialogs/createBug/form> ;
        oslc:hintHeight    "600px" ;
        oslc:hintWidth     "400px" ;
        oslc:label         "New Bug" ;
        oslc:resourceType  <http://open-services.net/ns/cm#Bug> ;
        dcterms:title      "Report Bug (Product Z)" .

<http://example.com/dialogs/selectBug>
        a                  oslc:Dialog ;
        oslc:dialog        <http://example.com/dialogs/selectBug/form> ;
        oslc:hintHeight    "600px" ;
        oslc:hintWidth     "400px" ;
        oslc:label         "Select Bug" ;
        oslc:resourceType  <http://open-services.net/ns/cm#Bug> ;
        dcterms:title      "Select Bug (Product Z)" .

Discovering Dialogs Using the Service resource

Servers may also advertise their support for dialogs using the oslc:creationDialog and oslc:selectionDialog properties of the Service discovery resource.

The client discovers the dialogs by making a GET request on the Service resource and accessing these properties.

GET /serviceproviders/bugs/services.xml HTTP/1.1
Host: example.com
Accept: application/rdf+xml

The server response contains a Service resource which contains properties with URLs to the dialog descriptors.

HTTP/1.1 200 OK
Date: Thu, 12 Jun 2014 18:26:59 GMT
Content-Type: application/rdf+xml

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dcterms="http://purl.org/dc/terms/"
  xmlns:oslc="http://open-services.net/ns/core#">
<oslc:ServiceProvider rdf:about="https://example.com/serviceproviders/bugs/services.xml">
<oslc:creationDialog>
  <oslc:Dialog>
    <dcterms:title rdf:parseType="Literal">New Bug</dcterms:title>
    <oslc:label>Bug Change Request</oslc:label>
    <oslc:usage rdf:resource="http://open-services.net/ns/cm#requirementsChangeRequest"/>
    <oslc:resourceType rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
    <oslc:dialog rdf:resource="http://example.com/dialogs/createBug/form"/>
    <oslc:hintWidth>680px</oslc:hintWidth>
    <oslc:hintHeight>505px</oslc:hintHeight>
  </oslc:Dialog>
</oslc:creationDialog>
<oslc:selectionDialog>
  <oslc:Dialog>
    <dcterms:title rdf:parseType="Literal">Select Bug</dcterms:title>
    <oslc:label>Bug</oslc:label>
    <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
    <oslc:resourceType rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/>
    <oslc:dialog rdf:resource="http://example.com/dialogs/selectBug/form"/>
    <oslc:hintWidth>550px</oslc:hintWidth>
    <oslc:hintHeight>460px</oslc:hintHeight>
  </oslc:Dialog>
</oslc:selectionDialog>
</oslc:ServiceProvider>
</rdf:RDF>

The client then requests the dialog to display using the discovered URI in the oslc:dialog property in order to display the desired form.

GET /dialogs/selectBug/form HTTP/1.1
Host: example.com

The Client's Responsibilities

1. Open the dialog in a new window using the Window.open() method or embed the dialog in an iframe, setting iframe src to the URI of the dialog.
2. Add a message listener to receive messages from the dialog.
3. Listen for message events, ignoring unrecognized events from other sources or those not prefixed with oslc-response:
4. When message from the dialog indicates a completed action, free resources and handle the action.

    window.addEventListener("message", function(event) {
        // Make sure the message originated from the same origin as the dialog.
        if (event.origin !== "http://example.com") {
            return;
        }

        // Make sure the message starts with oslc-response:
        var message = event.data;
        if (message.indexOf("oslc-response:") !== 0) {
            return;
        }

        // Handle each result.
        var response = JSON.parse(message.substr("oslc-response:".length));
        var results = response["oslc:results"];
        for (var i = 0; i < results.length; i++) {
            var label = results[i]["oslc:label"];
            var uri = results[i]["rdf:resource"];
            // Handle resource...
        }

        // Remove the dialog from the page.
        var dialogContainer = document.getElementById('dialogContainer');
        dialogContainer.removeChild(dialogContainer.firstChild);
    }, false);

The Server's Responsibilities

1. Provide the dialog, an HTML page for resource creation or selection.
2. Allow the user to perform resource creation or selection.
3. Once the user has created or selected a resource or canceled the dialog, send notification using postMessage to the page's opener or parent window prefixed with "oslc-response:".

The following JavaScript code example shows how a dialog would send a response using postMessage, taking into account pages that the dialog might be in its own window or an iframe.

    function respondWithSelection(label, uri) {
        var response = {
            "oslc:results": [ {
                "oslc:label": label,
                "rdf:resource": uri
            } ]
        };
        (window.opener || window.parent).postMessage("oslc-response:" + JSON.stringify(response), "*");
    }

Prefill

Servers may support setting the initial values in a dialog. A client can test if a dialog supports prefill by making an HTTP OPTIONS request to the dialog descriptor URI. Prefill can be used with creation dialogs to provide a template of initial values. Clients can use prefill with selection dialogs to inform servers about the users desired content in the selection dialog.

OPTIONS /dialogs/createBug HTTP/1.1
Host: example.com

If the server supports prefill for this dialog, it includes POST among the methods in the Allow response header.

HTTP/1.1 204 No Content
Allow: GET,POST,HEAD,OPTIONS

To prefill content, clients POST the resource representation with the desired initial values to the delegated dialog descriptor URI.

POST /dialogs/createBug HTTP/1.1
Host: example.com
Content-Type: text/turtle
Transfer-Encoding: chunked

@prefix oslc_cm: <http://open-services.net/ns/cm#> .
@prefix dcterms: <http://purl.org/dc/terms/> .

<>
   a oslc_cm:Bug ;
   dcterms:title "Build 23 failed" ;
   oslc_cm:severity <http://example.com/enums#S1> .

The content of the request depends on the type of dialog and the server. Servers may describe constraints on POST content using ResourceShapes. The dialog descriptor uses property oslc:resourceShape for the shape constraints.

The server's response contains a Location header with the prefilled dialog's URI. The client uses this as the iframe src.

HTTP/1.1 201 Created
Location: http://example.com/dialogs/createBug/form/2zFy45

The client then uses the dialog URI from the Location like any other dialog. The dialog URI from a prefill request is often temporary. After a reasonable time, the server might respond with 404 Not Found or 410 Gone.

Security Issue: Clickjacking (UI redress attack)

Clickjacking is a vulnerability that can occur when a malicious (or compromised) web application embeds an OSLC delegated dialog in the application in such a way that the user is tricked into using their authenticated session with the dialog, believing that they are performing an operation other than the one indicated on the delegated dialog. The clickjacking application embeds it own web page in a way that means the dialog is not clearly visible to the user, either almost invisible, or hidden behind other components). When the user attempts to click on the visible components, the browser interprets this as a click on the obscured delegated dialog, and the components within it. The malicious web page encourages the user to click one of the visible components, which the user might believe will not have side-effects (such as a link saying "If you are not redirected within 2 seconds, click here"), but places that component over a component in the delegated dialog that the malicious page wishes the user to click unknowingly. The user attempts to click on the visible component, but the browser interprets that as a click on the hidden component, which will perform some action that the user is authorised to do (but the malicious web page is not) but that the user did not intend to perform.

This vulnerability requires that the user loads a malicious web page in their browser. This can happen in a number of ways, including:

• The user is tricked into loading the page directly, believing it to be trustworthy.
• A trusted page is compromised and "infected" to perform this attack.
• An OSLC server administrator is tricked into configuring their server to trust a malicious server. Their server then loads the malicious page as a delegated dialog or rich UI preview, which then embeds the page under attack in a further iframe.

There are always two pages involved in this attack; the "UI consumer" page (which has the iframe embedded within it), and the "UI provider" page (which gets loaded within the iframe). Consider the UI provider's server the "server under attack".

To protect against this attack:

1. When requesting the URL for the delegated dialog (from the ServiceProvider) or the UI preview (from the compact resource), the server under attack must require requests for the ServiceProvider to be authenticated. This authentication must be for the end-user, not for the client app itself. That is, access to the dialog URIs should be protected, as well as access to the dialogs themselves.
2. When returning a URL for the dialog or preview, the server under attack must return a URL that is specific to the authenticated user, and that cannot be guessed by merely knowing the user's username or ID.
3. When the server under attack receives a request for the dialog or preview URL itself (the request that is generated by the iframe to load the page to display within it), the server under attack must check that the URL that was requested is one that was generated for the same user that is requesting this page (i.e. the user that is identified by a session ID in the cookies sent with the request). This makes sure that the client can't get a URL for the dialog from one user that it is authenticated for, and use that to perform a clickjacking attack on another user that has not authorized that client.
4. If the users (for the URL and the cookie) do not match, then the server can either return with an HTTP error, or include an X-Frame-Options header with value SAMEORIGIN or DENY.

This is only required on dialogs or resource previews that contain controls that can be invoked with one or more clicks, and where those controls have side effects on the server. That is, if there are no controls on a preview, then there is no target for the malicious page to tick the user to click on.

By following these steps the server under attack knows that only clients that are able to authenticate against the server (e.g. for OAuth authentication they must have a valid client ID and - if required by the interaction pattern they're using - they must know the client secret), and that have also been authorized by the user to whom the the dialog is displayed, can display that dialog.

There are still some potential attack vectors:

• The server administrator could authorize a malicious client app.
• The user could authorize a malicious app to authenticate with the server under attack on their behalf.

But the exposure has been reduced as the attack cannot occur simply by loading a malicious web page in the user's browser. See the OWASP Clickjacking Defense Cheat Sheet for further information.