Table of Contents

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 module.ceylon:

shared import io.vertx.ceylon.auth.common "3.3.2";

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

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 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: