Authentication

There are two types of Authentication currently supported in Trellis: Basic Auth and Token-based Auth. One may enable one, both or neither in the server configuration.

JWT Authentication

JWT Authentication is a token-based authentication mechanism that consists of a set of claims about the user on whose behalf the request is being made. The request is digitally signed with a shared key, known by the Trellis server and the server that generates the tokens. This is the recommended way to authenticate users in Trellis.

In order for Trellis to authenticate users with JWT, it needs to be able to derive a WebID for a user. The best way to do this is by providing a webid claim as per the Solid WebID-OIDC specification. Alternatively, a client can provide a standard sub claim with a URL identifying a user or a combination of iss (issuer) and sub (subject) to form a WebID. For example, the simplest token could consist of:

{
    "webid": "http://example.com/username"
}

Or, this would produce the same WebID:

{
    "sub": "username",
    "iss": "http://example.com/"
}

Other claims may be present, but they will be ignored by Trellis.

A JWT token appears in a header as:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3ZWJpZCI6Imh0dHA6Ly9leGFtcGxlLmNvbS91c2VyIn0.YyVrlxXVQXFtg6euOl7I1GTMwdm7SiHcIZb6L0brBqI

The token consists of three Base64-encoded elements, each separated by a period (.). The first component is the JWT header, the second is the JSON claims and the third is a signature of the header and body. If the signature is not valid, the token will be rejected, and it is only possible to validate a signature with the secret key used to sign the token initially.

JWT authentication is configured in Trellis by defining a key and identifying whether that key has already been base64 encoded.

Basic Authentication

This is a mechanism by which users login with a username and password. This means that the Trellis system will need to manage these usernames and passwords (Note: it is recommended that this mechanism be reserved for a small number of (possibly) administrative users if it is enabled at all). Basic Authentication relies on an Authorization header that includes a Base64-encoded username:password string. When used over simple HTTP, this is an inherently insecure authentication mechanism.

The users file that is consulted when a client logs in takes the following form:

username : password : webid

where each field is separated by a colon (:). The WebID should be a URL, uniquely identifying the user.

Anonymous Authentication

Anonymous users may also interact with Trellis. Assuming that no Authorization header is sent in a request, the effective user will be http://www.trellisldp.org/ns/trellis#AnonymousAgent. If WebAC authorization is enabled, then one's ability to read from or write to the server will be dependent on the resource's WebAC configuration.