resource-access.bs

Authenticated Resource Access {#resource-access}
================================================

Issue: Write introduction to the Authenticated Resource Access section.

## Hypertext Transfer Protocol ## {#http}

### Background and Need ### {#http-need}
<em>This section is non-normative.</em>

Solid clients and servers need to exchange data securely over the Internet,
and they do so using the HTTP Web standard.
This section describes in detail
which parts of HTTP must be implemented by clients and servers.

### Required server-side implementation ### {#http-server}

A [=data pod=] MUST be an HTTP/1.1 server [[!RFC7230]][[!RFC7231]].
It SHOULD additionally be an HTTP/2 server [[!RFC7540]]
to improve performance,
especially in cases where individual clients
are expected to send high numbers of successive requests.

A data pod SHOULD use TLS connections
through the `https` URI scheme
in order to secure the communication between clients and servers.
When both `http` and `https` are supported,
all `http` URIs MUST redirect to their `https` counterparts
using a response with a `301` status code and a `Location` header.

A data pod MUST implement the server part
of <cite>HTTP/1.1 Conditional Requests</cite> [[!RFC7232]]
to ensure that updates requested by clients
will only be applied if given preconditions are met.
It SHOULD additionally implement the server part
of <cite>HTTP/1.1 Caching</cite> [[!RFC7234]]
to improve performance.
A data pod MAY implement the server part
of <cite>HTTP/1.1 Range Requests</cite> [[!RFC7233]]
to further improve performance for large representations.

A data pod MUST implement the server part
of <cite>HTTP/1.1 Authentication</cite> [[!RFC7235]].
When a client does not provide valid credentials
when requesting a resource that requires it (see [[#webid]]),
the data pod MUST send a response with a `401` status code
(unless `404` is preferred for security reasons).

### Required client-side implementation ### {#http-client}

A Solid client MUST be an HTTP/1.1 client [[!RFC7230]][[!RFC7231]].
It MAY additionally be an HTTP/2 client [[!RFC7540]]
to improve performance.

A Solid client MAY implement the client parts of
<cite>HTTP/1.1 Conditional Requests</cite> [[!RFC7232]]
to only trigger updates when certain preconditions are met.
It MAY implement
<cite>HTTP/1.1 Caching</cite> [[!RFC7234]]
and
<cite>HTTP/1.1 Range Requests</cite> [[!RFC7233]]
to improve performance.

A Solid client MUST implement the client part
of <cite>HTTP/1.1 Authentication</cite> [[!RFC7235]]
if it needs to access resources requiring authentication (see [[#webid]]).
When it receives a response with a `403` or `404` status code,
it MAY repeat the request with different credentials.


## Linked Data Platform ## {#ldp}

Issue: Write Linked Data Platform section.

Draft:
A Solid data pod MUST conform to the LDP specification [[!LDP]].


## WebID ## {#webid}

Issue: Explain inline that agents accessing non-public Solid resources
  need to authenticate with a WebID, which is a URL
  pointing to a document with an RDF representation.


### WebID-OIDC ### {#webid-oidc}

Issue: Write WebID-OIDC section.

Draft:
A Solid data pod MUST conform to the WebID-OIDC specification [[!WEBID-OIDC]].


### WebID-TLS ### {#webid-tls}
<em>This section is non-normative.</em>

Initial versions of Solid relied on WebID-TLS for authenticated resource access,
this specification only relies on [[!WEBID-OIDC]]. Implementations can use WebID-TLS
just as any other mechanism as an additional authentication method. Implementations
should not assume broad support for any of those additional methods in solid ecosystem.


## Web Access Control ## {#wac}

Issue: Write Web Access Control section.

Draft:
A Solid data pod MUST conform to the Web Access Control specification [[!WAC]].


## Cross-Origin Resource Sharing ## {#cors}

### Background and Need ### {#cors-need}
<em>This section is non-normative.</em>

[=Solid apps=] typically access data from multiple sources.
However,
Web browsers by default prevent apps that run on one origin
from accessing data on other origins.
This cross-origin protection is a security mechanism
that ensures malicious websites cannot simply read
your profile or banking details from other websites.
However, this reasonable default poses a problem
even for benevolent Solid apps,
which might have good reasons to access data from different places.
For instance,
a Solid app at `https://app.example/`
would be prevented from accessing data on
`https://alice-data-pod.example/` or `https://bob-data-pod.example/`,
even when Alice and Bob have given the user of the app
their permission to see some of their data.

For cases where the other origins
have their own access protection mechanism—
[like within Solid](#wac)—
the browser's built-in cross-origin protection
is actually an obstacle rather than a feature.
After all,
[=data pods=] already ensure through access control
that certain documents can only be accessed
by specific people or applications.
Preventively blocking apps from different origins
thus introduces an unnecessary barrier.

Fortunately,
Web servers can indicate to the browser
that certain documents do not require cross-origin protection.
This mechanism to selectively disable that protection
is called *Cross-Origin Resource Sharing* or *CORS* [[FETCH]].
By responding to browser requests
with a specific combination of HTTP headers,
servers can indicate which actions are allowed for a given resource.
For a Solid data pod,
the goal is to allow *all* actions on the CORS level,
such that the deeper [access control layer](#wac)
can exert full control over the app's allowed permissions.
The next section describes how to achieve this
through the right HTTP header configuration.


### Required server-side implementation ### {#cors-server}

A [=data pod=] MUST implement the CORS protocol [[!FETCH]]
such that, to the extent possible,
the browser allows Solid apps
to send any request and combination of request headers
to the data pod,
and the Solid app can read any response and response headers
received from the data pod.
If the data pod wishes to block access to a resource,
this MUST NOT happen via CORS
but MUST instead be communicated to the Solid app in the browser
through HTTP status codes such as
`401`, `403`, or `404` [[!RFC7231]].

Note: Since the CORS protocol is part of a Living Standard,
it might be changed at any point,
which might necessitate changes to data pod implementations
for continued prevention of undesired blocking.
A [proposal](https://github.com/whatwg/fetch/issues/878) to mitigate this
has been suggested.

Concretely,
whenever a data pod receives an HTTP request
containing a valid `Origin` header [[!RFC6454]],
the server MUST respond with the appropriate `Access-Control-*` headers
as specified in the CORS protocol [[!FETCH]].
In particular,
the data pod MUST set the `Access-Control-Allow-Origin` header
to the valid `Origin` value from the request
and list `Origin` in the `Vary` header value.
The data pod MUST make all used response headers readable for the Solid app
through `Access-Control-Expose-Headers`
(with the possible exception of the `Access-Control-*` headers themselves).
A data pod MUST also support the HTTP `OPTIONS` method [[!RFC7231]]
such that it can respond appropriately to CORS preflight requests.

Careful attention is warranted,
especially because of the many edge cases.
For instance,
data pods SHOULD explicitly enumerate
all used response headers under `Access-Control-Expose-Headers`
rather than resorting to `*`,
which does not cover all cases (such as credentials mode set to `include`).
Data pods SHOULD also explicitly list `Accept` under `Access-Control-Allow-Headers`,
because values longer than 128 characters
(not uncommon for RDF-based Solid apps)
would otherwise be blocked,
despite shorter `Accept` headers being allowed without explicit mention.