Changes between Version 6 and Version 7 of NewTestbedAPISpec

Timestamp:

Jul 16, 2013 9:56:05 AM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -29 +29 @@
    * request - bad request
    * internal - internal server error
+   * password - user has an expired password that must be changed
  * ErrorString - a string describing the broad error
  * DetailString - a string describing the details that caused the error
@@ -72 +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.
 
-Currently only one challenge type is defined.  The challenge is an array of bytes and the response is return an SHA1 HMAC of that string keyed by the user's password.
+Currently 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.
 
  * '''Service:''' Users
@@ -78 +79 @@
  * '''Input Parameters:'''
    * userid - the identity to authenticate
+   * types - a list of challenges that are acceptable to the user.  May be empty
  * '''Return Values:'''
    * Type - the kind of challenge
@@ -84 +86 @@
    * ChallengeID - a 64-bit identifier that allows the server to validate the reply
 
+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.
+
  * '''Service:''' Users
  * '''Operation:''' challengeResponse
@@ -91 +95 @@
  * '''Return Values''':
   * Certificate - a binary string containing a PEM-encoded X.509 certificate and private key. (Passed down the encrypted connection)
+
+The certificate returned by the challenge is signed by the testbed.
+
+=== Password Changes ===
+
+The password is a unique user feature that is not in the profile because of its role in authentication.  When a user needs to change their password there are two API calls that can be used.
+
+If the user knows their current (or expired) password, they can authenticate using the standard challenge response protocol and then call
+
+* '''Service:''' Users
+ * '''Operation:''' changePassword
+ * '''Input Parameters:'''
+  * uid - the userid to change (note that an admin may change others passwords)
+  * newPass - the new passowrd
+ * '''Return Values''':
+  * a boolean, true if successful, but most errors will throw a fault
+
+We 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.
+
+If a user has forgotten their password, the user can request a password challenge, sent to them at their profile e-mail address.  The challenge is a 64-bit number that can be used to call changePasswordChallenge without logging in.  To request a challenge, the web interface calls:
+
+* '''Service:''' Users
+ * '''Operation:''' requestPasswordReset
+ * '''Input Parameters:'''
+  * uid - the userid to change
+  * urlPrefix - a string prefixed to the challenge ID in the mail sent to the user
+ * '''Return Values''':
+  * a boolean, true if successful, but most errors will throw a fault
+
+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.
+
+Each challenge is valid for 2 hours, and they are rate limited so only a few can be outstanding.
+
+With a valid challenge in hand, the web interface can call
+
+* '''Service:''' Users
+ * '''Operation:''' changePasswordChallenge
+ * '''Input Parameters:'''
+  * challengeID - the 64-bit number from the e-mail
+  * newPass - the new passowrd
+ * '''Return Values''':
+  * a boolean, true if successful, but most errors will throw a fault
+
 
 === Profile Manipulation ===
@@ -137 +184 @@
 
  * '''Service:''' Users
- * '''Operation:''' getProfileDescription
+ * '''Operation:''' getUserProfile
  * '''Input Parameters:'''
   * userid - a string naming the user to be retrieved
@@ -162 +209 @@
  
  * '''Service:''' Users
- * '''Operation:''' getProfileDescription
+ * '''Operation:''' changeUserProfile
  * '''Input Parameters:'''
    * Userid - the user's profile to modify