Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 283 lines (220 sloc) 10.432 kB
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
1 Aker
3438fa9 @rsutphin Reword for public release.
rsutphin authored
2 ====
ca30a7a Add rake tasks for setting up cc_pers_test, plus directions in the RE…
Rhett Sutphin authored
3
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
4 Aker is a library for managing authentication and authorization in
3438fa9 @rsutphin Reword for public release.
rsutphin authored
5 ruby applications (particularly Rack applications). It is designed to
6 extensibly work with your existing (possibly legacy) authentication
7 infrastructure.
ca30a7a Add rake tasks for setting up cc_pers_test, plus directions in the RE…
Rhett Sutphin authored
8
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
9 Aker is made up of **authorities** which provide user security
14703d5 More minor doc tweaks.
Rhett Sutphin authored
10 information, **modes** which integrate authentication with HTTP (via
11 Rack), and a **configuration** which specifies which of these to use
12 and how to set them up.
13
b45780d @rsutphin Add note and link to rubydoc.info.
rsutphin authored
14 Reader's note: this README uses [YARD][] markup to provide links to
15 Aker's API documentation. If you aren't already, consider reading it
16 on [rubydoc.info][] so that the links will be followable.
17
18 [YARD]: http://yardoc.org/
19 [rubydoc.info]: http://rubydoc.info/github/NUBIC/aker/master/file/README.md
20
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
21 Aker concepts
3438fa9 @rsutphin Reword for public release.
rsutphin authored
22 -------------
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
23
24 ### Authorities
25
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
26 An **authority** in Aker is the encapsulation of a mechanism for
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
27 providing authentication and/or authorization. The methods which an
28 authority may implement (all are optional) are described in detail in
3438fa9 @rsutphin Reword for public release.
rsutphin authored
29 the documentation for the {Aker::Authorities::Composite composite
30 authority}. All the included authorities are described in the
31 documentation for the {Aker::Authorities} module. See their
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
32 documentation for more information.
33
34 More than one authority can be used in a particular configuration.
35 When validating credentials or performing any of the other actions
36 provided by the authority interface, all the authorities will be
37 consulted. The documentation for the composite authority describes
14703d5 More minor doc tweaks.
Rhett Sutphin authored
38 how the results are aggregated for each action.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
39
40 ### Modes
41
3438fa9 @rsutphin Reword for public release.
rsutphin authored
42 An Aker **mode** is a mechanism for receiving credentials in the context
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
43 of a web application. Aker modes come in variants that are intended
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
44 for use in human-user-facing contexts (*UI* modes) and machine-facing
45 contexts (*API* modes). It is possible for the same mode to act in
46 both capacities.
47
48 An application may have zero-to-many API modes, but only one UI mode.
49 API modes work within a standard [RFC2617][] HTTP Authorization
50 interface, while UI modes have broad access to the Rack environment to
51 prompt the user as necessary.
52
3438fa9 @rsutphin Reword for public release.
rsutphin authored
53 All the included modes are described in the documentation of the
54 {Aker::Modes} module. See their documentation for more information.
55 If you would like to implement your own mode, see {Aker::Modes::Base}.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
56
57 #### API vs. UI
58
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
59 Aker uses the following heuristic to determine whether to attempt to
702ff24 Tweaks and corrections suggested by David.
Rhett Sutphin authored
60 authenticate a particular request using the configured UI mode or API
61 mode(s):
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
62
63 * If there are no API modes configured, requests are always handled by
64 the UI mode.
65 * If the HTTP Accept header includes `text/html` (literally includes
66 it, not matches it), the request is handled by the UI mode.
67 * If the HTTP User-Agent header includes `Mozilla`, the request is
68 handled by the UI mode.
69 * Otherwise, the request is handled by the API mode(s).
70
71 [RFC2617]: http://www.ietf.org/rfc/rfc2617.txt
72
73 ### Configuration
74
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
75 The aker **configuration** is where you define the authorities and
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
76 modes (and their parameters) for your application. It's a class whose
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
77 instances can be initialized both {Aker::Configuration traditionally}
78 and using a {Aker::ConfiguratorLanguage DSL}. There's a global
79 instance ({Aker.configuration}) which will be sufficient for most
80 uses and which can be updated using the DSL via {Aker.configure}.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
81
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
82 Since {Aker.configure} updates the configuration (rather than
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
83 replacing it), it is worthwhile to consider splitting up your
84 configuration into environment-specific and common parts. For
702ff24 Tweaks and corrections suggested by David.
Rhett Sutphin authored
85 instance, you might have the common configuration:
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
86
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
87 Aker.configure {
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
88 ui_mode :form
89 api_mode :http_basic
90 }
91
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
92 And then for your development environment use:
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
93
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
94 Aker.configure {
3438fa9 @rsutphin Reword for public release.
rsutphin authored
95 authority Aker::Authorities::Static.from_file("#{Rails.root}/environments/development-users.yml")
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
96 central "/etc/nubic/aker-local.yml"
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
97 }
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
98
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
99 And in your tests use:
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
100
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
101 Aker.configure {
102 authority Aker::Authorities::Static.from_file("#{Rails.root}/spec/test-users.yml")
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
103 }
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
104
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
105 But then in production use:
106
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
107 Aker.configure {
3438fa9 @rsutphin Reword for public release.
rsutphin authored
108 authorities :ldap
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
109 central "/etc/nubic/aker-prod.yml"
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
110 }
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
111
112 Using form authentication
113 -------------------------
114
8e75e51 @rsutphin Consolidate form mode and related code under `Aker::Form`.
rsutphin authored
115 Aker's {Aker::Form::Mode :form} mode provides a traditional HTML
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
116 form for user authentication. It works with one or more authorities
117 which handle the `:user` credential kind — compatible
99b26e1 @rsutphin Rename Aker::Authorities::Ldap -> Aker::Ldap::Authority.
rsutphin authored
118 authorities that ship with Aker are {Aker::Ldap::Authority
b590035 @rsutphin Fix bad refs in yardoc.
rsutphin authored
119 :ldap}, and {Aker::Authorities::Static :static}.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
120
121 `:form` is the default UI mode. If you want to explicitly configure
122 it, do like so:
123
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
124 Aker.configure {
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
125 authorities :static # whatever is appropriate for your app
126 ui_mode :form
127 }
128
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
129 Using CAS
130 ---------
131
934382f @rsutphin Consolidate all CAS functionality under the `Aker::Cas` module.
rsutphin authored
132 Aker's {Aker::Cas::ServiceMode :cas} mode provides interactive user
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
133 authentication via an external CAS 2 server. The
934382f @rsutphin Consolidate all CAS functionality under the `Aker::Cas` module.
rsutphin authored
134 {Aker::Cas::ProxyMode :cas_proxy} mode complements `:cas` by providing
135 non-interactive authentication using CAS proxy tickets. Each of these
136 modes works with an authority which can handle the corresponding
137 credential kind (i.e., `:cas` needs a `:cas`-handling authority). The
138 {Aker::Cas::Authority :cas} authority handles both. Here's an
139 example configuration:
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
140
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
141 Aker.configure {
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
142 authority :cas
143 ui_mode :cas
144 api_mode :cas_proxy # don't include unless needed
145 }
146
147 (The `:static` authority can also verify `:cas` and `:cas_proxy`
148 credentials, but it is relatively awkward to set up and so is left as
149 an exercise for the adventurous integrated tester.)
150
151 Since the CAS server provides authentication only, you may also want
152 to configure an authority to provide authorization information.
153
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
154 Authenticating a RESTful API
155 ----------------------------
156
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
157 As noted above, Aker has specific support for [RFC2617][]-style
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
158 standard HTTP authentication. It supports multiple simultaneous API
159 authentication modes. The most common case for multiple API modes
160 will be CAS-protected APIs which also need to provide non-interactive
161 API access (e.g., for cron jobs, since they are not run in the context
162 of a user logged into any particular application). Here's a sample
163 configuration:
164
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
165 Aker.configure {
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
166 ui_mode :cas
167 api_mode :http_basic, :cas_proxy
168
3438fa9 @rsutphin Reword for public release.
rsutphin authored
169 authorities :cas, :ldap
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
170
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
171 central "/etc/nubic/aker-local.yml"
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
172 }
173
174 In this case, the CAS server will be used for interactive logins and
175 for CAS proxy ticket validation, while HTTP Basic-authenticated
ff55f6a Eliminate references to the Pers authority: it's not part of Aker.
David Yip authored
176 requests will be validated using the `:ldap` authority.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
177
96d188f Outline for README. Done with #2809.
Rhett Sutphin authored
178 Rack (and Rails) integration
179 ----------------------------
180
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
181 Aker's web application integration is based on [Rack][]. This means
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
182 it can be used with nearly any ruby web framework, including Sinatra,
39fbc9f Remove "Rails 3 support coming soon" note from the README.
David Yip authored
183 Camping, etc., in addition to Rails.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
184
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
185 In your Aker-protected Rack application, you have access to a
3438fa9 @rsutphin Reword for public release.
rsutphin authored
186 `"aker.check"` key in the Rack environment. This key will yield an
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
187 instance of {Aker::Rack::Facade} which provides methods for
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
188 determining who is logged in, checking permissions, requiring
189 authentication, etc. See its API documentation for more information.
190
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
191 To configure Aker into your Rack application, use
192 {Aker::Rack.use_in}. See that method's API documentation for more
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
193 information.
194
195 #### Rails
196
3438fa9 @rsutphin Reword for public release.
rsutphin authored
197 While Rack support is built into the main Aker gem, Rails support (for
198 both Rails 2.3 and 3.x) is in a separate gem plugin. See the README
199 in the [`aker-rails` gem][aker-rails] for more information about it.
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
200
201 [Rack]: http://rack.rubyforge.org/
3438fa9 @rsutphin Reword for public release.
rsutphin authored
202 [aker-rails]: https://github.com/NUBIC/aker-rails
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
203
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
204 Aker outside of a Rack app
3438fa9 @rsutphin Reword for public release.
rsutphin authored
205 --------------------------
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
206
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
207 Aker's authorities are independent of its HTTP integration, so they
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
208 may be used in any ruby script or application. Here's an example:
209
210 #!/usr/bin/env ruby
211
212 require 'rubygems'
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
213 require 'aker'
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
214
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
215 Aker.configure {
3438fa9 @rsutphin Reword for public release.
rsutphin authored
216 authorities :ldap, :static
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
217 central "/etc/nubic/aker-staging.yml"
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
218 }
219
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
220 u = Aker.authority.valid_credentials?(:user, 'wakibbe', 'ekibder')
221 # => valid_credentials? returns a Aker::User on success
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
222
223 if !u
224 $stderr.puts "Bad credentials"
225 exit(1)
226 elsif u.permit?('Admin')
42e7b72 @rsutphin Bulk rename Bcsec -> Aker.
rsutphin authored
227 lookedup = Aker.authority.find_user(ARGV[0])
a0a33e2 Complete README for bcsec 2.0.
Rhett Sutphin authored
228 if lookedup
229 puts "#{ARGV[0]} is the username of #{lookedup.full_name}"
230 else
231 puts "#{ARGV[0]} isn't a valid username"
232 end
233 else
234 $stderr.puts "Unauthorized"
235 exit(2)
236 end
237
238 See the rest of the API documentation for more information.
239
3438fa9 @rsutphin Reword for public release.
rsutphin authored
240 Extending Aker
241 --------------
242
243 Aker was built for extensibility. Here are the highlights; see the
244 relevant sections above for more.
245
b17a922 @rsutphin Further documentation improvements.
rsutphin authored
246 * {Aker::Authorities::Composite#valid_credentials? Authentication} and
247 {Aker::Authorities::Composite#amplify! authorization} can be
248 provided by implementing an {Aker::Authorities authority}. An
249 application can configure in multiple authorities and their results
250 will be intelligently combined. Authorities can also implement
251 {Aker::Authorities::Composite#on_authentication_success success} and
252 {Aker::Authorities::Composite#on_authentication_failure failure}
253 callbacks to provide for auditing or
254 {Aker::Authorities::Composite#veto? lockout} features.
3438fa9 @rsutphin Reword for public release.
rsutphin authored
255 * An HTTP-based credential presentation mechanism can be implemented
b17a922 @rsutphin Further documentation improvements.
rsutphin authored
256 as a {Aker::Modes mode}. E.g., you would write a mode to adapt to a
257 legacy single-sign-on system.
3438fa9 @rsutphin Reword for public release.
rsutphin authored
258 * Authorities and modes can be customized through
259 {Aker::Configuration#parameters_for parameters} included in the
b17a922 @rsutphin Further documentation improvements.
rsutphin authored
260 {Aker::Configuration configuration}.
3438fa9 @rsutphin Reword for public release.
rsutphin authored
261 * Reusable extensions can be packaged as gems and registered alongside
262 Aker's built-in functionality. Extensions may use
263 {Aker::Configuration::Slice slices} to register themselves, set
b17a922 @rsutphin Further documentation improvements.
rsutphin authored
264 defaults parameter values, and register middleware that will be
265 included relative to Aker's own middleware.
3438fa9 @rsutphin Reword for public release.
rsutphin authored
266
267 Limitations
268 -----------
269
270 Aker's original iteration was a rails plugin built to assist the
271 Northwestern University Biomedical Informatics Center in transitioning
272 legacy systems to Ruby on Rails. Since then it's been used in dozens
273 of applications, both ports of existing systems and ones newly
274 built.
275
276 While it can be adapted to many kinds of applications, it is probably
277 not a good choice if you are not integrating with an existing
278 authentication or authorization backend. It does not include any
279 mechanism for provisioning users or letting users sign up for accounts
280 on their own. Such things could be built for it, but if that's what
281 you need then one of the other existing ruby security frameworks might
282 get you up and running faster.
Something went wrong with that request. Please try again.