docs/tutorials/gall/security-driver.udon · urbit.org

git.iko.soy/urbit.org

on c19bc7a help sign in

urbit.org/docs/tutorials/gall/security-driver.udon

281 lines 13 kB history raw

1:- :~ navhome/'/docs/'

2 navuptwo/'true'

3 next/'true'

4 sort/'8'

5 title/'Security Drivers'

6 ==

7;>

9# Security drivers

11A security driver is a file in `/=home=/sec/<tld>/<domain>/hoon`

12that handles the authentication for all HTTP requests to

13`https://<domain>.<tld>`. When anything in Urbit makes an HTTP

14request through `%eyre` (our web server), it checks to see if we

15have a security driver for the requested domain, and if so

16filters the request through the driver. The security driver will

17usually either decorate the request with the needed credentials

18if it has them, or else it will guide the user through the

19process of authenticating Urbit with the service.

21Each web service needs its own security driver, but most of them

22are pretty standard. We recommend starting with an existing

23security driver based on your needed authentication method (e.g.

24basic auth, OAuth1, OAuth2), and changing whatever is specific to

25your service.

27The best strategy for building security drivers is to copy a

28similar one and tweak it until it works for you. The best

29representatives are Github for Basic Authentication, Twitter for

30OAuth1, Slack for OAuth2 when access tokens don't expire, and

31Google APIs for OAuth2 when access tokens do expire. In most

32cases you'll need to make very few changes to one of these

33models.

35Still, it's worth seeing one or two built from the ground up.

36Here, we'll build a connector for the Github API v3. (It's already in `/sec/com/github.hoon` if you want to see it.)

38The

39simplest way to interact with the Github API is to just fetch

40https://api.github.com from the dojo. First, run this:

42```

43> |init-auth-basic /com/github

44```

46Input your Github username and password as directed. Next:

48```

49~your-urbit:dojo> +https://api.github.com

50```

52> Note: the current version of this API is outdated, so you'll get a 403 message at this point. We need to update this so you can follow along with the examples. We're sorry!

54Github exposes a few endpoints to the general web, and the root

55endpoint is one of them. This gives you a textual representation

56of a JSON object that contains a bunch of urls to other parts of

57Github's API. This is exactly the same response you would get

58from just running `curl https://api.github.com` on UNIX.

60If we don't have a security driver for Github yet, many of the

61endpoints won't be accessible, or they will only have publicly

62accessible information. Most of what we care about requires us

63to be authenticated.

65## Basic auth

67Here's a simple security driver:

69```

70:: Test url +https://api.github.com/user

71::

72:::: /hoon/github/com/sec

73 ::

74/+ basic-auth

75!:

76|_ [bal=(bale keys:basic-auth) $~]

77++ aut ~(standard basic-auth bal ~)

78++ filter-request out-adding-header:aut

79--

80```

82Github supports authentication through either Basic

83Authentication or OAuth2. We'll show the basic auth example

84first, but in general we'd prefer OAuth2.

86Since this driver is for Github, put it in

87`/=home=/sec/com/github/hoon`.

89To try this out, we first have to initialize our credentials with

90`|init-auth-basic`, which prompts for the url of the service

91(api.github.com), username, and password. It stores this

92information in a manner that `%eyre` knows how to decode and send

93put into your `bale`. Note that `|init-auth-basic` is standard for

94basic auth, but other auth schemes (like OAuth) are initialized

95in other ways.

97After you've run `|init-auth-basic`, you should be able to run

98`+https://api.github.com/user` and get a response indicating who

99you're logged in as.

100

101You can similarly POST:

102

103```

104~your-urbit:dojo> +https://api.github.com/gists &json _(cork de-json:html need) '{"files":{"file1.txt":{"content":"can\'t stop the signal"}}}'

105```

106

107This creates a gist, go to `https://gist.github.com/<username>` to

108see it.

109

110The `+url` syntax used in "source" position makes a GET request,

111but if you pass it data it will make a POST request with that

112data as the body. This request is authenticated seamlessly. You

113can send data of any mark as long as it has a conversion path to

114`%mime`.

115

116Let's take a look at the code and see if we can figure out what's

117happening here:

118

119```

120/+ basic-auth

121```

122

123First, we load a library called `basic-auth`. This library

124exposes two items. `keys` is the type of the basic auth key,

125which is essentially a base64'd username and password.

126`standard` accepts a `bale` and produces a core with everything

127we'll need to implement basic auth.

128

129Every security driver needs some amount of state, which is stored

130in `bale`. `bale` contains:

131

132- `our`, our urbit name

133- `now`, the current time

134- `eny`, 256 bits of entropy

135- `byk`, the urbit, desk and case which the security driver is running from

136- `usr`, the particular identity we're logging in with

137- `dom`, the site we're accessing

138- `key`, the secrets required to authenticate requests. The type for this entry is supplied by the programmer as the argument to `++bale`. Thus, in our case, `key` in our bale is of type `keys:basic-auth`.

139

140Additionally, a security driver contains at least one out of the

141five "special" arms:

142

143- `++filter-request` is a function which takes a hiss (http request) and produces a `sec-move` (defined in zuse), which is one of:

144 - `[%send hiss]`, which sends the new hiss. This is the case in, for example, basic auth, where all we need to do is add an extra header to the request.

145 - `[%give httr]`, where httr is an http response. This immediately returns an http response to the sender.

146 - `[%show purl]`, where a purl is a parsed url. This displays a message asking the user to visit the given url to continue the authentication process.

147 - `[%redo ~]`, which redoes the request.

148 - `%eyre` calls `++filter-request` just before sending an HTTP request to the specified domain. This allows the security driver to filter the requests, decorating them with authentication data.

149- `++filter-response` is a function which takes an httr and produces a `sec-move`. `%eyre` calls it after receiving an HTTP response from the specified domain. This allows the security driver to handle authentication errors, commonly caused by expired tokens, and retry the request.

150- `++receive-auth-query-string` is a function that takes a `quay` (list of query parameters) and produces a `sec-move`. `%eyre` calls it when it receives a request on the callback url. Generally, this happens in OAuth after the user has granted access to the urbit app, and the service makes a request to the callback url with the code. The security driver should then make a request to convert the code into an access token.

151- `++receive-auth-response` is a function that takes an httr and produces a `sec-move`. `%eyre` calls it when it gets a response to the request made in `++receive-auth-query-string`.

152- `++update` is a function which converts old state to a new format when the security driver gets updated. If you want to just get rid of the old state, define `++discard-state` as `~`.

153

154For basic auth, we only have to worry about `++filter-request`,

155since all we need to do is add the correct header to each

156request. Our `++aut` core contains a function

157`++out-addding-header`, which does exactly what we want.

158

159Where do the keys come from, though? Remember we ran

160`|init-auth-basic` to input them. This just prompts you for the

161service url, username, and password, and it stores them next to

162the driver. In our case, that's

163`/=home=/sec/com/gitub/api/atom`. These keys are stored

164encrypted, and you don't want to edit them directly. `%eyre`