Changes between Version 1 and Version 2 of GAPI_AM_API_DRAFT/SpeaksFor


Ignore:
Timestamp:
04/30/13 11:44:15 (11 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT/SpeaksFor

    v1 v2  
    33== AM API Change Set P: Support proxy clients that 'Speak For' an experimenter ==
    44
    5 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 they authenticate to AM API calls, and use a new 'Speaks For' credential (or credential set) to authorize the tool to take a given action. The experimenter will issue such credentials to the tool (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.
     5GENI 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.
    66
    77Two 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.
     
    1111  `geni_handles_speaksfor`: A boolean (0 or 1 in XML-RPC), default is false (0).
    1212
    13    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 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.
     13   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.
    1414
    1515 2. Add a new option to the `options` field of each AM API call:
     
    1717  `geni_experimenter_urn`. <string URN>
    1818
    19   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`).
     19  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`).
    2020
    2121Two other additions are required: we must define the 'Speaks For' credential and its semantics, and we must define the URN and certificates for tools.
    2222
    2323The 'Speaks For' credential will be specified elsewhere. Several points are worth noting
    24  - The credential includes the certificates of the tool and the user. For the credential to be accepted, each must be a valid GENI certificate, signed by a GENI root trusted by this aggregate.
     24 - The credential includes the certificates of the tool instance and the user. For the credential to be accepted, each must be a valid GENI certificate, signed by a GENI root trusted by this aggregate.
    2525 - The credential includes an expiration
    2626 - The credential may include scope limitations (including slice, aggregate, operation)
     
    2929=== Tool Certificates ===
    3030
    31 Tools may be issued GENI identity certificates, using the same format and rules as for users.
    32  - The URN will be the URN of the tool. 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:
     31Tool instances may be issued GENI identity certificates, using the same format and rules as for users.
     32 - 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:
    3333  - Tool names are case-insensitive internally, though they may be case-sensitive in display.
    3434   - EG `JohnSmth` as a display name is `johnsmth` internally, and there cannot also be a user `JOHNSMTH`.
    3535  - Tool names should begin with a letter and be alphanumeric or underscores; no hyphen or '.': (`'^[a-zA-Z][\w]\{0,7\}$'`).
    3636  - Tool names are limited to 8 characters.
    37   - Tool URNs (which contain the authority name and the tool name) are required to be temporally and globally unique.
     37  - Tool URNs (which contain the authority name and the tool instance name) are required to be temporally and globally unique.
    3838
    3939'''[FIXME: Must tool names be in the same namespace as user names? That is, do any AMs use the name part of the client URN in some way that cross both tools and users? Can we loosen these restrictions? That is, are some of these only because the user turns into a unix login name or something?]'''
    4040
    41  - The tool email address should be a way to contact the administrators of the tool - the organization or individual who applied for the certificate and who stands behind its integrity.
     41 - 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.
    4242
    4343Note that this functionality also supports proxy aggregates, or aggregates of aggregates. See a previous related change proposal: