account_authz 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +35 -0
- data/app/controllers/concerns/account_authz/authorization.rb +34 -0
- data/lib/account_authz/version.rb +1 -1
- data/the_local/agents/account_authz-develop.md +46 -11
- data/the_local/agents/account_authz-info.md +21 -1
- data/the_local/agents/account_authz-install.md +1 -0
- data/the_local/interface.yml +4 -0
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: '08736d6d036391393f04c3ec1f8c5316e524020761284be3b0b092a8887d981a'
|
|
4
|
+
data.tar.gz: bf362208cbe556157c80554e7b7f9fefef06985f60d80743ba856be5cc04af08
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 8d8421969bc99f85c0a308e612d6d8900e82c9d849c6d7c24563191daeab7442bb7ec3cc1223903c4ac939fb36270e3c5162b2dbbcc1c36abd325170dd0ec39d
|
|
7
|
+
data.tar.gz: e1abfff9d51b4d10d5e855b45c9212fbb900a3fb2f5b1d58f71921aa0e965edf6ade49b2802795eef45146822f77d4149c7dbad749fbc908af508a1df81cb9b0
|
data/README.md
CHANGED
|
@@ -34,6 +34,41 @@ AccountAuthz.can?(grants, :view_fulfillment) # => true/false
|
|
|
34
34
|
AccountAuthz.approved_metrics(grants) # => [:revenue, :deals]
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
+
## A permission for every action
|
|
38
|
+
|
|
39
|
+
A controller that includes `AccountAuthz::Authorization` can refuse every
|
|
40
|
+
action that does not name the permission it needs:
|
|
41
|
+
|
|
42
|
+
```ruby
|
|
43
|
+
class LedgersController < ApplicationController
|
|
44
|
+
include AccountAuthz::Authorization
|
|
45
|
+
|
|
46
|
+
refuse_actions_without_a_permission
|
|
47
|
+
requires_permission :revenue, only: :show
|
|
48
|
+
open_to_every_member only: :index, reason: "Every member reads the list of ledgers."
|
|
49
|
+
end
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- `refuse_actions_without_a_permission` refuses every action of the controller
|
|
53
|
+
and its subclasses unless the action names a permission and the current
|
|
54
|
+
member holds it in the current account.
|
|
55
|
+
- `requires_permission :capability, only: [:actions]` names the permission
|
|
56
|
+
those actions need.
|
|
57
|
+
- `open_to_every_member only: [:actions], reason: "..."` lets any signed-in
|
|
58
|
+
member open those actions, whatever permissions they hold.
|
|
59
|
+
- A refused action answers 403 Forbidden. A controller answers differently by
|
|
60
|
+
overriding the private method `refuse_the_action`:
|
|
61
|
+
|
|
62
|
+
```ruby
|
|
63
|
+
class HiddenLedgersController < LedgersController
|
|
64
|
+
private
|
|
65
|
+
|
|
66
|
+
def refuse_the_action
|
|
67
|
+
head :not_found
|
|
68
|
+
end
|
|
69
|
+
end
|
|
70
|
+
```
|
|
71
|
+
|
|
37
72
|
## Installation
|
|
38
73
|
|
|
39
74
|
```ruby
|
|
@@ -6,13 +6,47 @@ module AccountAuthz
|
|
|
6
6
|
module Authorization
|
|
7
7
|
extend ActiveSupport::Concern
|
|
8
8
|
|
|
9
|
+
EVERY_MEMBER = :every_member
|
|
10
|
+
|
|
9
11
|
included do
|
|
10
12
|
include Pundit::Authorization
|
|
11
13
|
helper_method :can?
|
|
14
|
+
class_attribute :action_permissions, instance_writer: false, default: {}
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
class_methods do
|
|
18
|
+
def refuse_actions_without_a_permission
|
|
19
|
+
before_action :refuse_an_action_its_member_may_not_take
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
def requires_permission(capability, only:)
|
|
23
|
+
self.action_permissions = action_permissions.merge(Array(only).to_h { |action| [ action.to_s, capability ] })
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def open_to_every_member(only:, reason:)
|
|
27
|
+
requires_permission(EVERY_MEMBER, only: only)
|
|
28
|
+
end
|
|
12
29
|
end
|
|
13
30
|
|
|
14
31
|
def can?(capability)
|
|
15
32
|
Current.account_id.present? && current_member&.can?(capability, account_id: Current.account_id) || false
|
|
16
33
|
end
|
|
34
|
+
|
|
35
|
+
private
|
|
36
|
+
|
|
37
|
+
def refuse_an_action_its_member_may_not_take
|
|
38
|
+
refuse_the_action unless may_take_this_action?
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
def refuse_the_action
|
|
42
|
+
head :forbidden
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
def may_take_this_action?
|
|
46
|
+
capability = action_permissions[action_name]
|
|
47
|
+
return current_member.present? if capability == EVERY_MEMBER
|
|
48
|
+
|
|
49
|
+
capability.present? && can?(capability)
|
|
50
|
+
end
|
|
17
51
|
end
|
|
18
52
|
end
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: account_authz-develop
|
|
3
|
-
description: Use PROACTIVELY for declaring capabilities (permissions and metrics), defining role templates, seeding an account's default roles, creating roles, ranking roles so a manager can change only members and roles below them, assigning or revoking a member's roles, checking whether one member may change another member's roles, checking whether an editor may create or edit a role with a given rank and capabilities, checking whether taking a role, removing a member, or changing a role's capabilities would leave an account with nobody who can manage its members, checking whether a member can do something, filtering which metrics a member may see, writing Pundit policies that gate actions on a capability, choosing which members the members page lists, how it finds a member or an invitation addressed by a code or token, how it invites a person to an account, which invitations it shows as still waiting for an answer, how it sends one again and cancels one, and how it removes a member from an account, and which capability lets a member open it to invite, send an invitation again, cancel one, remove a member, and give and take roles, choosing which capability lets a member open the role pages to create and edit roles, which viewers see the links between the members page and the role pages, and showing or rewording the message a manager sees when the members page or role pages refuse a change — MUST BE USED instead of hand-rolling role checks, permission flags, role hierarchies, limits on the rank or capabilities an editor may give a role, last-admin checks, role management screens, member invite, waiting invitation or removal screens, refusal messages, or ad hoc authorization in controllers and views.
|
|
3
|
+
description: Use PROACTIVELY for declaring capabilities (permissions and metrics), defining role templates, seeding an account's default roles, creating roles, ranking roles so a manager can change only members and roles below them, assigning or revoking a member's roles, checking whether one member may change another member's roles, checking whether an editor may create or edit a role with a given rank and capabilities, checking whether taking a role, removing a member, or changing a role's capabilities would leave an account with nobody who can manage its members, checking whether a member can do something, filtering which metrics a member may see, writing Pundit policies that gate actions on a capability, making a controller refuse every action that names no permission, naming the permission each controller action needs, opening an action to every signed-in member with a reason, and choosing how a refused action answers, choosing which members the members page lists, how it finds a member or an invitation addressed by a code or token, how it invites a person to an account, which invitations it shows as still waiting for an answer, how it sends one again and cancels one, and how it removes a member from an account, and which capability lets a member open it to invite, send an invitation again, cancel one, remove a member, and give and take roles, choosing which capability lets a member open the role pages to create and edit roles, which viewers see the links between the members page and the role pages, and showing or rewording the message a manager sees when the members page or role pages refuse a change — MUST BE USED instead of hand-rolling role checks, permission flags, role hierarchies, limits on the rank or capabilities an editor may give a role, last-admin checks, role management screens, member invite, waiting invitation or removal screens, refusal messages, or ad hoc authorization in controllers and views, including per-action permission checks written by hand.
|
|
4
4
|
tools: Read, Write, Edit, Grep
|
|
5
5
|
scope: authorization — capability catalog, roles, and Pundit enforcement in multi-tenant Rails apps
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
You implement authorization in a host app that already has account_authz installed, using only the entry points below. You always keep capability keys in the catalog, keep roles as database records, gate actions through policies that inherit `AccountAuthz::ApplicationPolicy
|
|
8
|
+
You implement authorization in a host app that already has account_authz installed, using only the entry points below. You always keep capability keys in the catalog, keep roles as database records, gate actions through policies that inherit `AccountAuthz::ApplicationPolicy` or through the permission each controller action names, decide who may change whose roles and what rank and capabilities an editor may give a role through `AccountAuthz::Reach`, keep an account's last member manager through `AccountAuthz::LastManager`, and word refusals through the `account_authz.refusals` locale keys.
|
|
9
9
|
|
|
10
10
|
## What account_authz is
|
|
11
11
|
|
|
12
|
-
AccountAuthz is capability-based authorization for multi-tenant Rails apps. The app declares a fixed list of capability keys in code, each account holds roles as records that bundle a subset of those keys, and a member's access is the union of the capabilities of the roles assigned to them. A member is a person's membership in one account, not the person, so a person who belongs to three accounts is three members, and an app with no membership record lets the person hold roles directly instead. Each role also has an integer rank, and a manager may change only members and roles ranked below the manager's highest role in the account. On account_authz's role pages, an editor may give a role only capabilities the editor holds and a rank no higher than the editor's own. AccountAuthz's members page and role pages refuse a change that would leave an account with nobody holding a role that grants the members capability. When they refuse a change for rank, for capabilities the editor does not hold, for the last member manager, or because a member may not be removed, they change nothing and send the manager back with a flash alert saying why. Fire this local when code needs to declare a capability, create, seed or rank roles, assign roles to a member, answer "may this member do X", answer "may this manager change this member or hand out this role", answer "may this editor create or edit this role with this rank and these capabilities", answer "would this change leave the account with no member manager", pick which metrics a member may see, write a policy that authorizes an action, decide who the members page lists, how it finds a member or invitation by address, how it invites a person, which invitations it shows as still waiting and how it sends one again or cancels one, how it removes members, and who may open it, decide who may open the role pages to create and edit roles, or show or reword the message a refused change shows.
|
|
12
|
+
AccountAuthz is capability-based authorization for multi-tenant Rails apps. The app declares a fixed list of capability keys in code, each account holds roles as records that bundle a subset of those keys, and a member's access is the union of the capabilities of the roles assigned to them. A member is a person's membership in one account, not the person, so a person who belongs to three accounts is three members, and an app with no membership record lets the person hold roles directly instead. Each role also has an integer rank, and a manager may change only members and roles ranked below the manager's highest role in the account. On account_authz's role pages, an editor may give a role only capabilities the editor holds and a rank no higher than the editor's own. AccountAuthz's members page and role pages refuse a change that would leave an account with nobody holding a role that grants the members capability. When they refuse a change for rank, for capabilities the editor does not hold, for the last member manager, or because a member may not be removed, they change nothing and send the manager back with a flash alert saying why. Fire this local when code needs to declare a capability, create, seed or rank roles, assign roles to a member, answer "may this member do X", answer "may this manager change this member or hand out this role", answer "may this editor create or edit this role with this rank and these capabilities", answer "would this change leave the account with no member manager", pick which metrics a member may see, write a policy that authorizes an action, make a controller refuse every action that names no permission, name the permission an action needs or open it to every signed-in member, choose how a refused action answers, decide who the members page lists, how it finds a member or invitation by address, how it invites a person, which invitations it shows as still waiting and how it sends one again or cancels one, how it removes members, and who may open it, decide who may open the role pages to create and edit roles, or show or reword the message a refused change shows.
|
|
13
13
|
|
|
14
14
|
## Interface
|
|
15
15
|
|
|
@@ -34,6 +34,10 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
|
|
|
34
34
|
- `member.can?` — `member.can?(capability, account_id: nil)` returns true when that union includes `capability`.
|
|
35
35
|
- `member.approved_metrics` — `member.approved_metrics(account_id: nil)` returns the catalog metrics the member holds.
|
|
36
36
|
- `AccountAuthz::ApplicationPolicy` — the base class for Pundit policies, taking `(member, record)`, exposing `member` and `record`, and providing `can?(capability)`.
|
|
37
|
+
- `refuse_actions_without_a_permission` — called in the body of a host controller set up for account_authz authorization, such as the host's `ApplicationController`, it refuses each action of that controller and of every controller inheriting from it unless the signed-in member may take that action under the permission it names.
|
|
38
|
+
- `requires_permission` — `requires_permission(:capability, only: [:action, ...])` names the capability a member needs in the current account to take those actions, and `only:` takes one action name or a list.
|
|
39
|
+
- `open_to_every_member` — `open_to_every_member(only: [:action, ...], reason: "...")` lets every signed-in member take those actions whatever roles they hold, and `reason:` is required.
|
|
40
|
+
- `refuse_the_action` — the private controller method that answers a refused action, which returns `head :forbidden` unless the controller defines its own.
|
|
37
41
|
- `AccountAuthz.members_source` — `AccountAuthz.members_source = AccountMembers` sets the object the members page uses to list an account's members, find one member or invitation by its address, invite a person, list the invitations still waiting for an answer, send one of those again, cancel one, ask whether a member may be removed, and remove a member, and it has no default.
|
|
38
42
|
- `AccountAuthz.members_capability` — `AccountAuthz.members_capability = :key` sets the capability a member needs in the current account to open the members page and invite, send an invitation again, cancel one, remove a member, or give or take roles on it, and it defaults to `:manage_members`.
|
|
39
43
|
- `AccountAuthz.roles_capability` — `AccountAuthz.roles_capability = :key` sets the capability a member needs in the current account to open the role pages and create or edit roles on them, and it defaults to `:manage_roles`.
|
|
@@ -115,7 +119,37 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
|
|
|
115
119
|
|
|
116
120
|
The base class defines no `Scope`, so a policy used with `policy_scope` needs its own. The `member` a policy receives is the object Pundit passes as its user, and it must be an instance of the host's role-holding model. The base `can?(capability)` checks only the roles the member holds in the current request's account, and it returns false when no current account is set, so the request must set the current account before any policy runs. The controller `can?` helper follows the same rule.
|
|
117
121
|
|
|
118
|
-
11. **
|
|
122
|
+
11. **Name a permission for each controller action, if the host wants new actions closed until someone names one.** In a host controller set up for account_authz authorization, such as the host's `ApplicationController` or a controller inheriting from it, turn the rule on and name what each action needs:
|
|
123
|
+
|
|
124
|
+
```ruby
|
|
125
|
+
class OrdersController < ApplicationController
|
|
126
|
+
refuse_actions_without_a_permission
|
|
127
|
+
|
|
128
|
+
requires_permission :view_fulfillment, only: [:index, :show]
|
|
129
|
+
requires_permission :edit_orders, only: :update
|
|
130
|
+
open_to_every_member only: :help, reason: "Every member reads the help page."
|
|
131
|
+
end
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The rule is off until a controller calls `refuse_actions_without_a_permission`, so `requires_permission` and `open_to_every_member` change nothing in a controller where it is off. Once a controller turns it on, it applies to that controller and to every controller inheriting from it. A subclass keeps every action its parent named and adds its own, and naming the same action again replaces the permission named for it before. Naming actions in a subclass does not change the parent.
|
|
135
|
+
|
|
136
|
+
- An action named with `requires_permission` is taken only by a signed-in member who holds that capability in the current account, using the same check as the controller `can?` helper. It is refused when no current account is set, so call `refuse_actions_without_a_permission` after the `before_action` that sets the current account. Name the capability as a symbol, because a string never matches a member's capabilities, and declare it in the catalog.
|
|
137
|
+
- An action that names no permission is refused, so every action added later stays refused until someone names its permission.
|
|
138
|
+
- An action named with `open_to_every_member` is taken by any signed-in member, whatever roles they hold, and the current account is not checked. A request with no signed-in member is refused. The `reason:` is required and is not shown anywhere, so write it for the next developer reading the controller. Do not name a permission `:every_member`, because `requires_permission` treats that name the same as `open_to_every_member`.
|
|
139
|
+
|
|
140
|
+
A refused action calls the controller's private `refuse_the_action`, which answers `head :forbidden`. To answer differently, such as with not found, define it as a private method in the controller, and its subclasses use it too:
|
|
141
|
+
|
|
142
|
+
```ruby
|
|
143
|
+
private
|
|
144
|
+
|
|
145
|
+
def refuse_the_action
|
|
146
|
+
head :not_found
|
|
147
|
+
end
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The engine's controllers inherit from the host's `ApplicationController` and name no action permissions, so turning the rule on in the host's `ApplicationController` refuses every request to the members pages and the role pages. Ask the developer which controllers turn the rule on, and whether the engine's pages are served, before turning it on in the host's base controller. For each action, ask which capability it needs, or whether it is open to every signed-in member and why.
|
|
151
|
+
|
|
152
|
+
12. **Configure the members pages, if the host serves them.** The members page opens with a `Members` heading, which carries a `Roles` link to the roles page only when the viewer holds the roles capability in the current account. Below it, a `Team` section with an `Invite` link lists each member's name, email, and the names of the roles they hold in the current account, or `None`, and each name opens that member's page. Below that, an `Invited` section lists each invitation the source says is still waiting for an answer, with its name, its email, a `Send again` button and a `Cancel` button, shown to every member who can open the page. The `Invite` link opens an invite page holding a required `Name` field, a required `Email` field and an `Invite` button. A member's page shows the member's name and email, a link back to the members page, and the roles they hold in the current account. When the viewer reaches the member, it also shows a `Take <role>` button for each held role the viewer reaches, a `Give <role>` button for each of the current account's roles the viewer reaches that the member does not hold, and a `Remove from team` button when the source says that member may be removed. It leaves out a take button when `lost_by_taking?` is true for that member and role, and the `Remove from team` button when `lost_by_removing?` is true for that member. A member the viewer does not reach is shown with no buttons. The invite form and every button return to the members page. The pages create no roles, so an account with no roles shows no give buttons. The members pages and the role pages are drawn inside the layout the host's `ApplicationController` uses, so nothing in this step or the next changes how they look.
|
|
119
153
|
|
|
120
154
|
Each member's page and each button for a member is addressed by the member's `to_param`, and each invitation button by the invitation's `to_param`, so whatever those return is the address account_authz later looks the record up by. Each `Give` and `Take` button addresses its role by the role's code, not its id.
|
|
121
155
|
|
|
@@ -192,15 +226,15 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
|
|
|
192
226
|
|
|
193
227
|
- `member(account_id, address)` returns the member of that account at the address its `to_param` gives. Add it when members are addressed by a code or anything else `find` on `members` does not look up. When the source answers it, the member's page, giving or taking a role, and removing a member find the member only through it. AccountAuthz does not check that the record it returns belongs to the account, so it must return only a member of that account. It must raise `ActiveRecord::RecordNotFound` when no member is at the address, because account_authz does not handle `nil`.
|
|
194
228
|
- `invitation(account_id, address)` returns the waiting invitation of that account at the address its `to_param` gives. Add it when invitations are addressed by a token or anything else `find` on `invitations` does not look up. When the source answers it, sending an invitation again and cancelling one find the invitation only through it. AccountAuthz does not check that the record it returns belongs to the account or is still waiting, so it must return only such an invitation. It must raise `ActiveRecord::RecordNotFound` when no invitation is at the address, because account_authz does not handle `nil`.
|
|
195
|
-
- `member_for(account_id:, person:)` returns the membership the signed-in member holds in that account, or `nil`. Add it only when the host's signed-in member is the person rather than the membership that
|
|
229
|
+
- `member_for(account_id:, person:)` returns the membership the signed-in member holds in that account, or `nil`. Add it only when the host's signed-in member is the person rather than the membership that holds roles. When the source answers it, a give, take or removal measures the viewer's reach from the membership it returns, and from the signed-in member when it returns `nil`. The capability check that opens the pages, the buttons a member's page shows, and the `invited_by:` passed to `invite` still use the signed-in member as it is.
|
|
196
230
|
|
|
197
|
-
A member's page, give, take or removal for an address the member lookup does not find raises `ActiveRecord::RecordNotFound`. A give or take for a role address that is not the code of a role in the current account also raises `ActiveRecord::RecordNotFound` when the viewer reaches the member, and so does a role's id. A give or take for a member or role the viewer does not reach changes nothing and returns to the members page with a refusal message. So does a take when `lost_by_taking?` is true for that member and role. A removal does the same when the viewer does not reach the member, when `removable?` returns false, or when `lost_by_removing?` is true for that member. Step
|
|
231
|
+
A member's page, give, take or removal for an address the member lookup does not find raises `ActiveRecord::RecordNotFound`. A give or take for a role address that is not the code of a role in the current account also raises `ActiveRecord::RecordNotFound` when the viewer reaches the member, and so does a role's id. A give or take for a member or role the viewer does not reach changes nothing and returns to the members page with a refusal message. So does a take when `lost_by_taking?` is true for that member and role. A removal does the same when the viewer does not reach the member, when `removable?` returns false, or when `lost_by_removing?` is true for that member. Step 14 lists which message each refusal shows. Sending again or cancelling an invitation at an address the invitation lookup does not find raises `ActiveRecord::RecordNotFound`. Neither rank nor the last member manager limits inviting or the invitation buttons, so every member who can open the members page may invite a person and send again or cancel any invitation the account is waiting on. An invite request that sends neither a name nor an email fails with an error rather than a refusal message. With no source set, every request to the members pages, the invite form and the buttons from a member who holds the capability raises an error, apart from opening the invite page.
|
|
198
232
|
|
|
199
233
|
Ask the developer which capability opens the members page, a member's page and the invite page: the default `:manage_members`, or a key the app already uses for managing its team. The same capability is required to invite, send an invitation again, cancel one, remove a member, and give or take a role. Set it as a symbol, because a string never matches a member's capabilities. Declare that key in the catalog as a permission, because otherwise no role can grant it and every request to those pages gets 403. A request with no signed-in member or no current account also gets 403.
|
|
200
234
|
|
|
201
235
|
Tell the developer that the page refuses only the change that removes the last holder of a role granting the members capability. While another member still holds such a role, a manager at the account's top rank can take such a role from, or remove, any member `removable?` allows, including themselves.
|
|
202
236
|
|
|
203
|
-
|
|
237
|
+
13. **Configure the role pages, if the host serves them.** The roles page opens with a `Members` button that goes to the members page, shown to every viewer, and a viewer without the members capability who presses it gets 403. Below it, the roles page lists the current account's roles by name, with the number of capabilities each one grants, and each name opens that role's edit form. Its new role button opens a form with a name field, a rank field, and one checkbox per catalog key, labelled with the key itself, and saving creates the role in the current account. The edit form is the same form filled in with the role's name, rank and capabilities, and saving renames the role, sets its rank, and replaces its capabilities. Below the list, the roles page shows one button per default template, which creates a role from that template at rank 0, and it leaves that part out when no template is declared `default: true`. Each save and each template button returns to the roles page. The pages delete no roles. In the initializer, set the capability:
|
|
204
238
|
|
|
205
239
|
```ruby
|
|
206
240
|
AccountAuthz.roles_capability = :manage_team
|
|
@@ -222,7 +256,7 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
|
|
|
222
256
|
|
|
223
257
|
Tell the developer what the role pages still allow. An editor at the account's top rank can edit every role in the account, including a role that editor holds. Any editor can lower the rank of a role they reach and untick any capability on it, including capabilities the editor does not hold. An editor can raise a role they reach to their own rank, which gives its holders at least the same reach over members and roles as the editor. The role pages do not stop an editor from removing the roles capability from every role, so an account can be left with no member who can open them.
|
|
224
258
|
|
|
225
|
-
|
|
259
|
+
14. **Show and word the refusal messages, if the host serves either page.** A refused change sets `flash[:alert]` and redirects. AccountAuthz's pages do not display the flash themselves, so the manager sees the message only when the layout the host's `ApplicationController` uses displays `flash[:alert]`. Ask the developer whether that layout already displays it, and add it there if not.
|
|
226
260
|
|
|
227
261
|
Each refusal shows the message under one key:
|
|
228
262
|
|
|
@@ -255,9 +289,9 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
|
|
|
255
289
|
|
|
256
290
|
A request from a member without the page's capability, with no signed-in member, or with no current account still gets 403 with no message.
|
|
257
291
|
|
|
258
|
-
|
|
292
|
+
15. **Reset in tests.** Call `AccountAuthz.reset!` in test setup when a test declares its own catalog or templates, then declare what the test needs. After `reset!` the catalog is empty, so creating any role with capabilities fails validation until the catalog is declared again. `reset!` returns `members_capability` to `:manage_members` and `roles_capability` to `:manage_roles`, but does not clear `members_source`, so a test that sets a source must set it back itself.
|
|
259
293
|
|
|
260
|
-
|
|
294
|
+
16. **Run the test suite** after each change.
|
|
261
295
|
|
|
262
296
|
## Conventions
|
|
263
297
|
|
|
@@ -265,12 +299,13 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
|
|
|
265
299
|
- Capability keys exist only in the catalog, and are never stored as records or built from user input.
|
|
266
300
|
- Roles are records, and are never hardcoded in application code; starter roles come from templates.
|
|
267
301
|
- Every capability check goes through `member.can?`, `AccountAuthz.can?`, or a policy that inherits `AccountAuthz::ApplicationPolicy`, never through role names or flags compared in controllers or views.
|
|
302
|
+
- A controller that turns on `refuse_actions_without_a_permission` names each action's permission with `requires_permission` or `open_to_every_member`, never with a hand-written `before_action` that checks a capability.
|
|
268
303
|
- Every capability check in a multi-tenant request passes the current account's id, unless the developer has decided otherwise.
|
|
269
304
|
- The members capability and the roles capability are catalog keys like any other, and are never checked by comparing role names.
|
|
270
305
|
- Every host flow where one member changes another member's roles checks `AccountAuthz::Reach` for both the member and the role, and never compares ranks by hand.
|
|
271
306
|
- Every host flow where a member creates or edits a role checks `AccountAuthz::Reach` for the role, the rank and the capabilities, and never compares ranks or capability lists by hand.
|
|
272
307
|
- Every host flow that takes a role, removes a member, or changes a role's capabilities checks `AccountAuthz::LastManager`, and never counts an account's managers by hand.
|
|
273
308
|
- A refusal message is reworded under `account_authz.refusals` in the app's own locale files, and a host flow that explains a refusal reuses those keys rather than writing its own text for the same reason.
|
|
274
|
-
- Adding the gem, running its migrations, choosing which model holds roles, preparing the host's models and controllers, making the members page and role pages reachable, and loading keystone_ui's styles into the host's layout are out of scope for this local.
|
|
309
|
+
- Adding the gem, running its migrations, choosing which model holds roles, preparing the host's models and controllers for authorization, making the members page and role pages reachable, and loading keystone_ui's styles into the host's layout are out of scope for this local.
|
|
275
310
|
- AccountAuthz's pages give and take an account's roles and create, rename, rank, and change the capabilities of roles, so the host builds any screen that deletes a role.
|
|
276
311
|
- AccountAuthz's members page hands inviting, listing waiting invitations, sending one again, cancelling one and removing a member to the members source, so the host stores each invitation, sends it, decides when it stops waiting for an answer, builds the flow for accepting one, and decides what removing a member does to its records.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: account_authz-info
|
|
3
|
-
description: Use to learn what account_authz offers — its capability catalog, account roles and ranks, members as account memberships, reach limits on who may manage whom, the rule that every account keeps a member manager, the members, member, invite and role pages and the team section with their invitations and refusal messages, how roles, members and invitations are addressed, and Pundit enforcement.
|
|
3
|
+
description: Use to learn what account_authz offers — its capability catalog, account roles and ranks, members as account memberships, reach limits on who may manage whom, the rule that every account keeps a member manager, the members, member, invite and role pages and the team section with their invitations and refusal messages, how roles, members and invitations are addressed, refusing every controller action that names no permission, and Pundit enforcement.
|
|
4
4
|
tools: Read
|
|
5
5
|
scope: authorization — capability catalog, roles, and Pundit enforcement in multi-tenant Rails apps
|
|
6
6
|
---
|
|
@@ -51,6 +51,9 @@ two locals:
|
|
|
51
51
|
- declaring the catalog, defining roles and templates, seeding them, and
|
|
52
52
|
assigning roles to members;
|
|
53
53
|
- checking capabilities and approved metrics, and writing policies;
|
|
54
|
+
- making a host controller refuse every action that names no permission,
|
|
55
|
+
naming the permission each action needs, opening an action to every
|
|
56
|
+
signed-in member, and choosing how a refused action answers;
|
|
54
57
|
- asking whether a manager's rank reaches a member or a role, whether an editor
|
|
55
58
|
may put a set of capabilities or a rank on a role, and whether a change would
|
|
56
59
|
remove the account's last member manager;
|
|
@@ -73,6 +76,8 @@ Decide which of the two you need, then go there.
|
|
|
73
76
|
**account_authz-install**.
|
|
74
77
|
- AccountAuthz is connected and you are adding a capability, a role, a template, or a
|
|
75
78
|
check on an action: use **account_authz-develop**.
|
|
79
|
+
- AccountAuthz is connected and you want a controller to refuse any action
|
|
80
|
+
that does not name its permission: use **account_authz-develop**.
|
|
76
81
|
- AccountAuthz is connected and you are setting up the members pages, their
|
|
77
82
|
invitations and removals, how members and invitations are found by address,
|
|
78
83
|
or the role pages: use **account_authz-develop**.
|
|
@@ -229,6 +234,21 @@ Decide which of the two you need, then go there.
|
|
|
229
234
|
the app names another.
|
|
230
235
|
- **Roles capability** — the capability a person needs to open the role pages and
|
|
231
236
|
to create or change roles there, `manage_roles` unless the app names another.
|
|
237
|
+
- **Permission per action** — a host controller can turn on a rule that refuses
|
|
238
|
+
each of its actions unless the action names the permission it needs. It
|
|
239
|
+
covers that controller and every controller that inherits from it, and a
|
|
240
|
+
subclass keeps the permissions its parent named and may name more. An action
|
|
241
|
+
naming a permission is open only to a member who holds it in the current
|
|
242
|
+
account, so it is refused when no current account is set. An action that
|
|
243
|
+
names no permission is refused, so a new action stays closed until someone
|
|
244
|
+
names one.
|
|
245
|
+
- **Open to every member** — an action marked as needing no permission, which
|
|
246
|
+
any signed-in member may open whatever roles they hold, even with no current
|
|
247
|
+
account set. Marking an action this way requires a written reason.
|
|
248
|
+
- **Refused action** — an action the permission-per-action rule turns away. It
|
|
249
|
+
answers 403 Forbidden unless the controller chooses another answer, such as
|
|
250
|
+
not found. The engine's own pages inherit from the host's base controller and
|
|
251
|
+
name no permissions, so turning the rule on there refuses them too.
|
|
232
252
|
- **Forbidden** — a person without the page's capability, or a request with no
|
|
233
253
|
current account, gets a forbidden response from any engine page. Another
|
|
234
254
|
account's roles, members and waiting invitations cannot be read or changed from
|
|
@@ -43,6 +43,7 @@ A Rails engine for capability-based authorization in multi-tenant apps, hooked i
|
|
|
43
43
|
10. Ask the developer how the current account is found for a request, such as from the subdomain, the signed-in user, or a URL parameter. Add a `before_action` to `ApplicationController` that sets `AccountAuthz::Current.account_id` to that account's integer id. Rails resets it at the end of every request.
|
|
44
44
|
11. Ask the developer whether they want account_authz's pages. The one mount serves both the members pages and the role pages, so the host gets both or neither. If they do not want them, skip this step and steps 12 and 13. If they do, ask which path to serve them under, offering `/account_authz`, and add `mount AccountAuthz::Engine => "/account_authz"` with that path to `config/routes.rb`. The members page is then at that path followed by `/members`, and the roles page at that path followed by `/roles`.
|
|
45
45
|
- The engine's controllers inherit the host's `ApplicationController`, so the sign-in, `current_member`, current account and CSRF protection from the host apply to every page and every form on them.
|
|
46
|
+
- The engine's controllers name no permission for any of their actions. If the host's `ApplicationController` refuses every action that names no permission, every page and every form the mount serves gets a 403 response. Check whether it does. If it does, tell the developer, and hand the choice of where to refuse unnamed actions to the account_authz-develop local, such as a base controller for the host's own controllers that the engine's controllers do not inherit.
|
|
46
47
|
- The pages render inside the layout the host's `ApplicationController` uses, such as `app/views/layouts/application.html.erb`. Route helpers in that layout, such as `root_path`, reach the host's own routes on the pages without a `main_app.` prefix. The exception is a helper whose name the engine also defines: `members_path`, `member_path`, `member_roles_path`, `member_role_path`, `roles_path`, `new_role_path`, `edit_role_path`, `role_path`, `invitations_path`, `new_invitation_path`, `invitation_path` and `resend_invitation_path`, and their `_url` forms. On the engine's pages these reach the engine's routes. Check whether the layout calls any of them. If it does, tell the developer and change each call to start with `main_app.`, such as `main_app.members_path`.
|
|
47
48
|
- The pages are built from keystone_ui components and ship no stylesheet of their own, so that layout must load keystone_ui's styles. Check whether the host already loads them. If it does not and the host has a keystone_ui install local, hand that step to it. Otherwise ask the developer how the host loads keystone_ui's styles before continuing.
|
|
48
49
|
- A change a manager may not make sends them back to a page with a flash alert saying why, and the engine's pages do not show flash messages themselves. Check whether that layout renders `flash[:alert]`. If it does not, tell the developer that refused changes will return to the page with no message, and ask where in the layout to render the alert.
|
data/the_local/interface.yml
CHANGED
|
@@ -43,6 +43,10 @@ develop:
|
|
|
43
43
|
- last_manager.lost_by_taking?
|
|
44
44
|
- last_manager.lost_by_removing?
|
|
45
45
|
- last_manager.lost_by_changing?
|
|
46
|
+
- refuse_actions_without_a_permission
|
|
47
|
+
- requires_permission
|
|
48
|
+
- open_to_every_member
|
|
49
|
+
- refuse_the_action
|
|
46
50
|
|
|
47
51
|
sources:
|
|
48
52
|
- lib/account_authz.rb
|