%beacon
and %sentinel
are now completely replaced by the Urbit Authenticator tool. They are left available for reference purposes but should not be used in production code anymore.
A website can authenticate a user's ownership of an active Urbit ship using a pair of agents: one on the website's ship to request authentication, and one on the user's ship to confirm it.
Beacon requests an authentication from a user's ship. Sentinel replies with a confirmation or a denial, based on user determination.
Authentication requires two agents:
-
%beacon
is an Urbit app intended to be run on a website's Urbit ship.%beacon
will request the user's Urbit ship's%sentinel
agent whether the website login attempt should be continued, and notify the website when the answer is%.y
yes.|install ~dister-dozzod-lapdeg %beacon
-
%sentinel
is an Urbit app which logs and responds to website authentication requests.%sentinel
will track all approved websites and reply to%beacon
subscriptions with the status of the authentication.|install ~dister-dozzod-lapdeg %sentinel
The %beacon
agent requests authentication for websites from users with the %sentinel
agent.
An Urbit ship maintains a standard interface for HTTP POST
and GET
requests, documented here and here. This will take place over a channel, an SSE stream. You should not need to write any Hoon code to work with %beacon
, and the web interface is provided for debugging and sanity-checking the behavior of the channel system.
%beacon
maintains two states: approved and unapproved. When a request is sent, the Urbit ship is marked as unapproved. This state only changes when the client %sentinel
agent responds that an approval has been made.
%beacon
allows you to set the current website. Since this is raw text, you should be consistent in how you type it: e.g. https://urbit.org/
and https://urbit.org
will appear to be different websites.
To set the self-identifying URL, send a JSON message to the local %beacon
ship at the endpoint /beacon-set-url
with the contents of the target ship: {"url":"https://urbit.org"}
. You should be consistent with this as it is only text (that is, trailing /
will distinguish sites.)
curl --header "Content-Type: application/json" \
--request PUT \
--data '{"url":"https://urbit.org"}' \
http://localhost:8080/beacon-set-url
To issue an authentication request, send a JSON message to the local %beacon
ship at the endpoint /beacon-send
with the contents of the target ship: {"ship":"~zod"}
.
curl --header "Content-Type: application/json" \
--request PUT \
--data '{"ship":"~zod"}' \
http://localhost:8080/beacon-send
To check on the state of an authentication request, send a JSON message to the local %beacon
ship at the endpoint /beacon-check
with the contents of the target ship: {"ship":~"zod"}
.
curl --header "Content-Type: application/json" \
--request PUT \
--data '{"ship":"~zod"}' \
http://localhost:8080/beacon-send
This will respond with a JSON of the format {"ship":"~zod", "status": "true"}
(or "false"
).
The %sentinel
agent accepts requests from websites using the %beacon
agent.
%sentinel
maintains a list of known websites. Each website may have one of three states: pending, approved, and rejected.
Although you can preemptively input a website to approve it, website approval is not linted and therefore https://urbit.org/
and https://urbit.org
will appear to be different websites. You should wait for the requester so that you approve their intended form.
There is not currently a mechanism to entirely delete website requests, only to disapprove them.
A website provider has a website running on a server. Somewhere accessible to this server (perhaps on the same machine, perhaps not), the provider also has an Urbit ship (likely a moon) with %beacon
installed.
|install ~dister-dozzod-lapdeg %beacon
When a user attempts to log in to the website using an option for Urbit ID, the site requests the ship's %beacon
agent to authenticate the user. The %beacon
agent will request the authentication status from the user's planet and relay the status to the website, which has subscribed to the %beacon
agent for that ship's status. Details for the JSON API are included in the discussion on %beacon
above.
At this point, three relevant possibilities follow:
- The user has
%sentinel
installed and has approved the website's authentication request. - The user has
%sentinel
installed but has not approved the website's authentication request (or has denied it). - The user does not have
%sentinel
installed.
(Other cases include the user entering a ship which isn't currently on the network, or which they do not control. We ignore these cases in this guide.)
In the first case, authentication should proceed smoothly. The website is responsible for maintaining the session.
In the second case, the login should be re-attempted by the user after granting approval through %sentinel
.
In the third case, the user should be told how to install the %sentinel
agent and how to approve the request. The user will then need to re-initiate the login authentication attempt at the website.
A user has %sentinel
installed. At their ship's URL plus /sentinel
, they are able to manage approved websites. While a user can input any website, he should wait for the external request because the URL is string-based; that is, https://urbit.org
differs from https://urbit.org/
for %sentinel
.
If the user does not have %sentinel
installed, he should install it to handle any website authentication requests fielded by %beacon
.
|install ~dister-dozzod-lapdeg %sentinel
Revoking website approval will not cancel any current sessions.