Authentication

There are three types of Authentication currently supported in Trellis: Anonymous Auth, Basic Auth and Token-based Auth. Any combination of these authentication types is possible, including enabling all or none of them.

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. Alternately, 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.

Anonymous Authentication

This is a mechanism for allowing anonymous users to 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.

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.