25.8. Data Security for Remote Client Server Mode
25.8.1. About Security Realms
ManagementRealm
stores authentication information for the Management API, which provides the functionality for the Management CLI and web-based Management Console. It provides an authentication system for managing JBoss Data Grid Server itself. You could also use theManagementRealm
if your application needed to authenticate with the same business rules you use for the Management API.ApplicationRealm
stores user, password, and role information for Web Applications and EJBs.
REALM-users.properties
stores usernames and hashed passwords.REALM-roles.properties
stores user-to-role mappings.mgmt-groups.properties
stores user-to-role mapping file forManagementRealm
.
standalone/configuration/
directories. The files are written simultaneously by the add-user.sh
or add-user.bat
command. When you run the command, the first decision you make is which realm to add your new user to.
25.8.2. Add a New Security Realm
Run the Management CLI.
Start thecli.sh
orcli.bat
command and connect to the server.Create the new security realm itself.
Run the following command to create a new security realm namedMyDomainRealm
on a domain controller or a standalone server./host=master/core-service=management/security-realm=MyDomainRealm:add()
Create the references to the properties file which will store information about the new realm's users.
Run the below command to define the location of the new security realm's properties file; this file contains information regarding the users of this security realm. The following command references a file namedmyfile.properties
in thejboss.server.config.dir
.Note
The newly-created properties file is not managed by the includedadd-user.sh
andadd-user.bat
scripts. It must be managed externally./host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path="myfile.properties",relative-to="jboss.server.config.dir")
Reload the server
Reload the server so the changes will take effect.:reload
The new security realm is created. When you add users and roles to this new realm, the information will be stored in a separate file from the default security realms. You can manage this new file using your own applications or procedures.
25.8.3. Add a User to a Security Realm
Run the
add-user.sh
oradd-user.bat
command.Open a terminal and change directories to theJDG_HOME/bin/
directory. If you run Red Hat Enterprise Linux or another UNIX-like operating system, runadd-user.sh
. If you run Microsoft Windows Server, runadd-user.bat
.Choose whether to add a Management User or Application User.
For this procedure, typeb
to add an Application User.Choose the realm the user will be added to.
By default, the only available realms are theManagementRealm
andApplicationRealm
; however, if a custom realm has been added, then its name may be entered instead.Type the username, password, and roles, when prompted.
Type the desired username, password, and optional roles when prompted. Verify your choice by typingyes
, or typeno
to cancel the changes. The changes are written to each of the properties files for the security realm.
25.8.4. Configuring Security Realms Declaratively
authentication
and an authorization
section.
Example 25.7. Configuring Security Realms Declaratively
<security-realms> <security-realm name="ManagementRealm"> <authentication> <local default-user="$local" skip-group-loading="true"/> <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/> </authentication> <authorization map-groups-to-roles="false"> <properties path="mgmt-groups.properties" relative-to="jboss.server.config.dir"/> </authorization> </security-realm> <security-realm name="ApplicationRealm"> <authentication> <local default-user="$local" allowed-users="*" skip-group-loading="true"/> <properties path="application-users.properties" relative-to="jboss.server.config.dir"/> </authentication> <authorization> <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/> </authorization> </security-realm> </security-realms>
server-identities
parameter can also be used to specify certificates.
25.8.5. Loading Roles from LDAP for Authorization (Remote Client-Server Mode)
memberOf
attributes; a group entity may map which users belong to it through uniqueMember
attributes; or both mappings may be maintained by the LDAP server.
force
attribute is set to "false". When force
is true, the search is performed again during authorization (while loading groups). This is typically done when different servers perform authentication and authorization.
<authorization> <ldap connection="..."> <!-- OPTIONAL --> <username-to-dn force="true"> <!-- Only one of the following. --> <username-is-dn /> <username-filter base-dn="..." recursive="..." user-dn-attribute="..." attribute="..." /> <advanced-filter base-dn="..." recursive="..." user-dn-attribute="..." filter="..." /> </username-to-dn> <group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." > <!-- One of the following --> <group-to-principal base-dn="..." recursive="..." search-by="..."> <membership-filter principal-attribute="..." /> </group-to-principal> <principal-to-group group-attribute="..." /> </group-search> </ldap> </authorization>
Important
force
attribute. It is required, even when set to the default value of false
.
username-to-dn
username-to-dn
element specifies how to map the user name to the distinguished name of their entry in the LDAP directory. This element is only required when both of the following are true:
- The authentication and authorization steps are against different LDAP servers.
- The group search uses the distinguished name.
- 1:1 username-to-dn
- This specifies that the user name entered by the remote user is the user's distinguished name.
<username-to-dn force="false"> <username-is-dn /> </username-to-dn>
This defines a 1:1 mapping and there is no additional configuration. - username-filter
- The next option is very similar to the simple option described above for the authentication step. A specified attribute is searched for a match against the supplied user name.
<username-to-dn force="true"> <username-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" attribute="sn" user-dn-attribute="dn" /> </username-to-dn>
The attributes that can be set here are:base-dn
: The distinguished name of the context to begin the search.recursive
: Whether the search will extend to sub contexts. Defaults tofalse
.attribute
: The attribute of the users entry to try and match against the supplied user name. Defaults touid
.user-dn-attribute
: The attribute to read to obtain the users distinguished name. Defaults todn
.
- advanced-filter
- The final option is to specify an advanced filter, as in the authentication section this is an opportunity to use a custom filter to locate the users distinguished name.
<username-to-dn force="true"> <advanced-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" filter="sAMAccountName={0}" user-dn-attribute="dn" /> </username-to-dn>
For the attributes that match those in the username-filter example, the meaning and default values are the same. There is one new attribute:filter
: Custom filter used to search for a user's entry where the user name will be substituted in the{0}
place holder.
Important
The XML must remain valid after the filter is defined so if any special characters are used such as&
ensure the proper form is used. For example&
for the&
character.
The Group Search
Example 25.8. Principal to Group - LDIF example.
TestUserOne
who is a member of GroupOne
, GroupOne
is in turn a member of GroupFive
. The group membership is shown by the use of a memberOf
attribute which is set to the distinguished name of the group of which the user (or group) is a member.
memberOf
attributes set, one for each group of which the user is directly a member.
dn: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org objectClass: extensibleObject objectClass: top objectClass: groupMember objectClass: inetOrgPerson objectClass: uidObject objectClass: person objectClass: organizationalPerson cn: Test User One sn: Test User One uid: TestUserOne distinguishedName: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org memberOf: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org memberOf: uid=Slashy/Group,ou=groups,dc=principal-to-group,dc=example,dc=org userPassword:: e1NTSEF9WFpURzhLVjc4WVZBQUJNbEI3Ym96UVAva0RTNlFNWUpLOTdTMUE9PQ== dn: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org objectClass: extensibleObject objectClass: top objectClass: groupMember objectClass: group objectClass: uidObject uid: GroupOne distinguishedName: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org memberOf: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org dn: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org objectClass: extensibleObject objectClass: top objectClass: groupMember objectClass: group objectClass: uidObject uid: GroupFive distinguishedName: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org
Example 25.9. Group to Principal - LDIF Example
TestUserOne
who is a member of GroupOne
which is in turn a member of GroupFive
- however in this case it is an attribute uniqueMember
from the group to the user being used for the cross reference.
dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org objectClass: top objectClass: inetOrgPerson objectClass: uidObject objectClass: person objectClass: organizationalPerson cn: Test User One sn: Test User One uid: TestUserOne userPassword:: e1NTSEF9SjR0OTRDR1ltaHc1VVZQOEJvbXhUYjl1dkFVd1lQTmRLSEdzaWc9PQ== dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org objectClass: top objectClass: groupOfUniqueNames objectClass: uidObject cn: Group One uid: GroupOne uniqueMember: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org dn: uid=GroupFive,ou=subgroups,ou=groups,dc=group-to-principal,dc=example,dc=org objectClass: top objectClass: groupOfUniqueNames objectClass: uidObject cn: Group Five uid: GroupFive uniqueMember: uid=TestUserFive,ou=users,dc=group-to-principal,dc=example,dc=org uniqueMember: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org
General Group Searching
<group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." > ... </group-search>
group-name
: This attribute is used to specify the form that should be used for the group name returned as the list of groups of which the user is a member. This can either be the simple form of the group name or the group's distinguished name. If the distinguished name is required this attribute can be set toDISTINGUISHED_NAME
. Defaults toSIMPLE
.iterative
: This attribute is used to indicate if, after identifying the groups a user is a member of, we should also iteratively search based on the groups to identify which groups the groups are a member of. If iterative searching is enabled we keep going until either we reach a group that is not a member if any other groups or a cycle is detected. Defaults tofalse
.
Important
group-dn-attribute
: On an entry for a group which attribute is its distinguished name. Defaults todn
.group-name-attribute
: On an entry for a group which attribute is its simple name. Defaults touid
.
Example 25.10. Principal to Group Example Configuration
memberOf
attribute on the user.
<authorization> <ldap connection="LocalLdap"> <username-to-dn> <username-filter base-dn="ou=users,dc=principal-to-group,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" /> </username-to-dn> <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid"> <principal-to-group group-attribute="memberOf" /> </group-search> </ldap> </authorization>
principal-to-group
element has been added with a single attribute.
group-attribute
: The name of the attribute on the user entry that matches the distinguished name of the group the user is a member of. Defaults tomemberOf
.
Example 25.11. Group to Principal Example Configuration
<authorization> <ldap connection="LocalLdap"> <username-to-dn> <username-filter base-dn="ou=users,dc=group-to-principal,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" /> </username-to-dn> <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid"> <group-to-principal base-dn="ou=groups,dc=group-to-principal,dc=example,dc=org" recursive="true" search-by="DISTINGUISHED_NAME"> <membership-filter principal-attribute="uniqueMember" /> </group-to-principal> </group-search> </ldap> </authorization>
group-to-principal
is added. This element is used to define how searches for groups that reference the user entry will be performed. The following attributes are set:
base-dn
: The distinguished name of the context to use to begin the search.recursive
: Whether sub-contexts also be searched. Defaults tofalse
.search-by
: The form of the role name used in searches. Valid values areSIMPLE
andDISTINGUISHED_NAME
. Defaults toDISTINGUISHED_NAME
.
principal-attribute
: The name of the attribute on the group entry that references the user entry. Defaults tomember
.