-
-
Notifications
You must be signed in to change notification settings - Fork 709
User Authentication
A Sandstorm app delegates authentication to the Sandstorm platform. This page documents the details.
Many apps on Sandstorm expect to receive HTTP requests. To support those apps, Sandstorm provides a tool called sandstorm-http-bridge.
Developers should know that when their app is running, they are receiving HTTP requests from sandstorm-http-bridge rather than directly from the user. This results in a few interesting properties:
-
Sandstorm knows which user is making the request, so it can add headers indicating the username ("authentication").
-
Sandstorm knows which permissions the user has -- for example, it knows if the user owns this grain -- so it can add headers indicating what permissions the user has ("authorization").
-
When your app receives HTTP requests,
sandstorm-http-bridgehas normalized them, so your app doesn't have to handle whatever dialect of non-compliant HTTP the user's browser is speaking.
Per the current implementation of sandstorm-http-bridge, an app receives the following headers related to user identity and permissions:
-
X-Sandstorm-Username: This is set to the user's full name, in percent-encoded UTF-8. For example, the username"Kurt Friedrich Gödel"will appear as"Kurt%20Friedrich%20G%C3%B6del". -
X-Sandstorm-User-Id: This is set to the user's current user ID, which is the first 128 bits of a SHA-256. For example:be21e57e93ac5526 -
X-Sandstorm-Permissions: When the admin requests the page, this contains all permissions defined in the package'ssandstorm-pkgdef.capnp. For everyone else, it is empty.
The purpose of this header is to let the app understand what permissions the user visiting the grain has.
Right now, the way it works is that for the grain owner, this contains all permissions defined in the package's sandstorm-pkgdef.capnp. For example, the MediaWiki app needs to find out if this user is the one that created the grain, so its package definition includes:
bridgeConfig = (viewInfo = (permissions = [(name = "admin")]))
This way, the app can tell if the string admin appears in the inbound X-Sandstorm-Permissions header. If so, the user is an admin!
In the future, this header will eventually contain a list of permissions that the grain's owner has granted to whoever is visiting the grain. Note that this "sharing" functionality is not yet built, so it does not do that yet.
It is possible to write a Sandstorm app that does not use sandstorm-http-bridge! We provide sample code for that in the sandstorm-rawapi-example repository on GitHub.
You might be interested in looking at:
- A sandstorm-pkgdef.capnp with no permissions defined.
- A sandstorm-pkgdef.capnp with one permission defined.
- The implementation of sandstorm-http-bridge.