Update to vertx-ext-parent 25

pom.xml

@@ -36,7 +36,7 @@
   <parent>
     <groupId>io.vertx</groupId>
     <artifactId>vertx-ext-parent</artifactId>
-    <version>24</version>
+    <version>25</version>
   </parent>
 
   <artifactId>vertx-auth</artifactId>

vertx-auth-common/src/main/asciidoc/groovy/index.adoc

@@ -14,15 +14,15 @@ To use this project, add the following dependency to the _dependencies_ section
 <dependency>
   <groupId>io.vertx</groupId>
   <artifactId>vertx-auth-common</artifactId>
-  <version>3.4.0.Beta1</version>
+  <version>3.4.0-SNAPSHOT</version>
 </dependency>
 ----
 
 * Gradle (in your `build.gradle` file):
 
 [source,groovy,subs="+attributes"]
 ----
-compile 'io.vertx:vertx-auth-common:3.4.0.Beta1'
+compile 'io.vertx:vertx-auth-common:3.4.0-SNAPSHOT'
 ----
 
 == Basic concepts

vertx-auth-common/src/main/asciidoc/java/index.adoc

@@ -14,15 +14,15 @@ To use this project, add the following dependency to the _dependencies_ section
 <dependency>
   <groupId>io.vertx</groupId>
   <artifactId>vertx-auth-common</artifactId>
-  <version>3.4.0.Beta1</version>
+  <version>3.4.0-SNAPSHOT</version>
 </dependency>
 ----
 
 * Gradle (in your `build.gradle` file):
 
 [source,groovy,subs="+attributes"]
 ----
-compile 'io.vertx:vertx-auth-common:3.4.0.Beta1'
+compile 'io.vertx:vertx-auth-common:3.4.0-SNAPSHOT'
 ----
 
 == Basic concepts

vertx-auth-common/src/main/asciidoc/js/index.adoc

@@ -14,15 +14,15 @@ To use this project, add the following dependency to the _dependencies_ section
 <dependency>
   <groupId>io.vertx</groupId>
   <artifactId>vertx-auth-common</artifactId>
-  <version>3.4.0.Beta1</version>
+  <version>3.4.0-SNAPSHOT</version>
 </dependency>
 ----
 
 * Gradle (in your `build.gradle` file):
 
 [source,groovy,subs="+attributes"]
 ----
-compile 'io.vertx:vertx-auth-common:3.4.0.Beta1'
+compile 'io.vertx:vertx-auth-common:3.4.0-SNAPSHOT'
 ----
 
 == Basic concepts

vertx-auth-common/src/main/asciidoc/kotlin/index.adoc

@@ -0,0 +1,162 @@
+= Vert.x Auth - Authentication and Authorisation
+
+This Vert.x component provides interfaces for authentication and authorisation that can be used from
+your Vert.x applications and can be backed by different providers.
+
+Vert.x auth is also used by vertx-web to handle its authentication and authorisation.
+
+To use this project, add the following dependency to the _dependencies_ section of your build descriptor:
+
+* Maven (in your `pom.xml`):
+
+[source,xml,subs="+attributes"]
+----
+<dependency>
+  <groupId>io.vertx</groupId>
+  <artifactId>vertx-auth-common</artifactId>
+  <version>3.4.0-SNAPSHOT</version>
+</dependency>
+----
+
+* Gradle (in your `build.gradle` file):
+
+[source,groovy,subs="+attributes"]
+----
+compile 'io.vertx:vertx-auth-common:3.4.0-SNAPSHOT'
+----
+
+== Basic concepts
+
+_Authentication_ means verifying the identity of a user.
+
+_Authorisation_ means verifying a user has an authority.
+
+What the authority means is determined by the particular implementation and we don't mandate any particular model,
+e.g. a permissions/roles model, to keep things very flexible.
+
+For some implementations an authority might represent a permission, for example the authority to access all printers,
+or a specific printer. Other implementations must support roles too, and will often represent this by prefixing
+the authority with something like `role:`, e.g. `role:admin`. Another implementation might have a completely
+different model of representing authorities.
+
+To find out what a particular auth provider expects, consult the documentation for that auth provider..
+
+== Authentication
+
+To authenticate a user you use `link:../../apidocs/io/vertx/ext/auth/AuthProvider.html#authenticate-io.vertx.core.json.JsonObject-io.vertx.core.Handler-[authenticate]`.
+
+The first argument is a JSON object which contains authentication information. What this actually contains depends
+on the specific implementation; for a simple username/password based authentication it might contain something like:
+
+----
+{
+  "username": "tim"
+  "password": "mypassword"
+}
+----
+
+For an implementation based on JWT token or OAuth bearer tokens it might contain the token information.
+
+Authentication occurs asynchronously and the result is passed to the user on the result handler that was provided in
+the call. The async result contains an instance of `link:../../apidocs/io/vertx/ext/auth/User.html[User]` which represents the authenticated
+user and contains operations which allow the user to be authorised.
+
+Here's an example of authenticating a user using a simple username/password implementation:
+
+[source,java]
+----
+
+var authInfo = json {
+  obj(
+    "username" to "tim",
+    "password" to "mypassword"
+  )
+}
+
+authProvider.authenticate(authInfo, { res ->
+  if (res.succeeded()) {
+
+    var user = res.result()
+
+    println("User ${user.principal()} is now authenticated")
+
+  } else {
+    res.cause().printStackTrace()
+  }
+})
+
+----
+
+== Authorisation
+
+Once you have an `link:../../apidocs/io/vertx/ext/auth/User.html[User]` instance you can call methods on it to authorise it.
+
+to check if a user has a specific authority you use `link:../../apidocs/io/vertx/ext/auth/User.html#isAuthorised-java.lang.String-io.vertx.core.Handler-[isAuthorised]`.
+
+The results of all the above are provided asynchronously in the handler.
+
+Here's an example of authorising a user:
+
+[source,java]
+----
+
+user.isAuthorised("printers:printer1234", { res ->
+  if (res.succeeded()) {
+
+    var hasAuthority = res.result()
+
+    if (hasAuthority) {
+      println("User has the authority")
+    } else {
+      println("User does not have the authority")
+    }
+
+  } else {
+    res.cause().printStackTrace()
+  }
+})
+
+----
+
+And another example of authorising in a roles based model which uses `role:` as a prefix.
+
+Please note, as discussed above how the authority string is interpreted is completely determined by the underlying
+implementation and Vert.x makes no assumptions here.
+
+=== Caching authorities
+
+The user object will cache any authorities so subsequently calls to check if it has the same authorities will result
+in the underlying provider being called.
+
+In order to clear the internal cache you can use `link:../../apidocs/io/vertx/ext/auth/User.html#clearCache--[clearCache]`.
+
+=== The User Principal
+
+You can get the Principal corresponding to the authenticated user with `link:../../apidocs/io/vertx/ext/auth/User.html#principal--[principal]`.
+
+What this returns depends on the underlying implementation.
+
+== Creating your own auth implementation
+
+If you wish to create your own auth provider you should implement the `link:../../apidocs/io/vertx/ext/auth/AuthProvider.html[AuthProvider]` interface.
+
+We provide an abstract implementation of user called `link:../../apidocs/io/vertx/ext/auth/AbstractUser.html[AbstractUser]` which you can subclass
+to make your user implementation. This contains the caching logic so you don't have to implement that yourself.
+
+If you wish your user objects to be clusterable you should make sure they implement `link:../../apidocs/io/vertx/core/shareddata/impl/ClusterSerializable.html[ClusterSerializable]`.
+
+== Pseudo Random Number Generator
+
+Since Secure Random from java can block during the aquisition of entropy from the system, we provide a simple wrapper
+around it that can be used without the danger of blocking the event loop.
+
+By default this PRNG uses a mixed mode, blocking for seeding, non blocking for generating. The PRNG will also reseed
+every 5 minutes with 64bits of new entropy. However this can all be configured using the system properties:
+
+* io.vertx.ext.auth.prng.algorithm e.g.: SHA1PRNG
+* io.vertx.ext.auth.prng.seed.interval e.g.: 1000 (every second)
+* io.vertx.ext.auth.prng.seed.bits e.g.: 128
+
+Most users should not need to configure these values unless if you notice that the performance of your application is
+being affected by the PRNG algorithm.
+<a href="mailto:julien@julienviet.com">Julien Viet</a><a href="http://tfox.org">Tim Fox</a>

vertx-auth-common/src/main/asciidoc/ruby/index.adoc

@@ -14,15 +14,15 @@ To use this project, add the following dependency to the _dependencies_ section
 <dependency>
   <groupId>io.vertx</groupId>
   <artifactId>vertx-auth-common</artifactId>
-  <version>3.4.0.Beta1</version>
+  <version>3.4.0-SNAPSHOT</version>
 </dependency>
 ----
 
 * Gradle (in your `build.gradle` file):
 
 [source,groovy,subs="+attributes"]
 ----
-compile 'io.vertx:vertx-auth-common:3.4.0.Beta1'
+compile 'io.vertx:vertx-auth-common:3.4.0-SNAPSHOT'
 ----
 
 == Basic concepts