@@ -8,11 +8,13 @@ title: Security Drivers
9A security driver is a file in `/=home=/sec/<tld>/<domain>/hoon`
9A security driver is a file in `/=home=/sec/<tld>/<domain>/hoon`
10that handles the authentication for all HTTP requests to
10that handles the authentication for all HTTP requests to
11−`https://<domain>.<tld>`. All requests to the domain are
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
12−filtered through the security driver, which will either decorate
14+filters the request through the driver. The security driver will
13−the request with the needed credentials if it has them, or else
15+usually either decorate the request with the needed credentials
14−it will guide the user through the process of authenticating
16+if it has them, or else it will guide the user through the
15−Urbit with the service.
17+process of authenticating Urbit with the service.
17Each web service needs its own security driver, but most of them
19Each web service needs its own security driver, but most of them
18are pretty standard. We recommend starting with an existing
20are pretty standard. We recommend starting with an existing
@@ -121,23 +123,53 @@ in `bale`. `bale` contains:
121 `++bale`. Thus, in our case, `key` in our bale is of type
123 `++bale`. Thus, in our case, `key` in our bale is of type
122 `keys:basic-auth`.
124 `keys:basic-auth`.
124−Additionally, a security driver contains at least one "special"
126+Additionally, a security driver contains at least one out of the
125−arm. Here, we use `++filter-request`, which is a function which
129+- `++filter-request` is a function which takes a hiss (http
126−takes a hiss (http request) and produces a `sec-move`, which is
130+ request) and produces a `sec-move` (defined in zuse), which is
129−- `%send` plus a hiss, which sends the new hiss. This is the
133+ * `[%send hiss]`, which sends the new hiss. This is the
130− case in, for example, basic auth, where all we need to do is
134+ case in, for example, basic auth, where all we need to do is
131− add an extra header to the request.
135+ add an extra header to the request.
132−- `%give` plus an httr (http response), which immediately returns
136+ * `[%give httr]`, where httr is an http response. This
133− an http response to the sender.
137+ immediately returns an http response to the sender.
134−- `%show` plus a purl (parsed url), which displays a message
138+ * `[%show purl]`, where a purl is a parsed url. This displays
135− asking the user to visit the given url to continue the
139+ a message asking the user to visit the given url to continue
136− authentication process.
140+ the authentication process.
137−
141+ * `[%redo ~]`, which redoes the request.
138−Every request to a GitHub url will be filtered through
142+
139−`++filter-request`, and we want to add the authentication header
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.
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.
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.
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`.
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 `~`.
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
140−to it. Our `++aut` core contains a function
172+request. Our `++aut` core contains a function
141`++out-addding-header`, which does exactly what we want.
173`++out-addding-header`, which does exactly what we want.
143Where do the keys come from, though? Remember we ran
175Where do the keys come from, though? Remember we ran
@@ -215,7 +247,9 @@ Now we need a security driver. Use this:
216The oauth2 library provides the main "engine" in `standard`, just
248The oauth2 library provides the main "engine" in `standard`, just
217like in basic auth, except that we also have to specify a
249like 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`.
220Running `+http://api.github.com/user` tries to make a request to
254Running `+http://api.github.com/user` tries to make a request to
221Github with authentication. This loads into the bale the keys,
255Github with authentication. This loads into the bale the keys,