RestAuth: Unterschied zwischen den Versionen

Aus Free Software
Zur Navigation springen Zur Suche springen
(Replaced content with 'RestAuth attempts to provide a shared authentication service using the [http://en.wikipedia.org/wiki/Representational_State_Transfer REST paradigm]. Therefore simple HTTP req…')
Zeile 1: Zeile 1:
 
RestAuth attempts to provide a shared authentication service using the [http://en.wikipedia.org/wiki/Representational_State_Transfer REST paradigm]. Therefore simple HTTP requests can be used to perform the basic [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete CRUD operations] on the users known to RestAuth.
 
RestAuth attempts to provide a shared authentication service using the [http://en.wikipedia.org/wiki/Representational_State_Transfer REST paradigm]. Therefore simple HTTP requests can be used to perform the basic [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete CRUD operations] on the users known to RestAuth.
  
== Documentation ==
 
When dealing with shared authentication, the term "user" can mean two different things:
 
# Users that want to authenticate themselves against some service (i.e. you)
 
# The service that wants to use the shared authentication (i.e. this wiki)
 
In the following documentation, we refer to (1) as '''ServiceUser''' and to (2) as '''Service'''.
 
  
In order to increase security and limit abuse, services also have to authenticate against RestAuth. In the spirit of simplicity, this authentication is done with [http://en.wikipedia.org/wiki/Basic_access_authentication HTTP Basic authentication]. The RestAuth administrator therefore has to make sure that requests are only possible via HTTPS.
+
=== Interface documentation ===
 
+
The Interface is documented in detail at [[/Interface documentation]].
=== Create a ServiceUser ===
 
In order to create a ServiceUser, perform an HTTP POST request to:
 
/users/
 
 
 
The POST data MUST contain two values:
 
; username : The name of the user to create
 
; password : The password for this user
 
 
 
This method returns the following status codes:
 
; 201 Created : If the creation of the user succeeded
 
; 400 Bad Request : If either the POST data did not contain a username ''and'' password or if either username or password is not acceptable to the system.
 
; 405 Method Not Allowed : If the request to /users/ was not a POST request
 
; 409 Conflict : If the user already exists
 
; 500 Internal Server Error : If any other problem occurs
 
 
 
To create a user with curl, do:
 
curl -X POST -w "%{http_code}\n" -d "username=myuser&password=mypassword" <nowiki>http://user:pass@localhost/users/</nowiki>
 
 
 
=== Verify that a ServiceUser exists ===
 
Some services want to know if a user exists, to check this, perform an HTTP GET request to:
 
/users/<username>
 
 
 
This method returns the following status codes:
 
; 201 OK : If the user exists
 
; 404 NOT FOUND : If the user does not exist
 
; 500 Internal Server Error : If any other problem occurs
 
 
 
=== Verify a ServiceUser's password ===
 
To verify the password of a ServiceUser, perform an HTTP POST request to:
 
/users/<username>
 
 
 
The POST data MUST contain only one value, the password to check.
 
 
 
This method returns the following status codes:
 
; 200 OK : If the given password is the right one for the given user
 
; 400 Bad Request : If the POST data could not be parsed.
 
; 404 Not Found : If the user is not found ''or'' if the password does ''not'' match.
 
; 500 Internal Server Error : If any other problem occurs
 
 
 
To verify a password for a user, do:
 
curl -X POST -w "%{http_code}\n" -d "password=mynewpassword" <nowiki>http://user:pass@localhost/users/myuser/</nowiki>
 
 
 
===== Why is this POST and not GET? =====
 
Following the REST paradigm, this really should be a GET request, not a POST request. GET requests have one ''major'' disadvantage, though: GET parameters are usually logged in the log-files of your webserver. This would mean that a password verification request to ''users/<username>?password=<password>'' would be logged. There are ways around logging this, but in our opinion services should ''always'' be "secure by default".
 
 
 
=== Update a ServiceUser ===
 
To update the credentials of a ServiceUser, perform an HTTP PUT request to:
 
/users/<username>
 
where "<username>" is the name of the user to update.
 
 
 
The request data is interpreted the same way as with a POST request. It must contain either username and/or password. The service may not allow to update the username itself (see status codes below).
 
 
 
This method returns the following status codes:
 
; 200 OK : If the credentials where successfully updated
 
; 400 Bad Request : If the request data could not be parsed or if the new username/password is not acceptable to the system.
 
; 403 Forbidden : If the Service attempts to change the username and the RestAuth instance does not allow such a change.
 
; 404 Not Found : If the username does not exist
 
 
 
To update a user with curl, do:
 
curl -X PUT -w "%{http_code}\n" -d "password=mynewpassword" <nowiki>http://user:pass@localhost:8000/users/myuser/</nowiki>
 
 
 
=== Delete a ServiceUser ===
 
To delete a ServiceUser, perform an HTTP DELETE request to:
 
/users/<username>
 
 
 
This method returns the following status codes:
 
; 200 OK : If the user really was deleted
 
; 404 Not Found : If the user was not found
 
; 500 Internal Server Error : If any other problem occurs
 
 
 
To delete a user with curl, do:
 
<nowiki>curl -X DELETE http://user:pass@localhost/users/myuser/</nowiki>
 

Version vom 6. August 2010, 17:17 Uhr

RestAuth attempts to provide a shared authentication service using the REST paradigm. Therefore simple HTTP requests can be used to perform the basic CRUD operations on the users known to RestAuth.


Interface documentation

The Interface is documented in detail at /Interface documentation.