RestAuth

Aus Free Software
Zur Navigation springen Zur Suche springen

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/

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