Difference between revisions of "RestAuth"

From RestAuth
Jump to navigation Jump to search
(first version)
 
 
(60 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Documentation ==
+
__NOTOC__
 +
The ''RestAuth'' project is a system providing shared authentication, authorization and preferences. Shared authentication and preferences allow users to use a single account on multiple services (such as websites, mail, system accounts, ...), sharing preferences among those systems. Shared authorization allows administrators to manage permissions for users in a central and easy way.
  
=== Terminology ===
+
RestAuth is a free and open project, so please feel free to [[Participate|participate]].
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 (2) to '''Service'''.
 
  
=== Create a ServiceUser ===
+
=== The RestAuth protocol ===
In order to create a ServiceUser, perform an HTTP request to:
+
At the core of the project is a [[Specification|detailed specification]] ([[Specification overview|simplified overview]], [[RestAuth with curl|examples with curl]]) for a network protocol loosely based on the [[wikipedia:Representational_State_Transfer|REST paradigm]]. The primary design goal of the RestAuth protocol is to make it as easy as in any way possible to integrate existing services into the RestAuth system. If you need to use the protocol directly (i.e. because you are using a language where no library exists), the basic authentication service consists of just a few HTTP calls, you don't even need to use a JSON parser. Even more complex tasks require little more than a HTTP protocol implementation and a JSON parser. Our libraries make RestAuth even simpler to use, you need no knowledge of the protocol, you won't even notice that you are performing calls via the network.
POST /users/
 
  
The POST data MUST contain two values:
+
=== Servers ===
; username : The name of the user to create
+
The project provides a [https://server.restauth.net reference implementation] based on the [https://www.djangoproject.com Django web framework].
; password : The password for this user
 
  
This method returns the following status codes:
+
=== Client libraries ===
; 201 Created : If the creation of the user succeeded
+
The RestAuth project provides libraries for several popular programming languages: [https://python.restauth.net Python] (the client reference implementation), [https://php.restauth.net PHP], incomplete libraries are available for [https://github.com/RestAuth/java], [https://github.com/RestAuth/perl Perl] and [https://github.com/RestAuth/ruby Ruby]. Please see the [[Libraries|Libraries page]] for a full list of available libraries.
; 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:
+
=== Plugins ===
curl -X POST -w "%{http_code}\n" -d "username=myuser&password=mypassword" http://user:pass@localhost:8000/users/
+
There are ready-to-use plugins for many systems. The [[Plugins|Plugins page]] provides a full list.
  
=== Update a ServiceUser ===
+
=== Development ===
To update the credentials of a ServiceUser, perform an HTTP request to:
+
* [[Wish-list]]
PUT /users/<username>
+
* [[Username considerations]]
where "<username>" is the name of the user to update.
+
* [[Usernames]]
 
 
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
 

Latest revision as of 21:44, 8 September 2014

The RestAuth project is a system providing shared authentication, authorization and preferences. Shared authentication and preferences allow users to use a single account on multiple services (such as websites, mail, system accounts, ...), sharing preferences among those systems. Shared authorization allows administrators to manage permissions for users in a central and easy way.

RestAuth is a free and open project, so please feel free to participate.

The RestAuth protocol

At the core of the project is a detailed specification (simplified overview, examples with curl) for a network protocol loosely based on the REST paradigm. The primary design goal of the RestAuth protocol is to make it as easy as in any way possible to integrate existing services into the RestAuth system. If you need to use the protocol directly (i.e. because you are using a language where no library exists), the basic authentication service consists of just a few HTTP calls, you don't even need to use a JSON parser. Even more complex tasks require little more than a HTTP protocol implementation and a JSON parser. Our libraries make RestAuth even simpler to use, you need no knowledge of the protocol, you won't even notice that you are performing calls via the network.

Servers

The project provides a reference implementation based on the Django web framework.

Client libraries

The RestAuth project provides libraries for several popular programming languages: Python (the client reference implementation), PHP, incomplete libraries are available for [1], Perl and Ruby. Please see the Libraries page for a full list of available libraries.

Plugins

There are ready-to-use plugins for many systems. The Plugins page provides a full list.

Development