For standalone applications, you can use plain Shiro easily. The only thing to do is to register a configured SecurityManager when activating your Zest™ Application. It can be done outside the application, before its activation, "à là" by-hand ;

IniSecurityManagerFactory factory = new IniSecurityManagerFactory( "classpath:standalone-shiro.ini" );
SecurityManager securityManager = factory.getInstance();
SecurityUtils.setSecurityManager( securityManager );

note that this example code register the SecurityManager as a VM static singleton.

However we recommend to use the provided IniSecurityManagerService that does exactly this when activated and unregister the SecurityManager when passivated:

new StandaloneShiroAssembler().
    withConfig( configModule, Visibility.layer ).
    assemble( module );

You can change the INI resource path through the ShiroIniConfiguration:

public interface ShiroIniConfiguration
        extends ConfigurationComposite
{

    /**
     * Resource path of the ini configuration file.
     * "classpath:", "file": and "url:" prefixes are supported.
     * Defaulted to "classpath:shiro.ini".
     */
    @Optional
    Property<String> iniResourcePath();

}

Remember that this setup use a ThreadLocal SecurityManager singleton. Among other things it means that, althoug the IniSecurityManagerService is activated on Application activation, if you need to use Shiro in other Services that are activated on Application activation you should tell Zest™ about this dependency by injecting the SecurityManagerService in the laters.

Once started you must remember to register the SecurityManager in Shiro’s ThreadContext ;

@Service
private IniSecurityManagerService securityManagerService;

  [...snip...]

public void interactionBegins()
{
    ThreadContext.bind( securityManagerService.getSecurityManager() );
}

  [...snip...]

public void interactionEnds()
{
    ThreadContext.unbindSubject();
    ThreadContext.unbindSecurityManager();
}

that’s how Shiro works.

This library provides the SecurityConcern that should be used alongside the provided method annotations that mimic Apache Shiro annotations:

All the above is sufficient as long as you use the ini file to store user credentials and permissions or a Realm that has no dependency on your application code and can be specified in the ini file to be instanciated by Shiro outside the Zest™ scope.

One usecase where it’s not sufficient comes quickly as you would like to provide user credentials and permissions from Entities stored in an EntityStore or perform any custom logic involving your Zest™ Application.

Let’s look at a complete example using a Realm Service that extends one of the Shiro provided Realm which use in-memory credientials and configuring it ;

@Mixins( MyRealmMixin.class )
public interface MyRealmService
        extends Realm, ServiceComposite, ServiceActivation
{
}

  [...snip...]

public class MyRealmMixin
        extends SimpleAccountRealm
        implements ServiceActivation
{

    private final PasswordService passwordService;

    public MyRealmMixin()
    {
        super();
        passwordService = new DefaultPasswordService();
        PasswordMatcher matcher = new PasswordMatcher();
        matcher.setPasswordService( passwordService );
        setCredentialsMatcher( matcher );
    }

    public void activateService()
            throws Exception
    {
        // Create a test account
        addAccount( "foo", passwordService.encryptPassword( "bar" ) );
    }

      [...snip...]


}

@Override
public void assemble( ModuleAssembly module )
        throws AssemblyException
{
  [...snip...]

    new StandaloneShiroAssembler().
        withConfig( configModule, Visibility.layer ).
        assemble( module );
    module.services( MyRealmService.class );

      [...snip...]

}

We start by defining a Realm Service and its Mixin that’s based on SimpleAccountRealm that we configure to handle hashed passwords. For the sake of the example it is shown how to hash a password using Shiro built in mecanisms. Then comes the Assembly where we simply reuse the Standalone Shiro Assembly and declare our Realm as a Service. It works the same way when using the Shiro Web Security Library.

Note that under the hood, assembled Realm Services are added to the ones configured in the INI file.

Going further, if you want to persist credentials and permissions in an EntityStore, the Shiro Security Library provides skeletons to easily setup some usecases consisting of Shiro setup facilities and base state model for you to compose with.

public interface User
        extends PasswordSecurable
{
}

  [...snip...]

@Mixins( UserFactoryMixin.class )
public interface UserFactory
{

    User createNewUser( String username, String password );

}

  [...snip...]

public static class UserFactoryMixin
        implements UserFactory
{

    @Structure
    private UnitOfWorkFactory uowf;

    @Service
    private PasswordService passwordService;

    @Override
    public User createNewUser( String username, String password )
    {
        EntityBuilder<User> userBuilder = uowf.currentUnitOfWork().newEntityBuilder( User.class );
        User user = userBuilder.instance();
        user.subjectIdentifier().set( username );
        user.password().set( passwordService.encryptPassword( password ) );
        return userBuilder.newInstance();
    }

}

@Override
public void assemble( ModuleAssembly module )
        throws AssemblyException
{
  [...snip...]

    new StandaloneShiroAssembler().
        withConfig( configModule, Visibility.layer ).
        assemble( module );
    new PasswordDomainAssembler().
        withConfig( configModule, Visibility.layer ).
        assemble( module );

    module.entities( User.class );
    module.services( UserFactory.class );

      [...snip...]

}

User user = userFactory.createNewUser( "foo", "bar" );

  [...snip...]

Subject currentUser = SecurityUtils.getSubject();
currentUser.login( new UsernamePasswordToken( "foo", "bar" ) );

/**
 * Sets the name of the MessageDigest algorithm that will be used to compute hashes.
 */
@Optional
Property<String> hashAlgorithmName();

/**
 * Sets the number of hash iterations that will be performed during hash computation.
 */
@Optional
Property<Integer> hashIterationsCount();

public interface User
        extends PasswordSecurable, RoleAssignee
{
}

new StandaloneShiroAssembler().
    withConfig( configModule, Visibility.layer ).
    assemble( module );
new PasswordDomainAssembler().
    withConfig( configModule, Visibility.layer ).
    assemble( module );
new PermissionsDomainAssembler().
    assemble( module );

module.entities( User.class );
module.services( UserFactory.class );

UnitOfWork uow = unitOfWorkFactory.newUnitOfWork();

User user = userFactory.createNewUser( "foo", "bar" );
Role role = roleFactory.create( "role-one", "permission-one", "permission-two" );
role.assignTo( user );

uow.complete();

  [...snip...]

uow = unitOfWorkFactory.newUnitOfWork();

Subject currentUser = SecurityUtils.getSubject();
currentUser.login( new UsernamePasswordToken( "foo", "bar" ) );

if ( !currentUser.hasRole( "role-one" ) ) {
    fail( "User 'foo' must have 'role-one' role." );
}

if ( !currentUser.isPermitted( "permission-one" ) ) {
    fail( "User 'foo' must have 'permission-one' permission." );
}

  [...snip...]

uow.discard();

For other authentication mecanisms you can leverage Shiro extensions available in the Shiro distribution or as external libraries. There’s support for text files, simple JDBC, LDAP, CAS SSO, OAuth, OpenID, X.509 Certificates etc…

Take the PasswordRealmService as a start and extend/rewrite it to suit your needs.

If you happen to come with a Zest™ integration that could be valuable in this very library, don’t hesitate to contribute.

All code from this library use the org.apache.zest.library.shiro logger.