#23 explained main goal of the library in details

README.md

@@ -16,26 +16,51 @@
   - [Contact](#contact)
   - [License](#license)
 
-Play! (v2.5) library to protect REST endpoint using OAuth2 token verification. In order to access a protected endpoint clients should pass an `Authorization` header with the `Bearer` token in every request.
-This library is implemented in a non-blocking way and provides two implementations of token verification.
+Play! (v2.5) library to protect RESTful resource servers using OAuth2. According to [RFC 6749](https://tools.ietf.org/html/rfc6749#section-7):
 
-- `AlwaysPassAuthProvider` implementation is useful for Development environment to bypass a security mechanism. This implementation assumes that every token is valid.
-- `OAuth2AuthProvider` implementation acquires token information from a 3rd-party endpoint and then verifies this info. Also it applies a [Circuit Breaker](http://doc.akka.io/docs/akka/snapshot/common/circuitbreaker.html) pattern.
+> The client accesses protected resources by presenting the _access
+  token_ to the _resource server_. The resource server MUST _validate_ the
+  access token and ensure that it has not expired and that its scope
+  covers the requested resource. _The methods_ used by the resource
+  server _to validate the access token_ (as well as any error responses)
+  _are beyond the scope_ of this specification but generally involve an
+  interaction or coordination between the resource server and the
+  authorization server.
 
-Clients of this library don't need to change their code in order to protect endpoints. All necessary security configurations happen in a separate configuration file. The main difference between this library and similar libraries is that as a user of this library you don't need to change your code or somehow couple it any custom annotations or "actions". This library also provides you kind of a safety net because the access to all endpoints regardless of whether they are existing or planned is denied by default.
+However, the specification [does not define](https://tools.ietf.org/html/rfc6749#section-1.1) the interaction between the authorization server and resource server:
+
+> The interaction between the authorization server and resource server
+  is _beyond the scope_ of this specification.  The authorization server
+  _may be the same server_ as the resource server _or a separate entity_.
+
+The library assumes an existence of external server which implements [API](http://planb.readthedocs.io/en/latest/intro.html#token-info) of [Plan B Token Info service](https://github.com/zalando/planb-tokeninfo) and which is responsible for the validation of access tokens. The Plan B Token Info service API is not compatible with [OAuth 2.0 Token Introspection](https://tools.ietf.org/html/rfc7662), so the library does not cover an interaction with authorization servers which might implement token introspection. However, support of token introspection can be easily added by providing an implementation of `org.zalando.zhewbacca.AuthProvider` interface.
+
+**Note: the library does not validate access tokens on its own**.
+
+After successful validation of access token it evaluates access rules defined to access protected resources. For example, it can compare scopes required to access protected resource with scopes associated with the token. So the main goal of this library is to reduces amount of infrastructure code needed to implement proper interaction between resource server and authorization server (in this case [Plan B Token Info service](https://github.com/zalando/planb-tokeninfo)) and evaluation of access rules.
+
+Currently the library supports only `Bearer` access token type. In order to access a protected endpoint clients should pass an `Authorization` header with the `Bearer` token in every request. More details you can find in the [RFC 6749](https://tools.ietf.org/html/rfc6749#section-7.1).
+
+Developers who want to use this library don't need to change their code in order to protect endpoints. All necessary security configurations happen in a separate configuration file. The main difference between this library and similar libraries is that as a user of this library you don't need to couple it with any custom annotations or "actions". This library also provides you kind of a safety net because the access to all endpoints is denied by default regardless of whether they are existing or planned.
 
 The library is used in production in several projects, so you may consider it as reliable and stable.
 
 ## Core Technical Concepts
+- Non-blocking from top to bottom.
 - Non-intrusive approach for the integration with existing play applications. You don't need to change your code.
 - Declarative security configuration via configuration file.
 - Minimalistic. The library does only one thing, but does it good.
 - Developers friendly. Just plug it in and you are done.
-- Non-blocking from top to bottom.
+- Easy to use in tests with `AlwaysPassAuthProvider` provider.
 - Opinionated design choice: the library relies on `Play`'s toolbox like `WS`-client from the beginning because it is designed to work _exclusively_ within Play-applications.
 
 We mainly decided to release this library because we saw the needs of OAuth2 protection in almost every microservice we built and because we are not happy to couple our code with any forms of custom security actions or annotations.
 
+## Known alternatives
+- [Hutmann](https://github.com/zalando-incubator/hutmann)
+- [Deadbolt 2](https://github.com/schaloner/deadbolt-2/)
+- [SecureSocial](https://github.com/jaliss/securesocial/)
+
 ## Getting Started
 
 Configure libraries dependencies in your `build.sbt`:
@@ -110,7 +135,7 @@ Example of configuration in `application.conf` file:
 
 ```
 # Full URL for authorization endpoint
-authorisation.iam.endpoint = "https://info.services.auth.zalando.com/oauth2/tokeninfo"
+authorisation.iam.endpoint = "https://info.services.auth.example.com/oauth2/tokeninfo"
 
 # Maximum number of failures before opening the circuit
 authorisation.iam.cb.maxFailures = 4

src/main/scala/org/zalando/zhewbacca/AlwaysPassAuthProvider.scala

@@ -2,6 +2,10 @@ package org.zalando.zhewbacca
 
 import scala.concurrent.Future
 
+/**
+  * This implementation is useful for Development environment to bypass a security mechanism.
+  * It assumes that every token is valid.
+  */
 class AlwaysPassAuthProvider(tokenInfo: TokenInfo) extends AuthProvider {
   override def valid(token: Option[OAuth2Token], scope: Scope): Future[AuthResult] =
     Future.successful(AuthTokenValid(tokenInfo))