doc/api/keep-web-urls.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "Keep-web URL patterns"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 Files served by @keep-web@ can be rendered directly in the browser, or @keep-web@ can instruct the browser to only download the file.
  14
  15 When serving files that will render directly in the browser, it is important to properly configure the keep-web service to migitate cross-site-scripting (XSS) attacks.  A HTML page can be stored in a collection.  If an attacker causes a victim to visit that page through Workbench, the HTML will be rendered by the browser.  If all collections are served at the same domain, the browser will consider collections as coming from the same origin, which will grant access to the same browsing data (cookies and local storage).  This would enable malicious Javascript on that page to access Arvados on behalf of the victim.
  16
  17 This can be mitigated by having separate domains for each collection, or limiting preview to circumstances where the collection is not accessed with the user's regular full-access token.  For cluster administrators that understand the risks, this protection can also be turned off.
  18
  19 The following "same origin" URL patterns are supported for public collections and collections shared anonymously via secret links (i.e., collections which can be served by keep-web without making use of any implicit credentials like cookies). See "Same-origin URLs" below.
  20
  21 <pre>
  22 http://collections.example.com/c=uuid_or_pdh/path/file.txt
  23 http://collections.example.com/c=uuid_or_pdh/t=TOKEN/path/file.txt
  24 </pre>
  25
  26 The following "multiple origin" URL patterns are supported for all collections:
  27
  28 <pre>
  29 http://uuid_or_pdh--collections.example.com/path/file.txt
  30 http://uuid_or_pdh--collections.example.com/t=TOKEN/path/file.txt
  31 </pre>
  32
  33 In the "multiple origin" form, the string @--@ can be replaced with @.@ with identical results (assuming the downstream proxy is configured accordingly). These two are equivalent:
  34
  35 <pre>
  36 http://uuid_or_pdh--collections.example.com/path/file.txt
  37 http://uuid_or_pdh.collections.example.com/path/file.txt
  38 </pre>
  39
  40 The first form (with @--@ instead of @.@) avoids the cost and effort of deploying a wildcard TLS certificate for @*.collections.example.com@ at sites that already have a wildcard certificate for @*.example.com@ . The second form is likely to be easier to configure, and more efficient to run, on a downstream proxy.
  41
  42 In all of the above forms, the @collections.example.com@ part can be anything at all: keep-web itself ignores everything after the first @.@ or @--@. (Of course, in order for clients to connect at all, DNS and any relevant proxies must be configured accordingly.)
  43
  44 In all of the above forms, the @uuid_or_pdh@ part can be either a collection UUID or a portable data hash with the @+@ character optionally replaced by @-@ . (When @uuid_or_pdh@ appears in the domain name, replacing @+@ with @-@ is mandatory, because @+@ is not a valid character in a domain name.)
  45
  46 In all of the above forms, a top level directory called @_@ is skipped. In cases where the @path/file.txt@ part might start with @t=@ or @c=@ or @_/@, links should be constructed with a leading @_/@ to ensure the top level directory is not interpreted as a token or collection ID.
  47
  48 Assuming there is a collection with UUID @zzzzz-4zz18-znfnqtbbv4spc3w@ and portable data hash @1f4b0bc7583c2a7f9102c395f4ffc5e3+45@, the following URLs are interchangeable:
  49
  50 <pre>
  51 http://zzzzz-4zz18-znfnqtbbv4spc3w.collections.example.com/foo/bar.txt
  52 http://zzzzz-4zz18-znfnqtbbv4spc3w.collections.example.com/_/foo/bar.txt
  53 http://zzzzz-4zz18-znfnqtbbv4spc3w--collections.example.com/_/foo/bar.txt
  54 </pre>
  55
  56 The following URLs are read-only, but will return the same content as above:
  57
  58 <pre>
  59 http://1f4b0bc7583c2a7f9102c395f4ffc5e3-45--foo.example.com/foo/bar.txt
  60 http://1f4b0bc7583c2a7f9102c395f4ffc5e3-45--.invalid/foo/bar.txt
  61 http://collections.example.com/by_id/1f4b0bc7583c2a7f9102c395f4ffc5e3%2B45/foo/bar.txt
  62 http://collections.example.com/by_id/zzzzz-4zz18-znfnqtbbv4spc3w/foo/bar.txt
  63 </pre>
  64
  65 If the collection is named "MyCollection" and located in a project called "MyProject" which is in the home project of a user with username is "bob", the following read-only URL is also available when authenticating as bob:
  66
  67 pre. http://collections.example.com/users/bob/MyProject/MyCollection/foo/bar.txt
  68
  69 An additional form is supported specifically to make it more convenient to maintain support for existing Workbench download links:
  70
  71 pre. http://collections.example.com/collections/download/uuid_or_pdh/TOKEN/foo/bar.txt
  72
  73 A regular Workbench "download" link is also accepted, but credentials passed via cookie, header, etc. are ignored. Only public data can be served this way:
  74
  75 pre. http://collections.example.com/collections/uuid_or_pdh/foo/bar.txt
  76
  77 h2(#same-site). Same-site requirements for requests with tokens
  78
  79 Although keep-web doesn't care about the domain part of the URL, the clients do: especially when rendering inline content.
  80
  81 When a client passes a token in the URL, keep-web sends a redirect response placing the token in a @Set-Cookie@ header with the @SameSite=Lax@ attribute. The browser will ignore the cookie if it's not coming from a _same-site_ request, and thus its subsequent request will fail with a @401 Unauthorized@ error.
  82
  83 This mainly affects Workbench's ability to show inline content, so it should be taken into account when configuring both services' URL schemes.
  84
  85 You can read more about the definition of a _same-site_ request at the "RFC 6265bis-03 page":https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-5.2