Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
356 lines (299 sloc) 38.5 KB

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


  • Consists of three tiers: 1. Client, 2. Servlet Container hosting FortressRest, and 3. DirectoryServer that stores the policy information.
  • The Client is any HTTP interface that supports the Apache Fortress message formats.
  • FortressRest is a web application archive (.war) that deploys into a Servlet Container, i.e. Apache Tomcat.
  • FortressCore is a set of APIs that get embedded inside of Java apps (like FortressRest).
  • DirectoryServer is a process implementing LDAPv3 protocols, e.g. ApacheDS or OpenLDAP.

High-level Security Flow

  • The user credentials are introduced into the call chain by the Client as a standard HTTP basic auth header.
  • Passed into the Servlet Container for authentication and coarse-grained authorization before dispatch to FortressRest.
  • Medium-grained authorization performed inside FortressRest as the service dispatches.
  • Finally, if ARBAC enabled (more later), the credentials are converted to an RBAC session and passed into the FortressCore for fine-grained checks.

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

  • FortressRest 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 type fortress-rest-super-user fortress-rest-admin-user fortress-rest-review-user fortress-rest-access-user fortress-rest-deladmin-user fortress-rest-delreview-user fortress-rest-delaccess-user fortress-rest-pwmgr-user fortress-rest-audit-user fortress-rest-config-user
Admin Manager true true false false false false false false false false
Review Manager true false true false false false false false false false
Access Manager true false false true false false false false false false
Delegated Admin true false false false true false false false false false
Delegated Review true false false false false true false false false false
Delegated Access true false false false false false true false false false
Password Manager true false false false false false false true false false
Audit Manager true false false false false false false false true false
Config Manager true false false false false false false false false true
  • 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 FortressRest by default, to enable, add the following declaration to the


a. When enabled, all service invocations perform an ADMIN permission verification 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.

# Services UserOU Check PermOU Check Role Range Check ADMIN Permissions
1 userAdd true false false objName="" opName="addUser"
2 userUpdate true false false objName="" opName="updateUser"
3 userDelete true false false objName="" opName="deleteUser"
4 userDisable true false false objName="" opName="disableUser"
5 userChange true false false objName="" opName="changePassword"
6 userReset true false false objName="" opName="resetPassword"
7 userLock true false false objName="" opName="lockUserAccount"
8 userUnlock true false false objName="" opName="unlockUserAccount"
9 roleAsgn true false true objName="" opName="assignUser"
10 roleDeasgn true false true objName="" opName="deassignUser"
11 roleGrant false true true objName="" opName="grantPermission"
12 roleRevoke false true true objName="" opName="revokePermission"
13 roleAdd false false false objName="" opName="addRole"
14 roleDelete false false false objName="" opName="deleteRole"
15 roleUpdate false false false objName="" opName="updateRole"
16 addRoleConstraint false false false objName="" opName="addRoleConstraint"
17 removeRoleConstraint false false false objName="" opName="removeRoleConstraint"
18 roleEnableConstraint false false false objName="" opName="enableRoleConstraint"
19 roleDisableConstraint false false false objName="" opName="disableRoleConstraint"
20 permAdd false false false objName="" opName="addPermission"
21 objAdd false false false objName="" opName="addPermObj"
22 permDelete false false false objName="" opName="deletePermission"
23 objDelete false false false objName="" opName="deletePermObj"
24 permUpdate false false false objName="" opName="updatePermission"
25 objUpdate false false false objName="" opName="updatePermObj"
26 userGrant false false false objName="" opName="grantPermissionUser"
27 userRevoke false false false objName="" opName="revokePermissionUser"
28 roleDescendant false false false objName="" opName="addDescendant"
29 roleAscendent false false false objName="" opName="addAscendant"
30 roleAddinherit false false false objName="" opName="addInheritance"
31 roleDelinherit false false false objName="" opName="deleteInheritance"
32 ssdAdd false false false objName="" opName="createSsdSet"
33 ssdUpdate false false false objName="" opName="updateSsdSet"
34 ssdAddMember false false false objName="" opName="addSsdRoleMember"
35 ssdDelMember false false false objName="" opName="deleteSsdRoleMember"
36 ssdDelete false false false objName="" opName="deleteSsdSet"
37 ssdCardUpdate false false false objName="" opName="setSsdSetCardinality"
38 dsdAdd false false false objName="" opName="createDsdSet"
39 dsdUpdate false false false objName="" opName="updateDsdSet"
40 dsdAddMember false false false objName="" opName="addDsdRoleMember"
41 dsdDelMember false false false objName="" opName="deleteDsdRoleMember"
42 dsdDelete false false false objName="" opName="deleteDsdSet"
43 dsdCardUpdate false false false objName="" opName="setDsdSetCardinality"
44 addPermissionAttributeSet false false false objName="" opName="addPermissionAttributeSet"
45 deletePermissionAttributeSet false false false objName="" opName="deletePermissionAttributeSet"
46 addPermissionAttributeToSet false false false objName="" opName="addPermissionAttributeToSet"
47 permRead false false false objName="" opName="readPermission"
48 objRead false false false objName="" opName="readPermObj"
49 permSearch false false false objName="" opName="findPermissions"
50 objSearch false false false objName="" opName="findPermObjs"
51 permObjSearch false false false objName="" opName="findPermsByObj"
52 roleRead false false false objName="" opName="readRole"
53 roleSearch false false false objName="" opName="findRoles"
54 userRead false false false objName="" opName="readUser"
55 userSearch false false false objName="" opName="findUsers"
56 userAsigned false false false objName="" opName="assignedUsers"
57 roleAsigned false false false objName="" opName="assignedRoles"
58 roleAuthzed false false false objName="" opName="authorizedRoles"
59 userAuthzed false false false objName="" opName="authorizedUsers"
60 rolePerms false false false objName="" opName="rolePermissions"
61 userPerms false false false objName="" opName="userPermissions"
62 permRoles false false false objName="" opName="permissionRoles"
63 permRolesAuthzed false false false objName="" opName="authorizedPermissionRoles"
64 permUsers false false false objName="" opName="permissionUsers"
65 permUsersAuthzed false false false objName="" opName="authorizedPermissionUsers"
66 ssdRoleSets false false false objName="" opName="ssdRoleSets"
67 ssdRead false false false objName="" opName="ssdRoleSet"
68 ssdRoles false false false objName="" opName="ssdRoleSetRoles"
69 ssdCard false false false objName="" opName="ssdRoleSetCardinality"
70 dsdRoleSets false false false objName="" opName="dsdRoleSets"
71 dsdSets false false false objName="" opName="ssdSets"
72 dsdRead false false false objName="" opName="dsdRoleSet"
73 dsdRoles false false false objName="" opName="dsdRoleSetRoles"
74 dsdCard false false false objName="" opName="dsdRoleSetCardinality"
75 dsdSets false false false objName="" opName="dsdSets"
76 readPermAttributeSet false false false objName="" opName="readPermAttributeSet"
77 findRoleConstraints false false false objName="" opName="findRoleConstraints"
78 arleAdd false false false objName="" opName="addRole"
79 arleDelete false false false objName="" opName="deleteRole"
80 arleUpdate false false false objName="" opName="updateRole"
81 adminAssign false false false objName="" opName="assignUser"
82 adminDeassign false false false objName="" opName="deassignUser"
83 orgAdd false false false objName="" opName="addOU"
84 orgUpdate false false false objName="" opName="updateOU"
85 orgDelete false false false objName="" opName="deleteOU"
86 orgDescendant false false false objName="" opName="addDescendantOU"
87 orgAscendent false false false objName="" opName="addAscendantOU"
88 orgAddinherit false false false objName="" opName="addInheritanceOU"
89 orgDelinherit false false false objName="" opName="deleteInheritanceOU"
90 arleDescendant false false false objName="" opName="addDescendantRole"
91 arleAscendent false false false objName="" opName="addAscendantRole"
92 arleAddinherit false false false objName="" opName="addInheritanceRole"
93 arleDelinherit false false false objName="" opName="deleteInheritanceRole"
94 arleRead false false false objName="" opName="readRole"
95 arleSearch false false false objName="" opName="findRoles"
96 arleAsigned false false false objName="" opName="assignedRoles"
97 userAsignedAdmin false false false objName="" opName="assignedUsers"
98 orgRead false false false objName="" opName="readOU"
99 orgSearch false false false objName="" opName="searchOU"
100 groupAdd false false false objName="" opName="add"
101 groupUpdate false false false objName="" opName="update"
102 groupDelete false false false objName="" opName="delete"
103 groupAsgn false false false objName="" opName="assign"
104 groupDeasgn false false false objName="" opName="deassign"
105 groupRead false false false objName="" opName="read"
106 roleGroupAsigned false false false objName="" opName="groupRoles"
107 groupAsigned false false false objName="" opName="roleGroups"
108 pswdAdd false false false objName="" opName="add"
109 pswdUpdate false false false objName="" opName="update"
110 pswdDelete false false false objName="" opName="delete"
111 pswdUserAdd false false false objName="" opName="updateUserPolicy"
112 pswdUserDelete false false false objName="" opName="deletePasswordPolicy"
113 pswdSearch false false false objName="" opName="search"
114 pswdRead false false false objName="" opName="read"
115 auditBinds false false false objName="" opName="searchBinds"
116 auditAuthzs false false false objName="" opName="searchAuthZs"
117 auditUserAuthzs false false false objName="" opName="getUserAuthZs"
118 auditSessions false false false objName="" opName="searchUserSessions"
119 auditMods false false false objName="" opName="searchAdminMods"
120 auditInvld false false false objName="" opName="searchInvalidUsers"
false false false


You can’t perform that action at this time.