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

git.iko.soy/urbit.org

on 7fa97bd help sign in

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

287 lines 12 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. The

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

38https://api.github.com from the dojo:

40```

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

42```

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

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

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

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

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

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

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

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

53to be authenticated.

55## Basic auth

57Here's a simple security driver:

59```

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

61::

62:::: /hoon/github/com/sec

63 ::

64/+ basic-auth

65!:

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

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

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

69--

70```

72Github supports authentication through either Basic

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

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

76Since this driver is for Github, put it in

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

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

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

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

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

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

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

85in other ways.

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

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

89you're logged in as.

91You can similarly POST:

93```

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

95```

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

98see it.

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

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

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

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

104`%mime`.

105

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

107happening here:

108

109```

110 /+ basic-auth

111```

112

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

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

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

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

117we'll need to implement basic auth.

118

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

120in `bale`. `bale` contains:

121

122- `our`, our urbit name

123- `now`, the current time

124- `eny`, 256 bits of entropy

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

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

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

128- `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`.

129

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

131five "special" arms:

132

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

134

135```

136 * `[%send hiss]`, which sends the new hiss. This is the

137 case in, for example, basic auth, where all we need to do is

138 add an extra header to the request.

139 * `[%give httr]`, where httr is an http response. This

140 immediately returns an http response to the sender.

141 * `[%show purl]`, where a purl is a parsed url. This displays

142 a message asking the user to visit the given url to continue

143 the authentication process.

144 * `[%redo ~]`, which redoes the request.

145

146 * `%eyre` calls `++filter-request` just before sending an HTTP

147 request to the specified domain. This allows the security

148 driver to filter the requests, decorating them with

149 authentication data.

150```

151

152- `++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.

153

154- `++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.

155

156- `++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`.

157

158- `++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 `~`.

159

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

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

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

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

164

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

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

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

168the driver. In our case, that's

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

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