Contribute to help us improve!

Are there edge cases or problems that we didn't consider? Is there a technical pitfall that we should add? Did we miss a comma in a sentence?

If you have any input for us, we would love to hear from you and appreciate every contribution. Our goal is to learn from projects for projects such that nobody has to reinvent the wheel.

Let's collect our experiences together to make room to explore the novel!

To contribute click on Contribute to this page on the toolbar.


Figure 1. Security Model
  • The Identity- and Access-Management is provided by according products and typically already available in the enterprise landscape (e.g. an active directory). It provides a hierarchy of primary access control objects (roles and groups) of a user. An administrator can grant and revoke permissions (indirectly) via this way.

  • The application security defines a hierarchy of secondary access control objects (groups and permissions). This is done by configuration owned by the application (see following section). The "API" is defined by the IDs of the primary access control objects that will be referenced from the Identity- and Access-Management.

Clarification of terms

Security terms related to authorization
Term Meaning and comment


Verification that an authenticated user is allowed to perform the operation he intends to invoke


  • A permission is an object that allows a principal to perform an operation in the system.

  • This permission can be granted (give) or revoked (taken away).


  • A group contains permissions.

  • A group may also contain other groups.


  • A role is as a specific form of group that also contains permissions.

  • A role identifies a specific function of a principal. A user can act in a role.

  • For simple scenarios a principal has a single role associated.

  • In more complex situations a principal can have multiple roles but has only one active role at a time that he can choose out of his assigned roles. For KISS it is sometimes sufficient to avoid this by creating multiple accounts for the few users with multiple roles.

Access Control

Any permission, group, role, etc., which declares a control for access management.

Suggestions on the access model

For the access model we give the following suggestions:

  • Each Access Control (permission, group, role, …​) is uniquely identified by a human readable string.

  • A unique permission is created for each use-case.

  • Groups combine permissions to typical and useful sets for the users.

  • Roles act as specific groups as required by our business demands.

  • Users can be associated with a list of Access Controls.

  • For authorization of an implemented use case the required permissions are determined. A security exception is thrown if the user does not have the required permissions.

  • A user has no permission by default and only those granted to him explicitly give him additional permission for specific things. Permissions granted can not be reduced by other permissions.

  • Permissions are secrets of the application. Administrators shall not fiddle with individual permissions but grant them via groups. So the access management provides a list of strings identifying the Access Controls of a user. The individual application itself contains these Access Controls in a structured way, whereas each group forms a permission tree.

Naming conventions

As stated above each Access Control is uniquely identified by a human readable string. This string should follow the naming convention:


For Access Control Permissions the «local-name» again follows the convention:


The segments are defined by the following table:

Segments of Access Control Permission ID
Segment Description Example


Is a unique technical but human readable string of the application (or microservice). It shall not contain special characters and especially no dot or whitespace. We recommend to use lower-train-case-ascii-syntax. The identity and access management should be organized on enterprise level rather than application level. Therefore permissions of different apps might easily clash (e.g. two apps might both define a group ReadMasterData but some user shall get this group for only one of these two apps). Using the «app-id». prefix is a simple but powerful namespacing concept that allows you to scale and grow. You may also reserve specific «app-id»s for cross-cutting concerns that do not actually reflect a single app e.g to grant access to a geographic region.



The action that is to be performed on «object». Find shall be used for searching and reading data. Save shall be used for create and update. Create should only be used in addition to Save when there’s a concrete demand. Finally, Delete is used for deletions. For non CRUD actions additional verbs such as Approve or Reject can be used.



The affected object or entity. Shall be named according to your data-model


So as an example shop.FindProduct will reflect the permission to search and retrieve a Product in the shop application. The group shop.ReadMasterData may combine all permissions to read master-data from the shop. However, also a group shop.Admin may exist for the Admin role of the shop application. Here the «local-name» is Admin that does not follow the «verb»«object» schema.