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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> >> 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 <[email protected]> >>> 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 >>> > [email protected] >>> > Modify settings or unsubscribe at: >>> > https://lists.ubuntu.com/mailman/listinfo/juju-dev >>> > >>> >> >> -- >> Juju-dev mailing list >> [email protected] >> Modify settings or unsubscribe at: >> https://lists.ubuntu.com/mailman/listinfo/juju-dev >> >
-- Juju-dev mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
