= IsisLdapRealm
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Implementation of _org.apache.shiro.realm.ldap.JndiLdapRealm_ that also returns each user's groups.

Sample config for `shiro.ini` :

----

contextFactory = org.apache.isis.extensions.shirorealmldap.realm.impl.IsisLdapContextFactory
contextFactory.url = ldap://localhost:10389
contextFactory.authenticationMechanism = CRAM-MD5
contextFactory.systemAuthenticationMechanism = simple
contextFactory.systemUsername = uid=admin,ou=system
contextFactory.systemPassword = secret

ldapRealm = org.apache.isis.extensions.shirorealmldap.realm.impl.IsisLdapRealm
ldapRealm.contextFactory = $contextFactory

ldapRealm.searchBase = ou=groups,o=mojo
ldapRealm.groupObjectClass = groupOfUniqueNames
ldapRealm.uniqueMemberAttribute = uniqueMember
ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}

ldapRealm.searchUserBase = ou=users,o=mojo
ldapRealm.userObjectClass=inetOrgPerson
ldapRealm.groupExtractedAttribute=street,country
ldapRealm.userExtractedAttribute=street,country
ldapRealm.permissionByGroupAttribute=attribute:Folder.{street}:Read,attribute:Portfolio.{country}
ldapRealm.permissionByUserAttribute=attribute:Folder.{street}:Read,attribute:Portfolio.{country}

# optional mapping from physical groups to logical application roles
ldapRealm.rolesByGroup = \
   LDN_USERS: user_role,\
   NYK_USERS: user_role,\
   HKG_USERS: user_role,\
   GLOBAL_ADMIN: admin_role,\
   DEMOS: self-install_role

securityManager.realms = $ldapRealm
----

The permissions for each role can be specified using the _#setResourcePath(String)_ to an 'ini' file with a [roles] section, eg:

----

ldapRealm.resourcePath=classpath:webapp/myroles.ini
----

where `myroles.ini` is in `src/main/resources/webapp` , and takes the form:

----

[roles]
user_role = *:ToDoItemsJdo:*:*,\
            *:ToDoItem:*:*
self-install_role = *:ToDoItemsFixturesService:install:*
admin_role = *
----

This 'ini' file can then be referenced by other realms (if multiple realm are configured with the Shiro security manager).

Alternatively, permissions can be extracted from the base itself with the parameter searchUserBase, the attribute list as userExtractedAttribute and the permission url as permissionByUserAttribute. The idea is to extract attribute from the user or the group of the user and map directly to permission rule in replacing the string {attribute} by the extracted attribute (can me multiple). See the sample for group and user attribute and mapping.

== API

[source,java]
.IsisLdapRealm.java
----
class IsisLdapRealm {
  IsisLdapRealm()
  void setSearchBase(String searchBase)
  void setGroupObjectClass(String groupObjectClassAttribute)
  void setUniqueMemberAttribute(String uniqueMemberAttribute)
  void setUniqueMemberAttributeValueTemplate(String template)
  void setRolesByGroup(Map<String, String> rolesByGroup)
  void setResourcePath(String resourcePath)     // <.>
  void setPermissionByUserAttribute(String permissionByUserAttr)
  void setPermissionByGroupAttribute(String permissionByGroupAttribute)
  void setUserExtractedAttribute(String userExtractedAttribute)
  void setGroupExtractedAttribute(String groupExtractedAttribute)
  void setSearchUserBase(String searchUserBase)
  void setUserObjectClass(String userObjectClass)
  void setCnAttribute(String cnAttribute)
}
----

<.> xref:#setResourcePath_String[setResourcePath(String)]
+
--

--

== Members

[#setResourcePath_String]
=== setResourcePath(String)

----

ldapRealm.resourcePath=classpath:webapp/myroles.ini
----

where `myroles.ini` is in `src/main/resources/webapp` , and takes the form:This 'ini' file can then be referenced by other realms (if multiple realm are configured with the Shiro security manager).

----

[roles]
user_role = *:ToDoItemsJdo:*:*,\
            *:ToDoItem:*:*
self-install_role = *:ToDoItemsFixturesService:install:*
admin_role = *
----

