Changes between Version 20 and Version 21 of NewTestbedAPISpec


Ignore:
Timestamp:
Sep 11, 2013 10:41:40 AM (11 years ago)
Author:
faber
Comment:

Users API updates

Legend:

Unmodified
Added
Removed
Modified

  • NewTestbedAPISpec

    v20 v21  
    7171=== Authentication ===
    7272
    73 A user can authenticate to the testbed and receive a short-lived client x.509 certificate by requesting a challenge using the {{{requestChallenge}}} operation and responding to the challenge via the {{{challengeResponse}}} operation.
     73A user's identity is tied to an X.509 client certifcate issued by DETER.  A certificate is bound to one user at a time, but a person can logout and log in as a different DETER user using the same certificate by presenting a different password, or logging out, which severs the connection of user to certificate.
     74
     75A user can get a DETER-signed certificate by logging in without presenting an existing DETER-signed certificate.  For example, the first time a user logs in, they will get a DETER-signed certificate.
     76
     77A UI is welcome to keep one certificate for a session, or to reuse the certificates until they expire.  The certificates are issued with several years of valid time.
     78
     79A user can authenticate to the testbed and receive an X.509 certificate by requesting a challenge using the {{{requestChallenge}}} operation and responding to the challenge via the {{{challengeResponse}}} operation.
    7480
    7581Currently only one challenge is available, type "clear".  The challenge has no data and the user replies with their password in clear text.  Note that the exchange is protected by the SSL encrypted exchange, but implementors should not respond to clear challenges with parameters in the query string.  The "masked" challenge will address this issue shortly.
    … …  
    8692   * ChallengeID - a 64-bit identifier that allows the server to validate the reply
    8793
    88 Each challenge is valid for 2 minutes and are rate limited.  Web interfaces should collect the password from the user before requesting a challenge from the API to avoid spurious timeouts.
     94Each challenge is valid for 2 minutes and are rate-limited.  Web interfaces should collect the password from the user before requesting a challenge from the API to avoid spurious timeouts.
    8995
    9096 * '''Service:''' Users
    … …  
    94100  * ChallengeID - The 64-bit identifier of the challenge being responded to
    95101 * '''Return Values''':
    96   * Certificate - a binary string containing a PEM-encoded X.509 certificate and private key. (Passed down the encrypted connection)
    97 
    98 The certificate returned by the challenge is signed by the testbed.
     102  * Certificate - an optional  binary string containing a PEM-encoded X.509 certificate and private key. (Passed down the encrypted connection)  If the user presented a certificate on this connection, no credential is returned.
     103
     104Any certificate returned by the challenge is signed by the testbed.
     105
     106The binding between user and certificate lasts 24 hours.  It can be renewed by making another login exchange.  A UI may want to prompt a user to login again before the binding times out.
     107
     108 * '''Service:''' Users
     109 * '''Operation:''' logout
     110 * '''Input Parameters:'''
     111  * None
     112 * '''Return Values:'''
     113  * None
     114
     115Removes the user-to-certificate binding for this certificate.  The certificate can be reused or discarded, but cannot be used to manipulate the testbed without another successful requestChallenge/challengeResponse exchange.
     116
    99117
    100118=== Password Changes ===
    … …  
    110128  * newPass - the new passowrd
    111129 * '''Return Values''':
    112   * a boolean, true if successful, but most errors will throw a fault
     130  * a boolean, true if successful, but errors will throw a fault
    113131
    114132We expect that the web interface will handle issues like confirming user input to a password change page.  The changePassword call just makes the change directly.
    … …  
    124142  * a boolean, true if successful, but most errors will throw a fault
    125143
    126 Again, we expect this call to generally be made from a web interface that will then want to present an input form to the in order to reset their password.  The urlPrefix field provides that hook.  A web interface running on !https://niftydeter.com might call requestPasswordReset with parameters 'forgetfuluser' and '!https://niftydeter.com/reset.html?challenge='.  After that call forgetfuluser will get e-mail asking him or her to access the web page at !https://niftydeter.com/reset.html?challenge=1283548127541824, allowing {{{niftydeter.com}}} to present their password change interface, and do error checking, ete. on the new password.
    127 
    128 Each challenge is valid for 2 hours, and they are rate limited so only a few can be outstanding.
     144Again, we expect this call to generally be made from a web interface that will then want to present an input form to the in order to reset their password.  The urlPrefix field provides that hook.  A web interface running on !https://niftydeter.com might call requestPasswordReset with parameters 'forgetfuluser' and '!https://niftydeter.com/reset.html?challenge='.  After that call forgetfuluser will get e-mail asking him or her to access the web page at !https://niftydeter.com/reset.html?challenge=1283548127541824, allowing {{{niftydeter.com}}} to present their password change interface, and do error checking, etc. on the new password.
     145
     146Each challenge is valid for 2 hours, and they are rate-limited so only a few can be outstanding.
    129147
    130148With a valid challenge in hand, the web interface can call
    … …  
    154172 * a flag set if the element is optional
    155173 * A flag set if the field can be removed from the profile
    156  * a modification type: elements may be read/write, read-only (e.g., username) or write-only (e.g., password)
     174 * a modification type: elements may be read/write, read-only (e.g., username) or write-only (e.g., some shared secret) (valid strings are at [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html the constants documentation.]
    157175 * a brief description of the field, intended to be presented by a web interface or other third party program
    158176 * an ordering hint for web interfaces presenting the data to users, an integer
    … …  
    174192       * binary/opaque
    175193     * Value - a string containing the element's value
    176      * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
    177        * READ_WRITE
    178        * READ_ONLY
    179        * WRITE_ONLY (e.g., password)
     194     * Access - a string describing the access values (values at [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html javadoc as described above])
    180195     * Optional - a flag true if the field is optional (must be present but may be empty)
    181196     * Removable - a flag true if the field can be removed
    … …  
    202217       * binary/opaque
    203218     * Value - a string containing the element's value
    204      * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
    205        * READ_WRITE
    206        * READ_ONLY
    207        * WRITE_ONLY (e.g., password)
     219     * Access - a string describing the access values (values at [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html javadoc as described above])
    208220     * Optional - a flag true if the field is optional (must be present but may be empty)
    209221     * Removable - a flag true if the field can be removed
    … …  
    236248Each notification has a set of flags that define its state.  Currently there are 2
    237249
    238  * '''READ''' bit 0 (low order bit) true if the user has read the notification
    239  * '''URGENT''' bit 1 true if the testbed considers this urgent information
    240 
    241 The user is free to change this state using the markNotifications call.  Note that notifications are per-user.  A user who clears the READ or URGENT bit does not clear the bit for other recipients of the notification.
     250 * '''READ''' true if the user has read the notification
     251 * '''URGENT'''true if the testbed considers this urgent information
     252
     253The user is free to change this state using the markNotifications call.  Note that notifications are per-user.  A user who clears the READ or URGENT flag does not clear the flag for other recipients of the notification.
    242254
    243255 
    … …  
    248260   * FirstDate - an optional date.  If present only show notifications after that date
    249261   * LastDate - an optional date.  If present only show notifications before that date
    250    * Flags - a 32-bit integer of flags. Only notifications that match the flags state after the mask is applied are returned
    251    * Mask - A 32-bit mask of the bits to consider in the flags field.
     262   * Flags - A potentially empty list of flags to check.  If a flag's name appears in this list, only notifications with their flag in the given state are returned.
     263     * Tag - a string, the name of the flag
     264     * isSet - a boolean, true if the flag should be set
    252265 * '''Return Values:'''
    253266   * A list of responses each containing
    254267     * ID - a 64-bit integer identifying the notification
    255      * Flags - the message state
     268     * Flags - the notification state in the format
     269       * Tag - a string, the name of the flag
     270       * isSet - a boolean, true if notifications with the flag set should be returned, false if notifications with the flag unset should be returned
    256271     * Sent - the date the notification was issued
    257272     * Text - the text of the notification
    … …  
    269284   * Userid - the user's identity to gather notifications
    270285   * Ids - an array of 64-bit integers, the identifiers of the notifications to mark
    271    * Flags - a 32-bit integer of flags to change. Notifications will have their flags field set to the value in this field if the corresponding mask bit is set.
    272    * Mask - A 32-bit mask of the bits to consider in the flags field.
     286   * Flags - A list of flags to modify.  If a flag's name appears in this list, notifications will have their flag set to the given value.
     287     * Tag - a string, the name of the flag
     288     * isSet - a boolean, true if the flag should be set, false if it should be unset
    273289 * '''Return Values:'''
    274290   * None
    … …  
    281297   * Users - a list of uids to receive the notification
    282298   * Projects - a list of projects to receive the notification.  All users in the project will receive it
    283    * Flags - the initial notification state for each user
     299   * Flags - A list of initial flag values.  If a flag's name appears in this list, notifications will have their flag set to the given value.  Flags that do not appear will be unset.
     300     * Tag - a string, the name of the flag
     301     * isSet - a boolean, true if the flag should be set, false if it should be unset
    284302   * Text - the content of the notification
    285303 * '''Return Values:'''
    … …  
    346364   * Type - the type (STRING, INT, FLOAT, OPAQUE)
    347365   * Optional - a boolean, true if this attribute is optional
    348    * Access - an integer the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
     366   * Access - a string: the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
    349367   * Description - natural language description of the field (optional)
    350368   * Format - a regular expression describing the format (optional)
    … …  
    373391   * Type - the type (STRING, INT, FLOAT, OPAQUE)
    374392   * Optional - a boolean, true if this attribute is optional
    375    * Access - an integer the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
     393   * Access - a string: the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
    376394   * Description - natural language description of the field (optional)
    377395   * Format - a regular expression describing the format (optional)