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

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.

README for Apache Fortress REST Security Model

Apache Fortress Rest Security Model


Table of Contents

  • Document Overview
  • Understand the security model of Apache Fortress Rest
  • SECTION 2. Java EE security
  • SECTION 3. Apache CXF's SimpleAuthorizingInterceptor
  • SECTION 4. Apache Fortress ARBAC Checks
  • SECTION 5. Java EE security and Apache CXF SimpleAuthorizingInterceptor policy load
  • SECTION 6. ARBAC policy load
  • SECTION 7. The list of Services that enforce ARBAC02

Document Overview

Provides a description of the various security mechanisms that are performed during Apache Fortress REST runtime operations.

Understand the security model of Apache Fortress Rest

A typical deployment:

(REST/JSON Client)<--https-->Servlet Container(FortressRealm/FortressREST)<--in-process-->(FortressCore)<--ldaps-->(DirectoryServer)

  • REST/JSON Client is any HTTP interface that supports the Apache Fortress message formats.
  • Servlet Container is Apache Tomcat.
  • Apache Fortress Realm plugs into the Servlet Container and performs declarative authN and authZ.
  • Apache Fortress Rest is a web application archive (.war) that deploys into the Servlet Container.
    • Uses JAX-RS services to wrap Apache Fortress Core APIs over HTTP.
  • Apache Fortress Core is a set of APIs that get embedded inside of Java apps like Apache Fortress Rest.
    • A one-to-one mapping between an Apache Fortress Rest service and Apache Fortress Core api.
  • Directory Server is an LDAPv3 server instance, like ApacheDS or OpenLDAP.

High-level flow:

  • The credentials are introduced into the call chain by the REST/JSON Client as standard HTTP basic auth header.
  • Passed into the Apache Fortress Realm for authentication and coarse-grained authorization by the Servlet Container.
  • Medium-grained authorization performed in the Apache Fortress Rest runtime at service dispatch time.
  • Next converted to an RBAC session and passed into the runtime inside the Fortress Request object.
  • The RBAC session gets passed into the Apache Fortress Core runtime for fine-grained checks (if enabled).

Apache Fortress Rest security model includes:

1. TLS

Be sure to use because it allows confidentiality of credentials and message content via HTTPS. Refer to the documentation of your servlet container for how to enable.

2. Java EE security

  • Apache Fortress Rest uses the Apache Fortress Realm to provide Java EE authentication, coarse-grained authorization mapping the users and roles back to a given LDAP server.
  • This interface requires standard HTTP Basic Auth tokens for the userid/password credentials.
  • The credentials are verified by the Apache Fortress Realm via bind op invocation to the Directory Server.
  • The coarse-grained authorization policy ensures callers have the RBAC Role fortress-rest-user.
  • Can be changed via the deployment descriptor, web.xml.

3. Apache CXF's SimpleAuthorizingInterceptor

This policy enforcement mechanism maps RBAC roles to a given set of services. The following table shows what roles map to which (sets of) services:

service typefortress-rest-super-userfortress-rest-admin-userfortress-rest-review-userfortress-rest-access-userfortress-rest-deladmin-userfortress-rest-delreview-userfortress-rest-delaccess-userfortress-rest-pwmgr-userfortress-rest-audit-userfortress-rest-config-user
Admin Managertruetruefalsefalsefalsefalsefalsefalsefalsefalse
Review Managertruefalsetruefalsefalsefalsefalsefalsefalsefalse
Access Managertruefalsefalsetruefalsefalsefalsefalsefalsefalse
Delegated Admintruefalsefalsefalsetruefalsefalsefalsefalsefalse
Delegated Reviewtruefalsefalsefalsefalsetruefalsefalsefalsefalse
Delegated Accesstruefalsefalsefalsefalsefalsetruefalsefalsefalse
Password Managertruefalsefalsefalsefalsefalsefalsetruefalsefalse
Audit Managertruefalsefalsefalsefalsefalsefalsefalsetruefalse
Config Managertruefalsefalsefalsefalsefalsefalsefalsefalsetrue
  • The service-to-role mappings are performed inside the FortressServiceImpl module.
  • For example, the deleteUser service:
@RolesAllowed({"fortress-rest-super-user", "fortress-rest-admin-user"})
public FortResponse deleteUser...
  • The caller needs either fortress-rest-super-user or fortress-rest-admin-user RBAC role to invoke the specified service.

4. Apache Fortress ARBAC Checks

The Apache Fortress Administrative Role-Based Access Control (ARBAC) subsystem handles delegating administrative tasks to special users. Disabled in Apache Fortress REST by default, to enable, add the following declaration to the


a. When enabled, all service invocations perform an ADMIN permission check by invoking DelAccessMgr.checkAccess down in the API layer.

For example, the permission with an objectName: and operation name: addUser is automatically checked during the call to the userAdd service.

This means at least one ADMIN role must be activated for the user calling the service that has been granted the required permission. The entire list of permissions, and their mappings to services are listed in the table that follows.

b. Some services (#'s 1 - 12 in ARBAC table below) perform organizational verification, comparing the org on the ADMIN role with that on the target user or permission in the HTTP request. There are two types of organizations being checked, User and Permission.

For example, roleAsgn and roleDeasgn (9 and 10 in ARBAC table) will verify that the caller has an ADMIN role with a user org unit that matches the ou of the target user. There is a similar check on roleGrant and roleRevoke (11 and 12) verifying the caller has an activated ADMIN role with a perm org unit that matches the ou on the target permission.

c. Some services (#'s 9,10,11,12 in ARBAC table) perform a range check on the target RBAC role to verify user has matching ADMIN role with authority to assign to user or grant to permission. The Apache Fortress REST roleAsgn, roleDeasgn, roleGrant and roleRevoke services will enforce ADMIN authority over the particular RBAC role that is being targeted in the HTTP request. These checks are based on a (hierarchical) range of roles, for which the target role must fall inside.

For example, the following top-down contains a sample RBAC role hierarchy for a fictional software development organization:

    |       |
   ENG      QC
  |   |   |    |   
 E1   E2  Q1   Q2
    |        |
   DA        QA

Here a role called CTO is the highest ascendant in the graph, and A1 is the lowest descendant. In a top-down role hierarchy, privilege increases as we descend downward. So a person with role A1 inherits all that are above.

In describing a range of roles, beginRange is the lowest descendant in the chain, and endRange the highest. Furthermore a bracket, ‘[’, ‘]’, indicates inclusiveness with an endpoint, whereas parenthesis, ‘(’, ‘)’ will exclude a corresponding endpoint.

Some example ranges that can be derived from the sample role graph above:

  • [A1, CTO] is the full set: {CTO, ENG, QC, E1, E2, Q1, Q2, DA, QA, A1}.
  • (A1, CTO) is the full set, minus the endpoints: {ENG, QC, E1, E2, Q1, Q2, DA, QA}.
  • [A1, ENG] includes: {A1, DA, E1, E2, ENG},
  • [A1, ENG) includes: {A1, DA, E1, E2}.
  • (QA, QC] has {Q1, Q2, QC} in its range.
  • etc...

For an administrator to be authorized to target an RBAC role in one of the specified APIs listed above, at least one of their activated ADMIN roles must pass the ARBAC role range test. There are currently two roles created by the security policy in this project, that are excluded from this type of check: fortress-rest-admin and fortress-core-super-admin.

Which means they won't have to pass the role range test. All others use the range field to define authority over a particular set of roles, in a hierarchical structure.

5. Java EE security and Apache CXF SimpleAuthorizingInterceptor policy load

a. The policy load file in this section performs the following:

  • Creates the RBAC Role, fortress-rest-user for the Java EE simple role check (described earlier). See web.xml.
  • Create the RBAC Roles for the Apache CXF SimpleAuthorizingInterceptor checks (also described earlier). See FortressInterceptor.
    • For example...
    • Users assigned to fortress-rest-admin-user have access to every RBAC admin service. e.g. addUser, addRole, addPermission
    • " " fortress-rest-review-user have access to every RBAC review services. e.g. readUser, readRole, readPermission
    • " " fortress-rest-deladmin-user have access to every ARBAC admin services.
    • etc...
  • Create an RBAC Role, fortress-rest-power-user, and make it the child of every other RBAC role.
    • Users assigned to this Role have access to every service.
  • Create a test user, demoUser4, assign to fortress-rest-power-user RBAC role.

b. Execute the policy load FortressRestServerPolicy into LDAP:

mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml

c. Now demoUser4 may execute every service and pass the JavaEE and Apache CXF interceptor checks.

6. ARBAC policy load

a. The ARBAC policies are enforced when the following property is present in runtime

# Boolean value. Disabled by default. If this is set to true, the runtime will enforce administrative permissions and ARBAC02 DA checks:

b. The policy load file in this section Creates an ADMIN Role named: fortress-rest-admin, and associates with (Test) Perm and User OUs:



Note: The Perm and User OUs must be created prior to the ARBAC sample load script being run. They get created during Apache Fortress Core integration testing. See FortressJUnitTest.

c. Next, the ARBAC sample policy load script performs:

  • Create one ADMIN Permission for every Apache Fortress Rest service.
  • Grant every ADMIN Perm to the ADMIN Role fortress-rest-admin.
  • Assign the ADMIN Role fortress-rest-admin to test User demoUser4.
  • Users who have been assigned fortress-rest-admin, like demoUser4, may...
    • call every Apache Fortress Rest service in this system and pass the ARBAC perm checks.
    • pass the ARBAC Org checks for (only) the data contained within the Apache Fortress core junit tests.
    • pass any/all Role range checks.

d. To load the FortressRestArbacSamplePolicy into LDAP:

mvn install -Dload.file=src/main/resources/FortressRestArbacSamplePolicy.xml

e. Now demoUser4 may invoke every service in the subsystem and pass all of the ARBAC checks corresponding with the test data inside of Apache Fortress Core's integration test suite.

7. The list of Services that enforce ARBAC checking.

#ServicesUserOU CheckPermOU CheckRole Range CheckADMIN Permissions
1userAddtruefalsefalseobjName=“” opName=“addUser”
2userUpdatetruefalsefalseobjName=“” opName=“updateUser”
3userDeletetruefalsefalseobjName=“” opName=“deleteUser”
4userDisabletruefalsefalseobjName=“” opName=“disableUser”
5userChangetruefalsefalseobjName=“” opName=“changePassword”
6userResettruefalsefalseobjName=“” opName=“resetPassword”
7userLocktruefalsefalseobjName=“” opName=“lockUserAccount”
8userUnlocktruefalsefalseobjName=“” opName=“unlockUserAccount”
9roleAsgntruefalsetrueobjName=“” opName=“assignUser”
10roleDeasgntruefalsetrueobjName=“” opName=“deassignUser”
11roleGrantfalsetruetrueobjName=“” opName=“grantPermission”
12roleRevokefalsetruetrueobjName=“” opName=“revokePermission”
13roleAddfalsefalsefalseobjName=“” opName=“addRole”
14roleDeletefalsefalsefalseobjName=“” opName=“deleteRole”
15roleUpdatefalsefalsefalseobjName=“” opName=“updateRole”
16addRoleConstraintfalsefalsefalseobjName=“” opName=“addRoleConstraint”
17removeRoleConstraintfalsefalsefalseobjName=“” opName=“removeRoleConstraint”
18roleEnableConstraintfalsefalsefalseobjName=“” opName=“enableRoleConstraint”
19roleDisableConstraintfalsefalsefalseobjName=“” opName=“disableRoleConstraint”
20permAddfalsefalsefalseobjName=“” opName=“addPermission”
21objAddfalsefalsefalseobjName=“” opName=“addPermObj”
22permDeletefalsefalsefalseobjName=“” opName=“deletePermission”
23objDeletefalsefalsefalseobjName=“” opName=“deletePermObj”
24permUpdatefalsefalsefalseobjName=“” opName=“updatePermission”
25objUpdatefalsefalsefalseobjName=“” opName=“updatePermObj”
26userGrantfalsefalsefalseobjName=“” opName=“grantPermissionUser”
27userRevokefalsefalsefalseobjName=“” opName=“revokePermissionUser”
28roleDescendantfalsefalsefalseobjName=“” opName=“addDescendant”
29roleAscendentfalsefalsefalseobjName=“” opName=“addAscendant”
30roleAddinheritfalsefalsefalseobjName=“” opName=“addInheritance”
31roleDelinheritfalsefalsefalseobjName=“” opName=“deleteInheritance”
32ssdAddfalsefalsefalseobjName=“” opName=“createSsdSet”
33ssdUpdatefalsefalsefalseobjName=“” opName=“updateSsdSet”
34ssdAddMemberfalsefalsefalseobjName=“” opName=“addSsdRoleMember”
35ssdDelMemberfalsefalsefalseobjName=“” opName=“deleteSsdRoleMember”
36ssdDeletefalsefalsefalseobjName=“” opName=“deleteSsdSet”
37ssdCardUpdatefalsefalsefalseobjName=“” opName=“setSsdSetCardinality”
38dsdAddfalsefalsefalseobjName=“” opName=“createDsdSet”
39dsdUpdatefalsefalsefalseobjName=“” opName=“updateDsdSet”
40dsdAddMemberfalsefalsefalseobjName=“” opName=“addDsdRoleMember”
41dsdDelMemberfalsefalsefalseobjName=“” opName=“deleteDsdRoleMember”
42dsdDeletefalsefalsefalseobjName=“” opName=“deleteDsdSet”
43dsdCardUpdatefalsefalsefalseobjName=“” opName=“setDsdSetCardinality”
44addPermissionAttributeSetfalsefalsefalseobjName=“” opName=“addPermissionAttributeSet”
45deletePermissionAttributeSetfalsefalsefalseobjName=“” opName=“deletePermissionAttributeSet”
46addPermissionAttributeToSetfalsefalsefalseobjName=“” opName=“addPermissionAttributeToSet”
47permReadfalsefalsefalseobjName=“” opName=“readPermission”
48objReadfalsefalsefalseobjName=“” opName=“readPermObj”
49permSearchfalsefalsefalseobjName=“” opName=“findPermissions”
50objSearchfalsefalsefalseobjName=“” opName=“findPermObjs”
51permObjSearchfalsefalsefalseobjName=“” opName=“findPermsByObj”
52roleReadfalsefalsefalseobjName=“” opName=“readRole”
53roleSearchfalsefalsefalseobjName=“” opName=“findRoles”
54userReadfalsefalsefalseobjName=“” opName=“readUser”
55userSearchfalsefalsefalseobjName=“” opName=“findUsers”
56userAsignedfalsefalsefalseobjName=“” opName=“assignedUsers”
57roleAsignedfalsefalsefalseobjName=“” opName=“assignedRoles”
58roleAuthzedfalsefalsefalseobjName=“” opName=“authorizedRoles”
59userAuthzedfalsefalsefalseobjName=“” opName=“authorizedUsers”
60rolePermsfalsefalsefalseobjName=“” opName=“rolePermissions”
61userPermsfalsefalsefalseobjName=“” opName=“userPermissions”
62permRolesfalsefalsefalseobjName=“” opName=“permissionRoles”
63permRolesAuthzedfalsefalsefalseobjName=“” opName=“authorizedPermissionRoles”
64permUsersfalsefalsefalseobjName=“” opName=“permissionUsers”
65permUsersAuthzedfalsefalsefalseobjName=“” opName=“authorizedPermissionUsers”
66ssdRoleSetsfalsefalsefalseobjName=“” opName=“ssdRoleSets”
67ssdReadfalsefalsefalseobjName=“” opName=“ssdRoleSet”
68ssdRolesfalsefalsefalseobjName=“” opName=“ssdRoleSetRoles”
69ssdCardfalsefalsefalseobjName=“” opName=“ssdRoleSetCardinality”
70dsdRoleSetsfalsefalsefalseobjName=“” opName=“dsdRoleSets”
71dsdSetsfalsefalsefalseobjName=“” opName=“ssdSets”
72dsdReadfalsefalsefalseobjName=“” opName=“dsdRoleSet”
73dsdRolesfalsefalsefalseobjName=“” opName=“dsdRoleSetRoles”
74dsdCardfalsefalsefalseobjName=“” opName=“dsdRoleSetCardinality”
75dsdSetsfalsefalsefalseobjName=“” opName=“dsdSets”
76readPermAttributeSetfalsefalsefalseobjName=“” opName=“readPermAttributeSet”
77findRoleConstraintsfalsefalsefalseobjName=“” opName=“findRoleConstraints”
78arleAddfalsefalsefalseobjName=“” opName=“addRole”
79arleDeletefalsefalsefalseobjName=“” opName=“deleteRole”
80arleUpdatefalsefalsefalseobjName=“” opName=“updateRole”
81adminAssignfalsefalsefalseobjName=“” opName=“assignUser”
82adminDeassignfalsefalsefalseobjName=“” opName=“deassignUser”
83orgAddfalsefalsefalseobjName=“” opName=“addOU”
84orgUpdatefalsefalsefalseobjName=“” opName=“updateOU”
85orgDeletefalsefalsefalseobjName=“” opName=“deleteOU”
86orgDescendantfalsefalsefalseobjName=“” opName=“addDescendantOU”
87orgAscendentfalsefalsefalseobjName=“” opName=“addAscendantOU”
88orgAddinheritfalsefalsefalseobjName=“” opName=“addInheritanceOU”
89orgDelinheritfalsefalsefalseobjName=“” opName=“deleteInheritanceOU”
90arleDescendantfalsefalsefalseobjName=“” opName=“addDescendantRole”
91arleAscendentfalsefalsefalseobjName=“” opName=“addAscendantRole”
92arleAddinheritfalsefalsefalseobjName=“” opName=“addInheritanceRole”
93arleDelinheritfalsefalsefalseobjName=“” opName=“deleteInheritanceRole”
94arleReadfalsefalsefalseobjName=“” opName=“readRole”
95arleSearchfalsefalsefalseobjName=“” opName=“findRoles”
96arleAsignedfalsefalsefalseobjName=“” opName=“assignedRoles”
97userAsignedAdminfalsefalsefalseobjName=“” opName=“assignedUsers”
98orgReadfalsefalsefalseobjName=“” opName=“readOU”
99orgSearchfalsefalsefalseobjName=“” opName=“searchOU”
100groupAddfalsefalsefalseobjName=“” opName=“add”
101groupUpdatefalsefalsefalseobjName=“” opName=“update”
102groupDeletefalsefalsefalseobjName=“” opName=“delete”
103groupAsgnfalsefalsefalseobjName=“” opName=“assign”
104groupDeasgnfalsefalsefalseobjName=“” opName=“deassign”
105groupReadfalsefalsefalseobjName=“” opName=“read”
106roleGroupAsignedfalsefalsefalseobjName=“” opName=“groupRoles”
107groupAsignedfalsefalsefalseobjName=“” opName=“roleGroups”
108pswdAddfalsefalsefalseobjName=“” opName=“add”
109pswdUpdatefalsefalsefalseobjName=“” opName=“update”
110pswdDeletefalsefalsefalseobjName=“” opName=“delete”
111pswdUserAddfalsefalsefalseobjName=“” opName=“updateUserPolicy”
112pswdUserDeletefalsefalsefalseobjName=“” opName=“deletePasswordPolicy”
113pswdSearchfalsefalsefalseobjName=“” opName=“search”
114pswdReadfalsefalsefalseobjName=“” opName=“read”
115auditBindsfalsefalsefalseobjName=“” opName=“searchBinds”
116auditAuthzsfalsefalsefalseobjName=“” opName=“searchAuthZs”
117auditUserAuthzsfalsefalsefalseobjName=“” opName=“getUserAuthZs”
118auditSessionsfalsefalsefalseobjName=“” opName=“searchUserSessions”
119auditModsfalsefalsefalseobjName=“” opName=“searchAdminMods”
120auditInvldfalsefalsefalseobjName=“” opName=“searchInvalidUsers”