## Notices

Copyright © OASIS Open 2021. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This specification is published under the Attribution 4.0 International (CC BY 4.0). Portions of this specification are also provided under the Apache License 2.0.

All contributions made to this project have been made under the OASIS Contributor License Agreement (CLA).

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Open Projects IPR Statements page.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Open Project or OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Project Specification or OASIS Standard, to notify the OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Open Project that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Open Project Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

## Table of Contents

## 1. Introduction

This section is non-normative.

OSLC specifications target specific integration scenarios. In some cases, allowing one application to delegate to a user interface defined in another application is a more effective way to support a use case than an HTTP interface that can only be accessed programmatically. There are two cases where this is especially true:

- Resource creation: when a user of a web application needs to create a new resource in another application. In this case, the web application asks the other server to provide a UI for resource creation, and the server notifies the application when the creation has been completed or canceled by the user.
- Resource selection: when a user of a web application needs to pick a resource managed by another application. In this case, the web application asks the other server to provide a UI for resource selection, and the server notifies the application when a resource or resources has been selected or if the selection was canceled.

Delegated dialogs support these two cases. They allow one application to embed a creation or selection UI into another using HTML `iframe` elements and JavaScript code.

Fig. 1 Creation Dialog

Fig. 1 Creation Dialog depicts what a defect creation dialog might look like inside a quality management tool, displayed when the user clicks the Open Bug button. The dialog content itself comes from the change management tool, running on another server. The dialog displays seamlessly inside the quality management application, however, while retaining the change management tool's look and feel and capabilities.

Delegated dialogs provide a simple way for an end user to create or select resources from another application, thus eliminating the need to rebuild the other application's dialog and its application logic.

### 1.1 Terminology

Terminology uses and extends the terminology and capabilities of OSLC Core Overview, W3C Linked Data Platform [LDP], W3C's Architecture of the World Wide Web [WEBARCH], and Hyper-text Transfer Protocol [HTTP11].

The following terms are used in discussions of dialogs:

Dialog
  A web page for creating or selecting resources to be embedded inside another application.
Dialog Descriptor
  A resource that describes information about a dialog such as its title and dimensions. In RDF representations, the dialog descriptor has RDF type `oslc:Dialog`. See 5. Resource Constraints.
Prefill
  A method of setting initial field values in a creation dialog.

### 1.2 References

#### 1.2.1 Normative references

[CSP]
  M. West; A. Barth; D. Veditz. Content Security Policy Level 2. W3C. W3C Recommendation. URL: https://www.w3.org/TR/CSP2/
[CSS21]
  Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. W3C, 7 June 2011. W3C Recommendation. URL: https://www.w3.org/TR/CSS21/
[HTTP11]
  R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. IETF, June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[LDP]
  Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. W3C, 26 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/ldp/
[OSLCCore2]
  S. Speicher; D. Johnson. OSLC Core 2.0. http://open-services.net. Finalized. URL: http://open-services.net/bin/view/Main/OslcCoreSpecification
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. IETF, March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3986]
  T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. IETF, January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC5988]
  M. Nottingham. Web Linking. IETF, October 2010. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5988
[RFC7240]
  J. Snell. Prefer Header for HTTP. IETF, June 2014. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7240
[RFC8174]
  B. Leiba. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. IETF, May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8259]
  T. Bray, Ed.. The JavaScript Object Notation (JSON) Data Interchange Format. IETF, December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259
[RFC8288]
  M. Nottingham. Web Linking. IETF, October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
[whatwg-web-messaging]
  WHATWG contributors. HTML. Part 9.4: Cross-document messaging. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/web-messaging.html#web-messaging

#### 1.2.2 Informative references

[WEBARCH]
  Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. W3C, 15 December 2004. W3C Recommendation. URL: https://www.w3.org/TR/webarch/

### 1.3 Typographical Conventions and Use of RFC Terms

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

## 2. Discovering Dialogs

This section is non-normative.

Clients can discover dialogs in three ways:

- 2.1 Discovering Dialogs Using the Link Header
- 2.2 Discovering Dialogs Using the Prefer Header
- 2.3 Discovering Dialogs Using the Service resource

### 2.1 Discovering Dialogs Using the Link Header

This section is non-normative.

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.

Dialog Type | Link Relation
--- | ---
Creation | `http://open-services.net/ns/core#creationDialog`
Selection | `http://open-services.net/ns/core#selectionDialog`

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

Example 1: An 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.

Example 2: Response with Dialog Link Headers

    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.

Example 3

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

Example 4

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

### 2.2 Discovering Dialogs Using the Prefer Header

This section is non-normative.

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:

Example 5

    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"

Example 6

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

### 2.3 Discovering Dialogs Using the Service resource

This section is non-normative.

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.

Example 7: An OPTIONS Request on the Container

    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.

Example 8: Service Resource

    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.

Example 9

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

## 3. Using Dialogs

This section is non-normative.

Servers can offer two kinds of dialogs, selection dialogs and creation dialogs. Clients use selection dialogs when they want a user to pick a resource from another application. They use creation dialogs when they want a user to create a new resource in another application.

A client can open the dialog in a new browser window, or it can embed the dialog in another page by creating an `iframe` element and setting the `src` attribute to the URI of the dialog to be included.

Example 10: Display a Dialog

    var iframe =
           document.createElement("iframe");
       iframe.style.border = 0;
       iframe.style.width = "600px";  // or preferred dialog width
       iframe.style.height = "400px"; // or preferred dialog height
       iframe.src = "http://example.com/dialogs/createBug/form";
       document.getElementById("dialogContainer").appendChild(iframe);

Clients might choose to place dialogs inside page elements styled to look like a dialog window.

Fig. 2 Dialog iframe

The `iframe` itself, outlined in Fig. 2 Dialog iframe, contains the dialog content from the server.

Dialogs send results back to the client using the HTML5 function `Window.postMessage` [whatwg-web-messaging]. `postMessage` is called on `window.opener` if set. Otherwise, `postMessage` is called on `window.parent`.

When embedded in an `iframe`, dialogs may also request to be resized dynamically. These requests are the same as specified in OSLC Resource Preview and also use `postMessage`. Clients can distinguish between results and resize messages from the message prefix. Messages have the following prefixes:

Message Prefix | Meaning
--- | ---
`oslc-response:` | The user has created or selected resources or canceled the dialog.
`oslc-resize:` | The dialog is asking to be resized.

A stringified JSON object will be concatenated to the message prefix. For dialog responses, the JSON is described by Appendix A. Dialog Results JSON. It is a JSON object with an `oslc:results` array of results. Each result is a JSON object with an `rdf:resource` property whose value is the resource URI. The result may also have an `oslc:label` that can be useful for client to display a label for the delegated dialog.

Example 11: Dialog Results Message

    oslc-response:{"oslc:results":
      [{ "oslc:label": "bug 123: server crash", "rdf:resource": "http://example.com/bug123" }]}

An empty array indicates the dialog was canceled.

For resize requests, the JSON is an object with an `oslc:hintHeight` property, an `oslc:hintWidth` property, or both.

Example 12: Dyanmic Resize Message

    oslc-resize:{"oslc:hintHeight": "277px", "oslc:hintWidth": "400px"}

### 3.1 The Client's Responsibilities

This section is non-normative.

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.

Example 13: Listen for Dialog Results

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

### 3.2 The Server's Responsibilities

This section is non-normative.

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

Example 14

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

### 3.3 Prefill

This section is non-normative.

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.

Example 15

    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.

Example 16

    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.

Example 17: Prefilling a Bug Creation Dialog

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

Example 18: The Server Responds with the Dialog Location

    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.

### 3.4 Security Issue: Clickjacking (UI redress attack)

This section is non-normative.

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.

## 4. Implementation Conformance

### 4.1 Discovery

In responses to successful HTTP requests for an LDP container that has a selection dialog, server MUST include a `Link` header [RFC5988] where:

- The context URI is the effective request URI,
- The link relation is `http://open-services.net/ns/core#selectionDialog`, and
- The target URI is the URI of the selection dialog descriptor.

[DD-1]
Example 19

    Link: <http://example.com/dialogs/selectBug>; rel="http://open-services.net/ns/core#selectionDialog"

In responses to successful HTTP requests for an LDP container that has a creation dialog, server MUST include a `Link` header [RFC5988] where:

- The context URI is the effective request URI,
- The link relation is `http://open-services.net/ns/core#creationDialog`, and
- The target URI is the URI of the creation dialog descriptor.

[DD-2]
Example 20

    Link: <http://example.com/dialogs/createBug>; rel="http://open-services.net/ns/core#creationDialog"

Clients MAY request that the dialog descriptors for an LDP container are returned inline using the `Prefer` request header [RFC7240] with:

- Preference `return`, value `representation`
- Parameter `include` [LDP], value `http://open-services.net/ns/core#PreferDialog`.

[DD-3]
Example 21: Example Prefer Header

    Prefer: return=representation; include="http://open-services.net/ns/core#PreferDialog"

Servers MUST honor a client's request to inline dialog descriptors if the target resource has any dialog descriptors and the request is successful. [DD-4]

Servers MUST express the `oslc:hintWidth` and `oslc:hintHeight` properties of an `oslc:Dialog` in length units as specified in [CSS21]. [DD-5]

In responses to HTTP GET requests targeting resources that have dialogs, servers SHOULD either include a `Vary` response header with at least `Accept` and `Prefer` field values or a `Cache-Control` header value `no-store`. [DD-6]

Servers MAY also provide delegated dialog discovery using the ServiceProvider and Service resource and the `oslc:creationDialog` and `oslc:selectionDialog` properties. [DD-7]

### 4.2 Display

When embedding a dialog inside another web page, the client MUST use an `iframe` element and set the its `src` attribute to the URI of the dialog. [DD-8]

In order to allow the dialogs to be loaded on another webpage, the server SHOULD allow embedding dialogs on trusted domains by following the [CSP] specification. [DD-9]

### 4.3 Messaging

Servers MUST support the `Window.postMessage` method [whatwg-web-messaging] for dialog responses. [DD-10]

Servers MAY support the Window Name Protocol defined in [OSLCCore2] for backward compatibility with OSLC 2.0 clients that use that protocol. [DD-11]

Servers MAY support other protocols for dialog responses not specified in this document, which clients request by appending a fragment identifier [RFC3986] describing the protocol to the end of the dialog URI. [DD-12]

Servers MUST use `postMessage` for dialog responses if a client has not added a fragment identifier to the dialog URI, or the fragment identifier is `#oslc-core-postMessage-1.0`. [DD-13]

Messages describing dialog results MUST start with the characters `oslc-response:` followed by JSON as specified in Appendix A. Dialog Results JSON. [DD-14]

Example 22

    oslc-response:{"oslc:results":
      [{ "oslc:label": "bug 123: server crash", "rdf:resource": "http://example.com/bug123" }]}

Servers MAY include additional server-specific properties in the results JSON. [DD-15]

If the user cancels a dialog, the dialog MUST still send a message with an empty `oslc:results` array. [DD-16]

Example 23

    oslc-response:{"oslc:results": []}

Calls to `postMessage` from within a dialog MUST be made on `window.opener` unless `null` or `undefined`. [DD-17]

If `window.opener` is `null` or `undefined`, calls to `postMessage` MUST be made on `window.parent`. [DD-18]

Example 24

    (window.opener || window.parent).postMessage("oslc-response:" + response, "*");

Clients handling `message` events from dialogs MUST verify that the event `origin` is the same as the dialog. [DD-19]

For example, if the dialog is from example.com,

Example 25

    function handleMessage(event) {
        if (event.origin !== "http://example.com") {
            return;
        }

        // Otherwise, process message...
    }

Dialogs MAY support dynamic resizing as specified in OSLC Resource Preview. [DD-20]

Clients MUST anticipate other, unrelated uses of `postMessage` and ignore unrecognized messages not conforming to the protocol. [DD-21]

### 4.4 Prefill

Servers MAY support prefill for creation and/or selection dialogs. Client provided prefill information, either in a request entity body or query parameters is intended to inform servers of possible initial values for creation dialogs, or the preferred content of selection dialogs. Clients SHOULD NOT assume any specific content or URL format. [DD-22]

Servers MAY allow clients to prefill dialogs by accepting HTTP POST requests where the Request-URI is the dialog descriptor and the entity body is an entity describing the initial values. [DD-23]

Servers that support prefill MUST include the value `POST` in the set of `Allow` header values returned in response to HTTP OPTIONS requests for the dialog descriptor URI. [DD-24]

Example 26

    Allow: GET,POST,HEAD,OPTIONS

Servers MAY describe prefill constraints by adding an `oslc:resourceShape` property to the dialog descriptor whose value is a resource shape URI. [DD-25]

Servers MUST NOT reject prefill requests on creation dialogs solely because they are missing required fields for the resource. Users can fill in the missing values in the dialog. [DD-26]

On successful prefill requests, servers MUST respond with status code 201 (Created) and a `Location` header whose value is the URI of the prefilled dialog. [DD-27]

After some elapsed time, servers MAY respond with a 404 (Not Found) or 410 (Gone) to an HTTP GET request for a prefilled dialog URI. [DD-28]

Servers MAY support prefill by adding initial values as query parameters to the delegated dialog URI. Clients SHOULD NOT assume any specific URL format, however. [DD-29]

## 5. Resource Constraints

This document applies the following constraints to the Core vocabulary terms.

An OSLC server providing Dialog capability MUST implement the vocabulary defined in this section. [DD-30]

- Describes: `http://open-services.net/ns/core#Dialog`
- Summary: Describes information about a dialog such as its title and dimensions.

Dialog Properties

Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description
--- | --- | --- | --- | --- | --- | ---
`dcterms:title` | Exactly-one | true | XMLLiteral | N/A | Unspecified | Title string that could be used for display.
`oslc:dialog` | Exactly-one | true | unspecified | Either | Unspecified | The URI of the dialog.
`oslc:hintHeight` | Zero-or-one | true | unspecified | Either | Unspecified | Recommended height of the dialog. Values are expressed using length units as specified in [CSS21].
`oslc:hintWidth` | Zero-or-one | true | unspecified | Either | Unspecified | Recommended width of the dialog. Values are expressed using length units as specified in [CSS21].
`oslc:label` | Zero-or-one | true | string | N/A | Unspecified | Very short label for use in menu items.
`oslc:resourceShape` | Zero-or-many | true | Resource | Reference | `oslc:ResourceShape` | Describes constraints on dialog prefill requests.
`oslc:resourceType` | Zero-or-many | true | Resource | Reference | `rdfs:Class` | The expected resource type URI for the resources that will be returned when using this dialog. These would be the URIs found in the result resource's `rdf:type` property.
`oslc:usage` | Zero-or-many | true | Resource | Reference | Unspecified | An identifier URI for the domain specified usage of this dialog. If a resource has multiple uses, it may designate the primary or default one that should be used with a property value of oslc:default.

## 6. Conformance

Implementations of this specification need to satisfy the following conformance clauses.

Clause Number | Requirement
--- | ---
DD-1 | In responses to successful HTTP requests for an LDP container that has a selection dialog, server MUST include a `Link` header [RFC5988] where: The context URI is the effective request URI, The link relation is `http://open-services.net/ns/core#selectionDialog`, and The target URI is the URI of the selection dialog descriptor.
DD-2 | In responses to successful HTTP requests for an LDP container that has a creation dialog, server MUST include a `Link` header [RFC5988] where: The context URI is the effective request URI, The link relation is `http://open-services.net/ns/core#creationDialog`, and The target URI is the URI of the creation dialog descriptor.
DD-3 | Clients MAY request that the dialog descriptors for an LDP container are returned inline using the `Prefer` request header [RFC7240] with: Preference `return`, value `representation` Parameter `include` [LDP], value `http://open-services.net/ns/core#PreferDialog`.
DD-4 | Servers MUST honor a client's request to inline dialog descriptors if the target resource has any dialog descriptors and the request is successful.
DD-5 | Servers MUST express the `oslc:hintWidth` and `oslc:hintHeight` properties of an `oslc:Dialog` in length units as specified in [CSS21].
DD-6 | In responses to HTTP GET requests targeting resources that have dialogs, servers SHOULD either include a `Vary` response header with at least `Accept` and `Prefer` field values or a `Cache-Control` header value `no-store`.
DD-7 | Servers MAY also provide delegated dialog discovery using the ServiceProvider and Service resource and the `oslc:creationDialog` and `oslc:selectionDialog` properties.
DD-8 | When embedding a dialog inside another web page, the client MUST use an `iframe` element and set the its `src` attribute to the URI of the dialog.
DD-9 | In order to allow the dialogs to be loaded on another webpage, the server SHOULD allow embedding dialogs on trusted domains by following the [CSP] specification.
DD-10 | Servers MUST support the `Window.postMessage` method [whatwg-web-messaging] for dialog responses.
DD-11 | Servers MAY support the Window Name Protocol defined in [OSLCCore2] for backward compatibility with OSLC 2.0 clients that use that protocol.
DD-12 | Servers MAY support other protocols for dialog responses not specified in this document, which clients request by appending a fragment identifier [RFC3986] describing the protocol to the end of the dialog URI.
DD-13 | Servers MUST use `postMessage` for dialog responses if a client has not added a fragment identifier to the dialog URI, or the fragment identifier is `#oslc-core-postMessage-1.0`.
DD-14 | Messages describing dialog results MUST start with the characters `oslc-response:` followed by JSON as specified in Appendix A. Dialog Results JSON.
DD-15 | Servers MAY include additional server-specific properties in the results JSON.
DD-16 | If the user cancels a dialog, the dialog MUST still send a message with an empty `oslc:results` array.
DD-17 | Calls to `postMessage` from within a dialog MUST be made on `window.opener` unless `null` or `undefined`.
DD-18 | If `window.opener` is `null` or `undefined`, calls to `postMessage` MUST be made on `window.parent`.
DD-19 | Clients handling `message` events from dialogs MUST verify that the event `origin` is the same as the dialog.
DD-20 | Dialogs MAY support dynamic resizing as specified in OSLC Resource Preview.
DD-21 | Clients MUST anticipate other, unrelated uses of `postMessage` and ignore unrecognized messages not conforming to the protocol.
DD-22 | Servers MAY support prefill for creation and/or selection dialogs. Client provided prefill information, either in a request entity body or query parameters is intended to inform servers of possible initial values for creation dialogs, or the preferred content of selection dialogs. Clients SHOULD NOT assume any specific content or URL format.
DD-23 | Servers MAY allow clients to prefill dialogs by accepting HTTP POST requests where the Request-URI is the dialog descriptor and the entity body is an entity describing the initial values.
DD-24 | Servers that support prefill MUST include the value `POST` in the set of `Allow` header values returned in response to HTTP OPTIONS requests for the dialog descriptor URI.
DD-25 | Servers MAY describe prefill constraints by adding an `oslc:resourceShape` property to the dialog descriptor whose value is a resource shape URI.
DD-26 | Servers MUST NOT reject prefill requests on creation dialogs solely because they are missing required fields for the resource. Users can fill in the missing values in the dialog.
DD-27 | On successful prefill requests, servers MUST respond with status code 201 (Created) and a `Location` header whose value is the URI of the prefilled dialog.
DD-28 | After some elapsed time, servers MAY respond with a 404 (Not Found) or 410 (Gone) to an HTTP GET request for a prefilled dialog URI.
DD-29 | Servers MAY support prefill by adding initial values as query parameters to the delegated dialog URI. Clients SHOULD NOT assume any specific URL format, however.
DD-30 | An OSLC server providing Dialog capability MUST implement the vocabulary defined in this section.

## Appendix A. Dialog Results JSON

Dialog results are represented as JSON [RFC8259]. The top-level JSON object has an `oslc:results` property.

Property | Type | Occurs | Description
--- | --- | --- | ---
`oslc:results` | JSON Array | Exactly-one | An array of results, each result a JSON object. An empty array means the user canceled the dialog or didn't select a resource.

Each result is a JSON object with the following properties.

Property | Type | Occurs | Description
--- | --- | --- | ---
`rdf:resource` | String | Exactly-one | URI of the resource selected or created
`oslc:label` | String | Zero-or-one | Short label describing the resource selected

Here is an example response that contains two resources.

Example 27

    {
        "oslc:results": [
            {
                "oslc:label": "Bug 123: Server crash",
                "rdf:resource": "http://example.com/bug123"
            },
            {
                "oslc:label": "Bug 456: Client hangs on startup",
                "rdf:resource": "http://example.com/bug456"
            }
        ]
    }

When sent as a message in calls to `postMessage`, the JSON string is prefixed with the characters `oslc-response:`.