This branch is an experiment by The Authenticity Institute to expand the Solid Server implementation to authenticate owners of data stored in the POD against client certificates issued in an Authenticity framework. Primarily this means that client certificate must be signed by an official CA, rather than be self-signed. Currently, the City of Osmio Virtual Records Department CA is the root authority, but it could be any central CA that users collectively agreed on.
At the moment, we have also "faked" the WebID implementation, because Osmio VRD certificates are not currently issued with a Subject Alternative Name corresponding to the "WebID" for the identity in question. We would like to have a more coherent compatibility with WebID-TLS authentication, but pending some internal discussions about how this should work in our context, we have implemented a mechanism within node-solid-server that "derives" a WebID based on the Serial Number of the client certificate provided, using the following algorithm (for the moment):
- https:// +
- Serial Number is encoded using Crockford's Base32 +
- .webid.zkgroup.org +
- /profile/card#me
solid-server lets you run a Solid server on top of the file-system. You can use it as a command-line tool (easy) or as a library (advanced).
- Linked Data Platform
- Web Access Control
- WebID+TLS Authentication
- Real-time live updates (using WebSockets)
- Identity provider for WebID
- CORS proxy for cross-site data access
- Group members in ACL
- Email account recovery
You can install and run the server either using Node.js directly or using Docker. This and the following sections describe the first approach, for the second approach see the section use Docker Section below.
To install, first install Node and then run the following
$ npm install -g solid-serverThe easiest way to setup solid-server is by running the wizard. This will create a config.json in your current folder
$ solid initNote: If prompted for an SSL key and certificate, follow the instructions below.
To run your server, simply run solid start:
$ solid start
# Solid server (solid v0.2.24) running on https://localhost:8443/If you prefer to use flags instead, the following would be the equivalent
$ solid start --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem
# Solid server (solid v0.2.24) running on https://localhost:8443/If you want to run solid on a particular folder (different from the one you are in, e.g. path/to/folder):
$ solid start --root path/to/folder --port 8443 --ssl-key path/to/ssl-key.pem --ssl-cert path/to/ssl-cert.pem
# Solid server (solid v0.2.24) running on https://localhost:8443/Solid requires SSL certificates to be valid, so you cannot use self-signed certificates. To switch off this security feature in development environments, you can use the bin/solid-test executable, which unsets the NODE_TLS_REJECT_UNAUTHORIZED flag and sets the rejectUnauthorized option.
You need an SSL certificate from a certificate authority, such as your domain provider or Let's Encrypt!.
For testing purposes, you can use bin/solid-test with a self-signed certificate, generated as follows:
$ openssl genrsa 2048 > ../localhost.key
$ openssl req -new -x509 -nodes -sha256 -days 3650 -key ../localhost.key -subj '/CN=*.localhost' > ../localhost.cert
You can run solid so that new users can sign up, in other words, get their WebIDs username.yourdomain.com.
Pre-requisites:
- Get a Wildcard Certificate
- Add a Wildcard DNS record in your DNS zone (e.g.
*.yourdomain.com) - (If you are running locally) Add the line
127.0.0.1 *.localhostto/etc/hosts
$ solid init
..
? Allow users to register their WebID (y/N) # write `y` here
..
$ solid startOtherwise, if you want to use flags, this would be the equivalent
$ solid --multiuser --port 8443 --cert /path/to/cert --key /path/to/key --root ./accountsYour users will have a dedicated folder under ./accounts. Also, your root domain's website will be in ./accounts/yourdomain.tld. New users can create accounts on /api/accounts/new and create new certificates on /api/accounts/cert. An easy-to-use sign-up tool is found on /api/accounts.
See Running Solid behind a reverse proxy.
To use Gmail you may need to configure "Allow Less Secure Apps" in your Gmail account unless you are using 2FA in which case you would have to create an Application Specific password. You also may need to unlock your account with "Allow access to your Google account" to use SMTP.
If you don't want WebID Authentication and Web Access Control, you can run a simple Linked Data Platform.
# over HTTP
$ solid start --port 8080 --no-webid
# over HTTPS
$ solid start --port 8080 --ssl-key key.pem --ssl-cert cert.pem --no-webidNote: if you want to run on HTTP, do not pass the --ssl-* flags, but keep --no-webid
The command line tool has the following options
$ solid
Usage: solid [options] [command]
Commands:
init [options] create solid server configurations
start [options] run the Solid server
Options:
-h, --help output usage information
-V, --version output the version number
$ solid init --help
Usage: init [options]
Create solid server configurations
Options:
-h, --help output usage information
--advanced Ask for all the settings
$ solid start --help
Usage: start [options]
run the Solid server
Options:
--root [value] Root folder to serve (default: './data')
--port [value] SSL port to use
--serverUri [value] Solid server uri (default: 'https://localhost:8443')
--webid Enable WebID authentication and access control (uses HTTPS)
--mount [value] Serve on a specific URL path (default: '/')
--config-path [value]
--db-path [value]
--auth [value] Pick an authentication strategy for WebID: `tls` or `oidc`
--certificate-header [value]
--owner [value] Set the owner of the storage (overwrites the root ACL file)
--ssl-key [value] Path to the SSL private key in PEM format
--ssl-cert [value] Path to the SSL certificate key in PEM format
--no-reject-unauthorized Accept self-signed certificates
--multiuser Enable multi-user mode
--idp [value] Obsolete; use --multiuser
--no-live Disable live support through WebSockets
--proxy [value] Obsolete; use --corsProxy
--corsProxy [value] Serve the CORS proxy on this path
--suppress-data-browser Suppress provision of a data browser
--data-browser-path [value] An HTML file which is sent to allow users to browse the data (eg using mashlib.js)
--suffix-acl [value] Suffix for acl files (default: '.acl')
--suffix-meta [value] Suffix for metadata files (default: '.meta')
--secret [value] Secret used to sign the session ID cookie (e.g. "your secret phrase")
--error-pages [value] Folder from which to look for custom error pages files (files must be named <error-code>.html -- eg. 500.html)
--force-user [value] Force a WebID to always be logged in (useful when offline)
--strict-origin Enforce same origin policy in the ACL
--useEmail Do you want to set up an email service?
--email-host [value] Host of your email service
--email-port [value] Port of your email service
--email-auth-user [value] User of your email service
--email-auth-pass [value] Password of your email service
--useApiApps Do you want to load your default apps on /api/apps?
--api-apps [value] Path to the folder to mount on /api/apps
-v, --verbose Print the logs to console
Build with:
docker build -t node-solid-server .Run with:
docker run -p 8443:8443 --name solid node-solid-serverModify the config as follows:
- Copy the config to the current directory with:
docker cp solid:/usr/src/app/config.json . - Edit the
config.jsonfile - Copy the file back with
docker cp config.json solid:/usr/src/app/ - Restart the server with
docker restart solid
npm install
The library provides two APIs:
solid.createServer(settings): starts a ready to use Express app.lnode(settings): creates an Express that you can mount in your existing express app.
In case the settings is not passed, then it will start with the following
default settings.
{
cache: 0, // Set cache time (in seconds), 0 for no cache
live: true, // Enable live support through WebSockets
root: './', // Root location on the filesystem to serve resources
secret: 'node-ldp', // Express Session secret key
cert: false, // Path to the ssl cert
key: false, // Path to the ssl key
mount: '/', // Where to mount Linked Data Platform
webid: false, // Enable WebID+TLS authentication
suffixAcl: '.acl', // Suffix for acl files
corsProxy: false, // Where to mount the CORS proxy
errorHandler: false, // function(err, req, res, next) to have a custom error handler
errorPages: false // specify a path where the error pages are
}Have a look at the following examples or in the
examples/ folder
for more complex ones
You can create an solid server ready to use using solid.createServer(opts)
var solid = require('solid-server')
var ldp = solid.createServer({
key: '/path/to/sslKey.pem',
cert: '/path/to/sslCert.pem',
webid: true
})
ldp.listen(3000, function() {
// Started Linked Data Platform
})You can integrate solid in your existing Express
app, by mounting the solid app on a specific path using lnode(opts).
var solid = require('solid-server')
var app = require('express')()
app.use('/test', solid(yourSettings))
app.listen(3000, function() {
// Started Express app with ldp on '/test'
})
...Run your app with the DEBUG variable set:
$ DEBUG="solid:*" node app.jsIn order to really get a feel for the Solid platform, and to test out solid,
you will need the following:
-
A WebID profile and browser certificate from one of the Solid-compliant identity providers, such as databox.me.
-
A server-side SSL certificate for
solidto use (see the section below on creating a self-signed certificate for testing).
While these steps are technically optional (since you could launch it in HTTP/LDP-only mode), you will not be able to use any actual Solid features without them.
When deploying solid in production, we recommend that you go the
usual Certificate Authority route to generate your SSL certificate (as you
would with any website that supports HTTPS). However, for testing it locally,
you can easily generate a self-signed certificate for whatever domain you're
working with.
For example, here is how to generate a self-signed certificate for localhost
using the openssl library:
solid --webid --port 8443 --cert ../localhost.cert --key ../localhost.key -vNote that this example creates the localhost.cert and localhost.key files
in a directory one level higher from the current, so that you don't
accidentally commit your certificates to solid while you're developing.
If you started your solid server locally on port 8443 as in the example
above, you would then be able to visit https://localhost:8443 in the browser
(ignoring the Untrusted Connection browser warnings as usual), where your
solid server would redirect you to the default data viewer app.
To test certificates and account creation on subdomains, solid's test suite
uses the following localhost domains: nic.localhost, tim.localhost, and
nicola.localhost. You will need to create host file entries for these, in
order for the tests to pass.
Edit your /etc/hosts file, and append:
# Used for unit testing solid
127.0.0.1 nic.localhost
127.0.0.1 tim.localhost
127.0.0.1 nicola.localhost
$ npm test
# running the tests with logs
$ DEBUG="solid:*" npm testIn order to test a single component, you can run
npm run test-(acl|formats|params|patch)solid is only possible due to the excellent work of the following contributors:
| Tim Berners-Lee | GitHub/timbl | Twitter/@timberners_lee | WebID |
|---|---|---|---|
| Nicola Greco | GitHub/nicola | Twitter/@nicolagreco | WebID |
| Martin Martinez Rivera | GitHub/martinmr | ||
| Andrei Sambra | GitHub/deiu | Twitter/@deiu | WebID |
| Dmitri Zagidulin | GitHub/dmitrizagidulin | Twitter/@codenamedmitri | |
| Ruben Verborgh | GitHub/RubenVerborgh | Twitter/@RubenVerborgh | WebID |
- Join us in Gitter to help with development or to hang out with us :)
- Create a new issue to report bugs
- Fix an issue
Have a look at CONTRIBUTING.md.
MIT