Securing Your Application via Roles

The Platform manages and maintains Roles and Role membership for a Tenant and its Users at the Platform level. The Account Administrator (or someone with appropriate permission) can define permissions to secured functionality via Apprenda’s Role system on a per-application basis.

To take advantage of this capability, an application must have at least Multi-tenancy enabled as its Application Service level and include Securables in its definition. Developers use the Apprenda Guest App API to inquire whether or not a User (via their Role membership) can access certain application functionality. The Tenant can define permissions by specifying which Role membership is required to use a certain application functionality denoted by the Securable name and description.

Role Membership in Apprenda

Roles can contain Users as well as other Roles. There is no restriction to how many Roles a User or Role may belong to. When a permissions query occurs against the API, Apprenda checks the current User’s Role membership and compares it to the Role-Securable mappings defined by the Tenant. User Role membership is ancestry-inclusive:

In the diagram, User A is considered a member of both the ‘Marketing Managers’ and ‘Managers’ but not of ‘R&D Managers.’ If a Tenant mapped the role ‘Managers’ to an application’s Securables, all of A,B, & C would be allowed access since the authorization system would show them both to be managers on a membership query.

The Apprenda Account Portal is used to specify this membership. See the Using the Account Portal topic for additional information.

Checking Access to a Securable for .NET Applications

The .NET Guest App API offers Developers two methods to check Securable access:

  • When entering a WCF service call
  • Explicit checking via the Apprenda API

The following example illustrates how to check for permission prior to entering a WCF web service call:

C# Example – Securing via Attributes

[Secured("Scheduling Actions")]
public DeliveryReceipt ScheduleDelivery(DeliveryRequest request)
   if (null == request.DeliveryLocation)
      ITenantProfile profile = TenantContext.Current.GetCompanyProfile();
      request.DeliveryLocation = profile.PrimaryLocation;
   return request.Schedule();

Note that, via the attribute declaration, only calls coming from a service client are controlled; if one service method were to call another that was marked with ‘Secured’, the called method would not adhere to access control expectations. It is important to use attribute declarations if an application anticipates that the service method will only receive calls from service clients and not from within the same service itself.

The following example illustrates how to check for permission via the API:

C# Example – Authorization Query via API Call

public void CloseMarketingCampaign(Guid campaignId)
   ICampaign campaign = CampaignRepository.Instance.Get(campaignId);
   if (UserContext.Instance.IsAuthorized("Send Email"))

Checking Access to a Securable for Java Applications

A Securable can either be defined statically in application configuration (Static Securable), or created at runtime (Runtime Securable).

import com.apprenda.guest.api.ApprendaGuestApp;
import com.apprenda.guest.api.GuestAppContext;
import com.apprenda.guest.access.Securable;
import com.apprenda.guest.api.AppVersion;

// in your code
GuestAppContext guestCtx = ApprendaGuestApp.getContext();
if (guestCtx.isAuthorizationEnabled()) {
    AppVersion appVersion = guestCtx.getAppVersion();
    Iterable<Securable> runtimeSecurables = appVersion.getRuntimeSecurables();
    Iterable<Securable> staticSecurables = appVersion.getStaticSecurables();

Once the application has access to a Securable (Static or Dynamic), it can check if the User has access to the Securable. Further information can be found in the API docs for AppVersion.

// check if the current user has access to the "Manage Users" securable
GuestAppContext guestCtx = ApprendaGuestApp.getContext();
if (guestCtx.isAuthorizationEnabled()) {
    AppVersion appVersion = guestCtx.getAppVersion();
    // check if the current user has access to the "Manage Users" static securable
    appVersion.hasAccessToStatic("Manage Users");
    // check if the user has access to the dynamic securable "SecretDocument 6.0.0"
    appVersion.hasAccessToDynamic("SecretDocument 6.0.0");

The application can retrieve the set of Roles of the Tenant and the set of Roles for a given User. The application is also able to search for Users in the given Tenant based on the fields and the search string.

GuestAppContext guestCtx = ApprendaGuestApp.getContext();
User currUser = guestCtx.getUser();
Tenant currTenant = guestCtx.getTenant();
// these are all roles defined for the tenant
Iterable<Role> tenantRoles = currTenant.getTenantRoles();
// let's see the roles of the current user
Iterable<Role> userRoles = currTenant.getUserRoles(currUser.getId());
// let's get the first  many gmail users we have
String searchString = ""
List<UserSearchColumn> searchFields = new ArrayList<UserSearchColumn>();
searchFields .add(UserSearchColumn.Email);
PagedResult<? extends User> userSearchPage = currTenant.searchUsers(searchString , searchFields , new PagingParams(1,10));
// now, iterate over the list of users and look at their names
User firstUser = userSearchPage.iterator().next();