RestAuth: Unterschied zwischen den Versionen

Aus Free Software
Zur Navigation springen Zur Suche springen
K (→‎Terminology: grammar)
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.
 +
 
== Documentation ==
 
== 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'''.
  
=== Terminology ===
+
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.
Essentially, when dealing with shared authentication, you have to deal with ''two'' types of accounts:
 
# Users that want to authenticate themselves against some service
 
# The service that wants to use the shared authentication
 
In the following documentation, we refer to (1) as '''ServiceUser''' and to (2) as '''Service'''.
 
  
 
=== Create a ServiceUser ===
 
=== Create a ServiceUser ===

Version vom 3. August 2010, 00:52 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.

Documentation

When dealing with shared authentication, the term "user" can mean two different things:

  1. Users that want to authenticate themselves against some service (i.e. you)
  2. 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 Basic authentication. The RestAuth administrator therefore has to make sure that requests are only possible via HTTPS.

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" http://user:pass@localhost/users/

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" http://user:pass@localhost:8000/users/myuser/

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" http://user:pass@localhost/users/myuser/

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:

curl -X DELETE http://user:pass@localhost/users/myuser/