Update doc

README.md

@@ -6,27 +6,29 @@
 [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/zf-fr/zfr-oauth2-server/badges/quality-score.png?s=be36235c9898cfc55044f58d9bba789d2d4d102e)](https://scrutinizer-ci.com/g/zf-fr/zfr-oauth2-server/)
 [![Total Downloads](https://poser.pugx.org/zfr/zfr-oauth2-server/downloads.png)](https://packagist.org/packages/zfr/zfr-oauth2-server)
 
-ZfrOAuth2Server is a PHP library that aims to implement the OAuth 2 specification strictly. Contrary to other
-libraries, it assumes you are using Doctrine, and provide various services based on Doctrine interfaces.
+ZfrOAuth2Server is a PHP library that implement the OAuth 2 specification. It's main goal is to be a clean, PHP 5.4+
+library that aims to be used with Doctrine 2 only.
 
-Currently, it's more of a proof of concept to implement a simpler and cleaner OAuth 2 server implementation. It
-does not support yet the Implicit grant. If you want to help, please contribute!
+Currently, ZfrOAuth2Server does not implement the whole specification (implicit grant is missing), so you are
+encouraged to have a look at the doc if ZfrOAuth2Server can be used in your application.
 
-If you need a full featured project, that was tested by thousands of people, I suggest you to have a look
-at one of those two PHP libraries:
+Here are other OAuth2 library you can use:
 
 - [OAuth2 Server from PHP-League](https://github.com/php-loep/oauth2-server)
 - [OAuth2 Server from Brent Shaffer](https://github.com/bshaffer/oauth2-server-php)
 
 ## Requirements
 
 - PHP 5.4 or higher
+- Doctrine 2
 
 ## To-do
 
-- Better documentation
+- Write documentation
+- Security audit
 - Review of the whole spec
 - Testing the authorization server more extensively
+- Add implicit grant
 
 ## Versioning note
 
@@ -43,20 +45,60 @@ php composer.phar require zfr/zfr-oauth2-server:0.1.*
 
 ## Framework integration
 
-Here are various official integrations with ZfrOAuth2Server:
+Because of its strict dependency injection architecture, ZfrOAuth2Server is hardly usable alone, as it requires
+quite a lot of configuration. However, I've made a Zend Framework 2 module that abstract the whole configuration,
+and make it very easy to use:
 
 * [Zend Framework 2 module](https://github.com/zf-fr/zfr-oauth2-server-module)
 
+If anyone want to help with a Symfony 2 bundle, I'd be glad to help.
+
+
 ## Documentation
 
-ZfrOAuth2Server is based on the [RFC 6749](http://tools.ietf.org/html/rfc6749) for OAuth 2.
+ZfrOAuth2Server is based on the [RFC 6749](http://tools.ietf.org/html/rfc6749) documentation.
+
+### Why using OAuth2?
+
+OAuth2 is an authentication/authorization system that allows that can be used to:
+
+* Implement a stateless authentication mechanism (useful for API)
+* Allow third-party to connect to your application securely
+* Securing your application through the use of scopes
+
+OAuth2 is a dense, extensible specification that can be used for a wide number of use-cases. As of today,
+ZfrOAuth2Server implements three of the four official grants: AuthorizationGrant, ClientCredentialsGrant, PasswordGrant.
+
+### How OAuth2 works?
+
+This documentation does not aim to explain in details how OAuth2 work. Here is [a nice resource](http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified) you can read. However, here is the basic idea of how OAuth2 works:
+
+1. A resource owner (your JavaScript API, your mobile application...) asks for a so-called "access token" to an
+ authorization server. There are several strategies that depends on the use-case. Those strategies are called
+ "grants". For instance, the "password grant" assumes that the resource owner sends its username/password. In all
+ cases, your authorization server responds with an access token (and an optional refresh token).
+2. The client sends this access token to each request that is made to your API. It is used by a "resource server"
+to map this access token to a user in your system.
+
+Choosing the grant type depends on your application. Here are a few hints about which one to choose:
+
+* If you are the only consumer of your API (for instance, your JavaScript application make calls to your API), you
+should use the "password grant". Because you trust your application, it is not a problem to send username/password.
+* If you want a third-party code to connect to your API, and that you are sure that this third-party can keep secrets
+(this means the client is not a JavaScript API, or a mobile application): you can use the client credentials grant.
+* If you want third-party code to connect to your API, and that those third-party applications cannot keep secret
+(think about an unofficial Twitter client that connect to your Twitter account, for instance), you should use the
+authorization grant.
 
 ### Using the authorization server
 
-The authorization server allows you to authorize a request and generate a token. To create an authorization server,
-you need first to create grants. A grant is a flow that allows to create tokens. Each flow has its own use case.
-Currently, ZfrOAuth2 supports the following grants: authorization grant, client credentials grant, password grant
-and refresh token grant:
+The authorization server goal is to accept a request, and generate token. An authorization server can deny a
+request (for instance, if parameters are missing, or if username/password are incorrect).
+
+To use an authorization server, you must first decide which grant you want to support. Some applications should
+only support one type of grant, others may support all of the available grant. This is completely up to you, and
+you should have a solid understanding of all those grants first. For instance, here is how you would create an
+authorization server that support the authorization only:
 
 ```php
 $authTokenService    = new TokenService($objectManager, $authTokenRepository, $scopeRepository);
@@ -70,11 +112,14 @@ $authorizationServer = new AuthorizationServer([$authorizationGrant]);
 $response = $authorizationServer->handleRequest($request);
 ```
 
+The request must be a valid `Zend\Http\Request`, and the authorization server returns a `Zend\Http\Response` object
+that is compliant with the OAuth2 specification.
+
 #### Passing a user
 
-Most of the time, you want to associate an access token to a user. To do this, you can pass an optional second
-parameter to the `handleRequest`. This class must implements the `ZfrOAuth2\Server\Entity\TokenOwnerInterface`
-interface:
+Most of the time, you want to associate an access token to a user. This is the only way to map a token to a user
+of your system. To do this, you can pass an optional second parameter to the `handleRequest`. This class must
+implements the `ZfrOAuth2\Server\Entity\TokenOwnerInterface` interface:
 
 ```php
 $user = new User(); // must implement TokenOwnerInterface
@@ -86,7 +131,7 @@ $response = $authorizationServer->handleRequest($request, $user);
 
 ### Using the resource server
 
-You can use the resource server to retrieve the access token (by automatically extract the data from the HTTP
+You can use the resource server to retrieve the access token (by automatically extracting the data from the HTTP
 headers). You can also use the resource server to validate the access token against scopes:
 
 ```php