apiserver authorizers

[William Reade]

Thanks for asking :). Not sure there's a document directly focused on it,
largely because it's relatively simple -- doc/design/
juju-api-design-specification.md just says:

> The authorizer represents a value that can be asked for authorization
> information on its associated authenticated entity. It allows an API
> implementation to ask questions about the client that is currently
connected.

...which does tell you the important thing; and the interface is documented
reasonably clearly in `apiserver/common/interfaces.go`; for example:

> // AuthMachineAgent returns whether the authenticated entity is a
> // machine agent.
> AuthMachineAgent() bool

Honestly, I was expecting it to need to change more than it apparently has
-- it actually seems to have covered our needs pretty well. Anyway, in a
bit more detail:

  * Your facade constructor is passed a common.Authorizer that you can
interrogate to discover properties of the authenticated entity at the other
end of the connection.
  * You should definitely use it to restrict access to the facade as a
whole, so that (e.g.) machine agents can't talk to external facades, and
normal machine agents can't talk to environ-manager-only facades, etc etc.
  * You should probably use it internally as well, to check the actual
arguments refer to entities your worker should be allowed to see.
(sometimes you don't need to; judgment call; but err in favour of checking
if you're at all unsure whether unrestricted access is a good idea for the
client in question.)
  * Those restrictions should be as tight as possible: e.g. if it's a
facade for a per-machine-agent worker, it almost certainly shouldn't be
allowed to query or modify other machines, etc etc.
  * To restate: don't worry about restricting potentially valid use cases,
worry about leaking information or allowing operations that could be abused
by buggy or malicious code.

Regardless, I've just written a wiki page which attempts to illustrate
basic good practice: https://github.com/juju/juju/wiki/API-best-practices

Please let me know if it's useful and/or can/should be improved :-).

Cheers
William


On Wed, Dec 2, 2015 at 2:54 PM, Nate Finch <nate.finch at canonical.com> wrote:

> Auth on the api is a big mystery to me. Is there a document on the
> expected behavior and the functions and types that back it up?
>
> For example, you said "an environ provisioner may have wide-ranging
> powers, but that's no reason to let it see or modify container machines
> that are not its direct responsibility" ... I don't really know what that
> means. This sounds like authorization, but how do you know who is calling
> your api or what they're supposed to be allowed to do?
>
> On Wed, Dec 2, 2015, 6:36 AM William Reade <william.reade at canonical.com>
> wrote:
>
>> The case I spotted yesterday was here:
>> http://reviews.vapour.ws/r/3243/diff/1/?file=167369#file167369line41
>>
>> and in general:
>>
>>   * seeing `_ common.Authorizer` in a parameter list is a sign you're DIW.
>>   * failing to check some auth property when creating the facade is a
>> sign you're DIW.
>>   * failing to pass the auth on to the facade type itself *might* be OK,
>> but should be viewed with some suspicion -- for example:
>>       * an environ provisioner may have wide-ranging powers, but that's
>> no reason to let it see or modify container machines that are not its
>> direct responsibility
>>       * right now, many user-facing facades don't need further
>> authorization once they know it's an authenticated client, but that won't
>> last forever
>>
>> helpful?
>>
>> Cheers
>> William
>>
>> On Wed, Dec 2, 2015 at 12:26 PM, roger peppe <roger.peppe at canonical.com>
>> wrote:
>>
>>> Could you link to the offending change(s) please, so we
>>> can see what doing it wrong looks like?
>>>
>>> On 2 December 2015 at 09:28, William Reade <william.reade at canonical.com>
>>> wrote:
>>> > I just noticed that the unitassigner facade-constructor drops the
>>> authorizer
>>> > on the floor; and I caught a similar case in a review yesterday (that
>>> had
>>> > already been LGTMed by someone else).
>>> >
>>> > Doing that means that *any* api connection can use the thus-unprotected
>>> > facade -- clients, agents, and malicious code running in a compromised
>>> > machine and using the agent credentials. I don't think we have any APIs
>>> > where this is actually a good idea; the best I could say about any
>>> such case
>>> > is that it's not *actively* harmful *right now*. But big exploits are
>>> made
>>> > of little holes, let's make an effort not to open them in the first
>>> place.
>>> >
>>> > Moonstone, please fix the unitassigner facade ASAP; everyone else, be
>>> told,
>>> > and keep an extra eye out for this issue in reviews :).
>>> >
>>> > Cheers
>>> > William
>>> >
>>> > --
>>> > Juju-dev mailing list
>>> > Juju-dev at lists.ubuntu.com
>>> > Modify settings or unsubscribe at:
>>> > https://lists.ubuntu.com/mailman/listinfo/juju-dev
>>> >
>>>
>>
>> --
>> Juju-dev mailing list
>> Juju-dev at lists.ubuntu.com
>> Modify settings or unsubscribe at:
>> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20151203/54d7c9a9/attachment.html>