RestAuth

Aus Free Software
Zur Navigation springen Zur Suche springen

Documentation

Terminology

Essentially, when dealing with shared authentication, you have to deal with two types of accounts:

  1. Users that want to authenticate themselves against some service
  2. 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

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/