update docs for authorization

docs/Authorization.rst

@@ -2,14 +2,44 @@
 Authorization and Authentication
 *********************************
 
-h5serv supports HTTP Basic authentication to authenticate users be comparing an encrypted 
+Request Authentication
+-----------------------
+h5serv supports HTTP Basic authentication to authenticate users by comparing an encrypted 
 username and password against a value stored within a password file.  
 (See :doc: `AdminTools` to create a password file and add user accounts.) 
 
 If neither the requested object (Group, Dataset, or Committed Datatype) nor the object's root group
 has an Access Control List (ACL), authorization is not required and no authentication string
 needs to be suplied. 
 
-If the requested object (or object's root group), does have an ACL, authorization may be required,
-and the requestor may need to provide an Authorization header in the request.
+If the requested object (or object's root group), does have an ACL, authorization may be required 
+(if the object is not publically readable),
+and if so the requestor will need to provide an Authorization header in the request.  If 
+authoriazation is required, but not provided, the server will return an HTTP Status of 401 - 
+Unauthorized.
+
+If authorization is required (i.e. a 401 response), the client should provide an authorization header in the
+http request which conveys the userid and password.
+
+The authorization string is constructed as follows:
+
+# Username and password are combined into a string "username:password". Note that username cannot contain the ":" character.
+# The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
+# The authorization method and a space i.e. "Basic " is then put before the encoded string.
+
+For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the field is formed as follows:
+Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+
+If the authorization string is validated, the server will verify the request is authorized as
+per the object's ACL list.  If not authorized a http status 403 - Forbidden will be returned.
+See :doc:`AclOps`) for information on how to use ACL's.
+
+User ids and passwords
+----------------------
+
+User ids and passwords are maintained in an HDF5 file referenced in the server config: 
+'password_file'.  The admin tool (See :doc:`AdminTools`): update_pwd.py can be used 
+to create new users and update passwords.
+
+
 

docs/CommonErrorResponses.rst

@@ -11,6 +11,8 @@ information on the nature of the error.
  * ``200 OK`` - The request was completed successfully
  * ``201 Created`` - The request was fulfilled and a new resource (e.g. group, dataset, attribute was created) 
  * ``400 Bad Request`` - The request was not structured correctly (e.g. a required key was missing).
+ * ``401 Unauthorization`` - Use authentitcation is required, supply an Authentication header with valid user and password
+ * ``403 Forbidden`` - The requesting user does not have access to the requested resource
  * ``404 Not Found`` - The requested resource was not found (e.g. ``GET /groups/<id>`` where <id> was not a valid identifier for a group in the domain).
  * ``409 Conflict`` - This error is used with PUT requests where the resources cannot be created because there is an existing resource with the same name (e.g. PUT / where the requested domain is already present).
  * ``410 Gone`` - The resource requested has been recently deleted.