The Apache Shiro Auth provider implementation

The Apache Shiro Auth provider implementation
Authentication
Authorisation - Permission-Role Model

The Apache Shiro Auth provider implementation

This is an auth provider implementation that uses Apache Shiro.

To use this project, add the following dependency to the dependencies section of your build descriptor:

Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-auth-shiro</artifactId>
  <version>3.5.3-SNAPSHOT</version>
</dependency>

Gradle (in your build.gradle file):

compile 'io.vertx:vertx-auth-shiro:3.5.3-SNAPSHOT'

We provide out of the box support for properties and LDAP based auth using Shiro, and you can also plugin in any other Shiro Realm which expects username and password for credentials.

To create an instance of the provider you use ShiroAuth. You specify the type of Shiro auth provider that you want with ShiroAuthRealmType, and you specify the configuration in a JSON object.

Here’s an example of creating a Shiro auth provider by specifying the type:

var ShiroAuth = require("vertx-auth-shiro-js/shiro_auth");

var config = {
  "properties_path" : "classpath:test-auth.properties"
};

var provider = ShiroAuth.create(vertx, 'PROPERTIES', config);

Authentication

When authenticating using this implementation, it assumes username and password fields are present in the authentication info:

var authInfo = {
  "username" : "tim",
  "password" : "sausages"
};

authProvider.authenticate(authInfo, function (res, res_err) {
  if (res_err == null) {
    var user = res;
  } else {
    // Failed!
  }
});

Authorisation - Permission-Role Model

Although Vert.x auth itself does not mandate any specific model of permissions (they are just opaque strings), this implementation uses a familiar user/role/permission model, where a user can have zero or more roles and a role can have zero or more permissions.

If validating if a user has a particular permission simply pass the permission into. isAuthorised as follows:

user.isAuthorised("newsletter:edit:13", function (res, res_err) {
  if (res_err == null) {
    var hasPermission = res;
  } else {
    // Failed to
  }
});

If validating that a user has a particular role then you should prefix the argument with the role prefix.

user.isAuthorised("role:manager", function (res, res_err) {
  if (res_err == null) {
    var hasRole = res;
  } else {
    // Failed to
  }
});

The default role prefix is role:. You can change this with setRolePrefix.

The Shiro properties auth provider

This auth provider implementation uses Apache Shiro to get user/role/permission information from a properties file.

Note that roles are not available directly on the API due to the fact that vertx-auth tries to be as portable as possible. However one can run assertions on role by using the prefix role: or by specifying the prefered prefix with setRolePrefix.

The implementation will, by default, look for a file called vertx-users.properties on the classpath.

If you want to change this, you can use the properties_path configuration element to define how the properties file is found.

The default value is classpath:vertx-users.properties.

If the value is prefixed with classpath: then the classpath will be searched for a properties file of that name.

If the value is prefixed with file: then it specifies a file on the file system.

If the value is prefixed with url: then it specifies a URL from where to load the properties.

The properties file should have the following structure:

Each line should either contain the username, password and roles for a user or the permissions in a role.

For a user line it should be of the form:

user.{username}={password},{roleName1},{roleName2},...,{roleNameN}

For a role line it should be of the form:

role.{roleName}={permissionName1},{permissionName2},...,{permissionNameN}

Here’s an example:

user.tim = mypassword,administrator,developer
user.bob = hispassword,developer
user.joe = anotherpassword,manager
role.administrator=*
role.manager=play_golf,say_buzzwords
role.developer=do_actual_work

When describing roles a wildcard * can be used to indicate that the role has all permissions.

The Shiro LDAP auth provider

The LDAP auth realm gets user/role/permission information from an LDAP server.

The following configuration properties are used to configure the LDAP realm:

ldap-user-dn-template: this is used to determine the actual lookup to use when looking up a user with a particular id. An example is uid={0},ou=users,dc=foo,dc=com - the element {0} is substituted with the user id to create the actual lookup. This setting is mandatory.
ldap_url: the url to the LDAP server. The url must start with ldap:// and a port must be specified. An example is ldap://myldapserver.mycompany.com:10389
ldap-authentication-mechanism: TODO
ldap-context-factory-class-name: TODO
ldap-pooling-enabled: TODO
ldap-referral: TODO
ldap-system-username: TODO
ldap-system-password: TODO

Using another Shiro Realm

It’s also possible to create an auth provider instance using a pre-created Apache Shiro Realm object.

This is done as follows:

var ShiroAuth = require("vertx-auth-shiro-js/shiro_auth");

var provider = ShiroAuth.create(vertx, realm);

The implementation currently assumes that user/password based authentication is used. <a href="mailto:[email protected]">Julien Viet</a><a href="http://tfox.org">Tim Fox</a>

The Apache Shiro Auth provider implementation

Table of Contents