Setting up with Shiro

This section describes how to setup and configure SecMan with framework’s Shiro integration being used for primary authentication.

The primary use case this enables is for authentication to be performed through an external mechanism, for example LDAP.

If delegate authentication has been set up, this means that authentication may pass for a user that Secman knows nothing about. In this case Secman will automatically create an ApplicationUser for this externally delegated authenticated user, with its type set to "DELEGATED".

The integration does still allow for local logins (type set to "LOCAL") of ApplicationUsers if required.

Dependencies

In addition to the regular dependencies required by Secman, also add in Secman’s Shiro Realm implementation:

pom.xml

<dependencies>
        <dependency>
            <groupId>org.apache.isis.extensions</groupId>
            <artifactId>isis-extensions-secman-persistence-XXX</artifactId> (1)
        </dependency>
        <dependency>
            <groupId>org.apache.isis.extensions</groupId>
            <artifactId>isis-extensions-secman-encryption-jbcrypt</artifactId> (2)
        </dependency>
        <dependency>
            <groupId>org.apache.isis.extensions</groupId>
            <artifactId>isis-extensions-secman-shiro-realm</artifactId>
        </dependency>
</dependencies>

1	specify either `isis-extensions-secman-persistence-jpa` or `isis-extensions-secman-persistence-jdo`, as required
2	provides an implementation of `PasswordEncryptionService`

Update AppManifest

In addition to the other modules that Secman requires to be added to your application’s AppManifest, also add: You will also need to import the fixture module; SecMan uses fixture scripts to seed its entities:

AppManifest.java

@Configuration
@Import({
        ...
        IsisModuleExtSecmanRealmShiro.class,    (1)
        ...
})
public class AppManifest {
}

1	enables Shiro integration (so that Shiro delegates to Secman for authentication). This brings in a transitive dependency on the `IsisModuleSecurityShiro` module.

Ensure that no other IsisModuleSecurityXxx module is imported into the AppManifest.

Shiro (Delegate) Realm

SecMan’s Shiro realm is configured using the shiro.ini file. The following sets up Shiro without delegation:

shiro.ini

[main]

authenticationStrategy=org.apache.isis.extensions.secman.shiro.AuthenticationStrategyForIsisModuleSecurityRealm
isisModuleSecurityRealm=org.apache.isis.extensions.secman.shiro.IsisModuleExtSecmanShiroRealm

securityManager.authenticator.authenticationStrategy = $authenticationStrategy
securityManager.realms = $isisModuleSecurityRealm

[users]
[roles]

The [users] and [roles] sections are required but are unused.

The main point of introducing Shiro though is to introduce support for authentication by external mechanisms such as LDAP. In this case we configure Shiro to use the external realm as the primary realm, with Secman’s Shiro realm set up as a "delegate" realm. We specify the delegate realm implementation in the shiro.ini file, and "inject" it into the Secman realm.

For example, to use LDAP Realm for Shiro as a delegate:

shiro.ini

[main]

...
ldapRealm=org.apache.isis.extensions.shirorealmldap.realm.impl.IsisLdapRealm (1)
ldapRealm.xxx=...                                                            (2)
ldapRealm.yyy=...

isisModuleSecurityRealm.delegateAuthenticationRealm=$ldapRealm               (3)

...

1	instantiate the LDAP realm
2	configure the LDAP realm as required
3	specify the LDAP realm as the delegate realm for SecMan’s own realm.

Configuration Properties

As mentioned in the introduction, if delegate authentication has been set up, this means that authentication may pass for a user that Secman knows nothing about. In this case Secman will automatically create an ApplicationUser for this externally delegated authenticated user, with the type set to "DELEGATED".

We can configure whether such automatically created accounts should be unlocked or locked by default:

application.yml

isis:
  extensions:
    secman:
      delegated-users:
        auto-create-policy: AUTO_CREATE_AS_LOCKED