2. What is the Guardian?

The Guardian provides an authorization service for apps used with a UCS system. Authorization is the confirmation of a user’s access to some resource, such as the ability to modify a user’s data, export data from a system, or view a web page. It’s important to note that the Guardian itself only informs about the result of an authorization request. The app itself must enforce the result of any authorization.

Note

The Guardian doesn’t provide authentication, that’s the confirmation that a user is who they say they are. You can use Keycloak or another service to have a user sign-in to authenticate, and then use the Guardian to find out what the user can do.

2.1. Guardian apps

The authorization service consists of three applications installed from the UCS App Center:

• Management API

• Authorization API

• Management UI

At a minimum, you must install the Management API and the Authorization API. The Management UI provides an optional graphical user interface for the Management API. For more information, see section Installation.

2.1.1. Management API

The Management API is a REST interface for app developers to configure aspects of the Guardian that their apps need to handle authorization and permissions. Apps should run a join script during installation that accesses the Management API to register with the Guardian and set up all the roles, permissions, and other items that the app needs.

The Management API is for technical audiences, such as app developers. For a more user-friendly interface to manage the Guardian, use the Management UI.

For more information, see the section about the Management API and Authorization API.

2.1.2. Authorization API

The Authorization API is a REST interface that allows apps to verify whether a given user or other actor has access to a resource provided by the app. The Authorization API answers the following questions:

1. Given a user and a target resource, what’s the user allowed to do?

2. Given a user, a target resource, and a proposed user behavior, is the user allowed to do that behavior?

The Authorization API is only for app developers. There is no other more user-friendly interface.

For more information, read the section about the Management API and Authorization API.

2.1.3. Management UI

The Management UI is a user-friendly web interface that allows guardian administrators and guardian app administrators to configure what users on their UCS system can do after an administrators installed an app.

For more information, read the section about the Management UI.

2.2. What does the Guardian do?

This section provides an overview of the behavior of the Guardian. A fictional example illustrates how the Guardian works with each of the three Guardian applications.

Example Organization develops an application, Cake Express, that administrators can install from the Univention App Center. Cake Express allows employees to order cakes for company events. Example Organization wants to give Cake Express administrators some flexibility in who can order cakes, so they update Cake Express so it integrates with the Guardian.

Ariel works for Happy Employees, Inc. in the role of director of IT. When she installs Cake Express on a UCS system, the join script for Cake Express using the Management API does the following:

1. Register Cake Express as an app with the Guardian, using the name cake-express.

2. Create a namespace called cakes which the app uses to store its roles and permissions for managing cakes.

3. In the cakes namespace, create a permission which the app verifies when people order cakes, cake-express:cakes:can-order-cake.

4. Create a role in the cakes namespace to assign to people, cake-express:cakes:cake-orderer.

5. Create a role in the cakes namespace to assign to cakes, cake-express:cakes:birthday-cake.

At the same time, the join script registers Cake Express as an app. The Guardian creates a special role to administer Cake Express, cake-express:default:app-admin. Ariel thinks that a person from the human resources department (HR) manages Cake Express in the Guardian. So she assigns the role cake-express:default:app-admin to the HR manager, Tristan, in UDM.

Tristan can now sign in to the Management UI, where he can see and edit everything related to Cake Express in the Guardian. He decides to create two capabilities:

• Everyone in the HR department has the role happy-employees:departments:hr, so everyone with this role gets the permission cake-express:cakes:can-order-cake.

• Anyone who isn’t in HR but has the role cake-express:cakes:cake-orderer is also allowed to order a cake, but not if it’s a birthday cake with the role cake-express:cakes:birthday-cake, because only HR can order birthday cakes.

Tristan asks Ariel to give Carla, the CEO, the role cake-express:cakes:cake-orderer in UDM. Now Carla can order a cake, even though she’s not in HR.

Carla then signs in to Cake Express, where she tries to order an anniversary cake for Daniel, who has been with the company for 20 years. Cake Express sends information about Carla, including her role, and the name of her department, and the type of cake, to the Authorization API to ask if she has the authorization cake-express:cakes:can-order-cake. The Authorization API verifies the capability that Tristan created and determines that yes, Carla has the role cake-express:cake:cake-orderer and the cake is not a birthday cake, so she is allowed to order a cake.

2.3. Terminology

This section covers some of the terminology used by the Guardian in more detail.

2.3.1. Guardian administrator and Guardian app administrator

Guardian administrator and guardian app administrator are the two kinds of people who can manage the Guardian.

Technical Note

A Guardian administrator has the role guardian:builtin:super-admin. This means that in UCS applications which have UDM integration, the attribute guardianRoles of the user must include this string, for example guardianRoles=guardian:builtin:super-admin. Another option is to add the user to a group which has the attribute guardianMemberRoles set to guardian:builtin:super-admin.

Guardian administrators can manage all aspects of the Guardian and integrated apps, including the following:

• Apps

• Namespaces

• Roles

• Permissions

• Conditions

• Capabilities

• Contexts

A guardian app administrator has the ability to manage a single app that integrates with the Guardian.

Technical Note

The role for an app administrator comes in the format <app-name>:default:app-admin, with the <app-name> replaced by the unique identifier for the app. In the Cake Express example from the previous section, the app administrator for Cake Express has the role cake-express:default:app-admin. In UCS applications that have UDM integration, the user must have the attribute guardianRoles include this string, for example guardianRoles=cake-express:default:app-admin.

Guardian app administrators can manage all of the following aspects of their respective app:

• Namespaces

• Roles

• Permissions

• Conditions

• Capabilities

• Contexts

Important

Even if the permissions granted by the Guardian app administrator role allow to manage all aspects of an app, the Management UI can’t manage permissions and conditions. Only apps can create and manage these types of objects directly during the provisioning process. Within a UCS domain, an app would typically create and manage these object types within the join script.

2.3.2. App

An app is an application installed from Univention App Center, or a third-party service that integrates with a UCS system, that uses the Guardian to determine what an actor can do.

To use the Guardian, apps first must register themselves using the Management API and a unique identifier. In the Cake Express example, the app Cake Express registered itself with the identifier cake-express. Everything in the Guardian that Cake Express uses, starts with this identifier, such as the role cake-express:cakes:can-order-cake.

2.3.3. Actor

An actor is a user or machine account that wants to do something in an app.

In the Cake Express example, the CEO Carla is an actor who wants to order a cake in Cake Express.

The Guardian doesn’t manage actors. It’s the responsibility of the app and app infrastructure maintainers to manage actors.

2.3.4. Target

A target is a resource that the actor wants to access in an app.

In the Cake Express example, when Carla ordered an anniversary cake from Cake Express, the anniversary cake was the target resource.

The Guardian doesn’t manage targets. It’s the responsibility of the app and app infrastructure maintainers to manage targets.

2.3.5. Namespace

A namespace is a convenient categorization within an app for all aspects of the app, such as roles and permissions. For example, an office suite might create an email namespace in which to store roles and permissions related to email.

In the Cake Express example, when Cake Express ran its join script at install time, it created the namespace cakes to store everything else it created. Later, if it wants to add some kind of user management feature, it might also add a namespace called users. Apps also always have the default namespace, which is where the app-admin role for an app always resides.

All objects in the guardian have a namespace. When referring to the role cake-express:cakes:cake-orderer in Cake Express, the namespace is the second field of the role string, cakes.

2.3.6. Role

A role is a string that you assign to a user, group, or other database object, to associate it with a capability, either as an actor or as a target. In a UCS domain this is usually done in UDM and supported for user objects only.

In the Cake Express example, Ariel could assign the role cake-express:cakes:cake-orderer to any person or even a machine account to let that actor order a cake. Cake Express, in its own internal database, might assign the role cake-express:cakes:birthday-cake to distinguish between different kinds of cakes.

A role string always follows the format <app-name>:<namespace-name>:<role-name>`.

For a how-to on assigning roles to users or objects, refer to the chapter about assigning roles to users.

2.3.7. Permission

A permission is an action that an actor can take in an app.

In the Cake Express example, there is a permission cake-express:cakes:can-order-cake, that allows a user to order a cake within the Cake Express app.

Permissions are strings that the code in an app recognizes, and uses to cause something to happen in the app.

Some other examples of fictional permissions include:

cake-express:orders:read-order

Allows a user to read all orders.

cake-express:orders:export-orders

Allows a user to export all orders as a spreadsheet.

cake-express:users:manage-email-notifications

Allows a user to manage the email notifications that users receive from Cake Express.

Important

The Management UI doesn’t have a permissions management interface. Only app developers can manage permissions through the Management API.

While a guardian administrator technically has the ability to create permissions, the app most likely doesn’t recognize the permission and know what to do with it.

A permission is a required component of a capability.

2.3.8. Condition

A condition is a criterion by which a permission applies.

In the Cake Express example, Cake Express might have a permission cake-express:cakes:can-add-candles that applies only if the condition is true that the cake has the role cake-express:default:birthday-cake.

A condition is an optional component of a capability.

Important

The Management UI doesn’t have an interface for managing conditions. Only app developers can manage conditions in the Management API.

While a guardian administrator technically has the ability to create conditions, this requires knowledge of how to write Rego code.

2.3.9. Capability

Capabilities are one of the more complicated aspects of the Guardian to explain, but they’re also the key to how the Authorization API can answer the question of what a user or an other actor can do in an app.

A capability is one or more permissions, optionally combined with one or more conditions that change when the permission applies. A capability is then assigned to a role to determine what an actor with that role can do.

The simplest capability is a single permission. In the Cake Express example, anyone with the role happy-employees:department:hr is assigned a capability with the single permission cake-express:cakes:can-order-cake.

A more complex capability might involve a permission plus a condition. In the Cake Express example, anyone with the role cake-express:cakes:cake-orderer has the permission cake-express:cakes:can-order-cake, provided the condition that the target cake doesn’t have the role cake-express:cakes:birthday-cake.

If there is more than one condition, a relation joins the conditions with Boolean operators, either AND or OR.

AND

With AND, all conditions must be true. The Guardian grants permission to the user if the target doesn’t have the birthday cake role AND the target cake isn’t marked as a “top-tier” style cake.

OR

OR allows any condition to be true. The Guardian grants permission to the user if they placed the cake order OR the cake is an anniversary cake.

2.3.10. Context

A context is an additional tag that the Guardian applies to a role so that it only applies in certain circumstances.

For example, Happy Employees, Inc. has two different offices, London and Berlin. Persons in the offices have the party planner role. Daniel is the party planner for London. Erik is the party planner for Berlin. Example Organization sets up a capability that says a party planner can order a cake, but only for the office context where they’re a party planner. So Erik can’t order a cake for London, and Daniel can’t order a cake for Berlin.

Important

Not all apps support contexts. Validate with the app developer for your app, to see if they support contexts.