Modules and Functionality

In this section, a more detailed description of the modules and functions in Authway is provided. We will also attempt to clarify factors to consider when defining the modules and functions needed.

Functions

A function is the smallest component to which permissions can be assigned and, therefore, is the one checked in the code to determine whether the user has the necessary permissions or not. A function should be very stable over time, essentially coming into existence when new functionality is developed and being removed simultaneously when the functionality is removed from the system. The determination of necessary functions is thus guided by the business requirements regarding which parts of the system users need to be able to assign different permissions to.

This also means that a function can vary widely in scope even within the same module/system. For some systems, only a single function representing the entire system is needed, but a more common starting point is to create one function per user interface view or per API. Often, it may be necessary to differentiate between the ability to read information in a view and the ability to manage the information. Examples of functions in Authway include, for instance:

  • Read user
  • Manage user
  • Read groups
  • Manage groups

Sometimes, the act of removal can be more sensitive than adding or modifying information. In such cases, additional functionality may be required, for example:

  • Manage organization (owner)
  • Remove organization (owner)

Within a view, there can also be other types of functions that are more sensitive. An example could be a search function that displays personal information, and if you add the capability to export the search results, it becomes more sensitive as it poses a risk of mishandling personal data. In such a scenario, one might consider having the following functions:

  • Search individuals
  • Export individuals

Another aspect that can impact the definition of functions is whether there are business rules associated with the organization. It is important to avoid moving business rules into Authway, as they belong in the system that has the rule. However, these rules may still need to influence which functions are defined. This is quite common in multi-tenant systems but also in other systems where organizational affiliation can play a significant role. An example could be the ability to administer properties in a real estate company, where a property manager has the right to update information about the properties they are responsible for, but not others. In this case, you might have functions like:

  • Manage my properties
  • Manage all properties

The definition of what “my” means is not specified here, as those rules exist in the business system. During organizational changes, these rules should only need to be updated in the business system, while the functions remain unchanged in Authway (possibly with the exception that you might want to update the description).

Administer functions

When creating functions, you give them a user-friendly name that is displayed in the administration interface, such as in group management. In the “Authorization” field, you specify the string against which the code verifies the permission, and this string must be unique. We recommend using the [Module].[Function] naming convention, for example, Security.ReadUser and Security.ManageUser. It’s also a good practice to create a constant in the code for each permission so that the string is defined in only one place.

A well-written description can help administrators understand the purpose of the function.

Functions that require owner permission must be saved first before adding owners who should have access. This is because the owner is granted access directly but after a check that the function requires owner permission. It also means that when assigning owner permission, you can press “Cancel” to close the dialog, provided no other changes that need saving have been made.

Owner-specific functions

In a multi-tenant system, there is sometimes a need to restrict access to a function to one or more specific owners. This could be for advanced features where there’s a need to view information from other owners, such as in a support organization. It could also involve a customer-specific report that belongs to the Report module.

If there are many functions that need to be specific to owners, it might be advisable to place them in a separate module, as modules are also assigned for each new owner.

The target audience for a function?

Often, the functions that a system contains are available both in a user interface and in an API, meaning that it is reasonable for both users and other systems to have access. However, there are functions that are clearly targeted either at users or systems. An example could be the ability to read an event stream for systems built on events. This is likely to be completely incomprehensible for users and practically never something a user would want to do, but another system is highly likely to need this capability. In Authway, it is possible to restrict where in the administration interface the functions are displayed by selecting a target audience.

Modules

Modules are a grouping of functions that are logically related in some way. A module can correspond to a system, but it is not uncommon to choose to divide a system into several modules. Here are some factors to consider when deciding to create modules:

  • If there are different target audiences (e.g., internal users and external users), it may be a good reason to place functions in different modules.
  • If there are specific owners who should have access to the functions, but there are still quite a few functions that are the same for these different owners, grouping these functions into a separate module may also be a good reason.
  • A module can be set to online/offline during deployments, so it’s often appropriate for modules to match the unit being deployed.
  • An API scope can only correspond to one module, meaning that if you want to require different scopes for calls to different APIs, these probably should be divided into separate modules.