= Speaks For AM API Changes = == AM API Change Set P: Support proxy clients that 'Speak For' an experimenter == GENI tools invoke AM API methods on behalf of experimenters. When that tool instance is well known and trusted by the experimenter, and runs local to a single experimenter, then it is reasonable for that tool to be given the experimenter's private key and public certificate, and 'speak as' the experimenter. But for a hosted tool that might act for multiple experimenters it is both more secure and more clear what is happening for such tools to have their own identity certificate and private key by which each tool instance authenticates to AM API calls, and use a new 'Speaks For' credential (or credential set) to authorize the tool instance to take a given action. The experimenter will issue such credentials to the tool instance (possibly scoped by time, slice, aggregate, or other dimension), and the aggregate can then properly assign the resources to the experimenter, while logging and reporting that the tool performed the operation. This functionality can also be used for an experimenter to authorize a 'proxy' aggregate or an aggregate of aggregates. Two changes are required in the AM API to support this functionality. First, not all aggregates will support 'Speaks For' yet, so tools must be able to distinguish. Second, we require an explicit way for the aggregate to determine on whose behalf a tool is taking this action. 1. Add a new optional return entry from `GetVersion`: `geni_handles_speaksfor`: A boolean (0 or 1 in XML-RPC), default is false (0). When present and true, the aggregate is capable of authorizing AM API actions using a GENI 'Speaks For' credential (or credential set), and accepting the option `geni_experimenter_urn` (see below). When the aggregate supports 'Speaks For', tools should authenticate using their own GENI issued certificate and key, supply a 'Speaks For' credential (or credential set) from the experimenter authorizing the tool instance to perform the given action, and supply the URN of the experimenter on whose behalf the tool is acting in the `geni_experimenter_urn` option. When the aggregate does not support 'Speaks For', the tool is expected to 'speak as' the experimenter, using the experimenter's own GENI issued certificate and key. Aggregates should however attempt to support 'Speaks For', as 'Speaks As' is undesirable deprecated behavior. If a client supplies 'Speaks For' arguments to an aggregate that does not advertise support for 'Speaks For', the aggregate will typically ignore these, and attempt to authorize the client directly (though that behavior is not required), likely resulting in an authorization failure. 2. Add a new option to the `options` field of each AM API call: `geni_experimenter_urn`. When supplied, this is the URN of the experimenter on whose behalf the client is acting. The aggregate should expect to find a 'Speaks For' credential or credential set in the `credentials` argument, by which the given experimenter authorizes the client (as authenticated by the SSL client certificate) to perform the given action on their behalf. If such a credential is not found, the aggregate should fail the request with an authorization error (e.g. error code `3`: `FORBIDDEN`). When omitted, the aggregate need not look for a 'Speaks For' credential, but should look to authorize the client itself ('speaks as'). If the client is not itself directly authorized to perform the given action, the aggregate should fail the request with an authorization error (e.g. error code `3`: `FORBIDDEN`). Two other additions are required: we must define the 'Speaks For' credential and its semantics, and we must define the URN and certificates for tools. The 'Speaks For' credential will be specified elsewhere. Several points are worth noting - The credential includes the certificates of the tool instance and the user. For the credential to be accepted, each certificate must itself be trusted by the aggregate; current recommended GENI policy requires [GeniApiCertificates a particular format] for that certificate, and requires that it be signed by a trusted GENI root . - The credential includes an expiration - The credential may include scope limitations (including slice, aggregate, operation) - When the aggregate authorizes a 'Speaks For' operation, the aggregate must treat the operation as though performed by the experimenter, but also log that it was done via the given tool. That is, resources will be owned by the experimenter, and logs and monitoring reports will include both the experimenter URN and the tool URN. === Tool Certificates === Tool instances may be issued GENI identity certificates, using the same format and rules as for users. - The URN will be the URN of the tool instance. With this change, we introduce a new 'type' for the URN field: `tool`. The name of a tool is subject to the same restrictions as the name for users: - Tool names are case-insensitive internally, though they may be case-sensitive in display. - EG `JohnSmth` as a display name is `johnsmth` internally, and there cannot also be a user `JOHNSMTH`. - Tool names should begin with a letter and be alphanumeric or underscore, hyphen, at sign or period: (`'^[a-zA-Z][a-ZA-Z0-9\-_@\.]{0,31}$'`). - Tool names are limited to 64 characters. - Tool URNs (which contain the authority name and the tool instance name) are required to be temporally and globally unique. '''[FIXME: 32 characters? 64? Right character restrictions?]''' - The tool email address should be a way to contact the administrators of the tool instance - the organization or individual who applied for the certificate and who stands behind its integrity. Note that this functionality also supports proxy aggregates, or aggregates of aggregates. See a previous related change proposal: http://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT?version=47#ChangeSetJ:Proxyaggregatemanagersaresupported