@@ -8,11 +8,13 @@ title: Security Drivers
88
99A security driver is a file in `/=home=/sec/<tld>/<domain>/hoon`
1010that handles the authentication for all HTTP requests to
11−`https://<domain>.<tld>`. All requests to the domain are
12−filtered through the security driver, which will either decorate
13−the request with the needed credentials if it has them, or else
14−it will guide the user through the process of authenticating
15−Urbit with the service.
11+`https://<domain>.<tld>`. When anything in Urbit makes an HTTP
12+request through `%eyre` (our web server), it checks to see if we
13+have a security driver for the requested domain, and if so
14+filters the request through the driver. The security driver will
15+usually either decorate the request with the needed credentials
16+if it has them, or else it will guide the user through the
17+process of authenticating Urbit with the service.
1618
1719Each web service needs its own security driver, but most of them
1820are pretty standard. We recommend starting with an existing
@@ -121,23 +123,53 @@ in `bale`. `bale` contains:
121123 `++bale`. Thus, in our case, `key` in our bale is of type
122124 `keys:basic-auth`.
123125
124−Additionally, a security driver contains at least one "special"
125−arm. Here, we use `++filter-request`, which is a function which
126−takes a hiss (http request) and produces a `sec-move`, which is
127−one of:
128−
129−- `%send` plus a hiss, which sends the new hiss. This is the
130− case in, for example, basic auth, where all we need to do is
131− add an extra header to the request.
132−- `%give` plus an httr (http response), which immediately returns
133− an http response to the sender.
134−- `%show` plus a purl (parsed url), which displays a message
135− asking the user to visit the given url to continue the
136− authentication process.
137−
138−Every request to a GitHub url will be filtered through
139−`++filter-request`, and we want to add the authentication header
140−to it. Our `++aut` core contains a function
126+Additionally, a security driver contains at least one out of the
127+five "special" arms:
128+
129+- `++filter-request` is a function which takes a hiss (http
130+ request) and produces a `sec-move` (defined in zuse), which is
131+ one of:
132+
133+ * `[%send hiss]`, which sends the new hiss. This is the
134+ case in, for example, basic auth, where all we need to do is
135+ add an extra header to the request.
136+ * `[%give httr]`, where httr is an http response. This
137+ immediately returns an http response to the sender.
138+ * `[%show purl]`, where a purl is a parsed url. This displays
139+ a message asking the user to visit the given url to continue
140+ the authentication process.
141+ * `[%redo ~]`, which redoes the request.
142+
143+ `%eyre` calls `++filter-request` just before sending an HTTP
144+ request to the specified domain. This allows the security
145+ driver to filter the requests, decorating them with
146+ authentication data.
147+
148+- `++filter-response` is a function which takes an httr and
149+ produces a `sec-move`. `%eyre` calls it after receiving an
150+ HTTP response from the specified domain. This allows the
151+ security driver to handle authentication errors, commonly
152+ caused by expired tokens, and retry the request.
153+
154+- `++receive-auth-query-string` is a function that takes a `quay`
155+ (list of query parameters) and produces a `sec-move`. `%eyre`
156+ calls it when it receives a request on the callback url.
157+ Generally, this happens in OAuth after the user has granted
158+ access to the urbit app, and the service makes a request to the
159+ callback url with the code. The security driver should then
160+ make a request to convert the code into an access token.
161+
162+- `++receive-auth-response` is a function that takes an httr and
163+ produces a `sec-move`. `%eyre` calls it when it gets a
164+ response to the request made in `++receive-auth-query-string`.
165+
166+- `++update` is a function which converts old state to a new
167+ format when the security driver gets updated. If you want to
168+ just get rid of the old state, define `++discard-state` as `~`.
169+
170+For basic auth, we only have to worry about `++filter-request`,
171+since all we need to do is add the correct header to each
172+request. Our `++aut` core contains a function
141173`++out-addding-header`, which does exactly what we want.
142174
143175Where do the keys come from, though? Remember we ran
@@ -215,7 +247,9 @@ Now we need a security driver. Use this:
215247
216248The oauth2 library provides the main "engine" in `standard`, just
217249like in basic auth, except that we also have to specify a
218−function to save the access token when we get it.
250+function to save the access token when we get it. It's worth
251+noting that this library is well documented in the source,
252+including examples: `/=home=/lib/oauth2/hoon`.
219253
220254Running `+http://api.github.com/user` tries to make a request to
221255Github with authentication. This loads into the bale the keys,