1. What is the Guardian?#

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

Note

The Guardian does not provide authentication, confirmation that a user is who they claim to be. You can use Keycloak or another service to have a user log in, i.e., authenticate, and then use the Guardian to find out what the user is allowed to do.

1.1. Guardian apps#

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

At a minimum, you must install the Management API and the Authorization API. The Management UI provides an optional user-friendly graphical interface for the Management API. See the chapter on Installation for more information.

1.1.1. Management API#

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

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

Please read the chapter on the Management API and Authorization API for more information.

1.1.2. Authorization API#

The Authorization API is a REST interface that allows apps to check whether a given user or other actor has access to a resource that the app provides. The API can answer the following questions:

  1. Given a user and a target resource, what is 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?

This API is intended only for app developers. There is no user-friendly interface for the Authorization API.

Please read the chapter on the Management API and Authorization API for more information.

1.1.3. Management UI#

The Management UI is a user-friendly web interface that allows guardian admins and guardian app admins to configure what users in their UCS system are allowed to do once an app has been installed.

Please read the chapter on the Management UI for more information.

1.2. What does the guardian do?#

Here is an example that illustrates how the Guardian works with each of the three Guardian applications:

ACME Corporation develops an application, Cake Express, which can be installed from the UCS App Center, and which allows employees to order cakes for company events. ACME Corporation wants to allow administrators of Cake Express to have some flexibility in who gets to order cakes, so they update Cake Express so it integrates with the Guardian.

Alice works for Happy Employees, Inc. as the head IT person. When she installs Cake Express on a UCS System, the join script for Cake Express does the following using the Management API:

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

  2. Creates a namespace called cakes that the app will use to store its roles and permissions for managing cakes.

  3. Creates a permission in the cakes namespace that the app will check when people try to order cakes, cake-express:cakes:can-order-cake.

  4. Creates a role to assign to people, cake-express:cakes:cake-orderer.

  5. Creates a role 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 manage Cake Express, cake-express:default:app-admin. Alice thinks that managing Cake Express in the Guardian should be done by an HR person, so she assigns the cake-express:default:app-admin role to the HR Manager, Bob, in UDM.

Bob can now log into the Management UI, where he is allowed to 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.

  • For everyone not in the HR department, but who has the role cake-express:cakes:cake-orderer, they are also allowed to order cake, but not if the cake is a birthday cake with the role cake-express:cakes:birthday-cake, because only HR can order birthday cakes.

Bob asks Alice to give the cake-express:cakes:cake-orderer role to Carla, the CEO, in UDM. Now Carla is allowed to order a cake, even though she’s not in the HR department.

Carla then logs into Cake Express, where she tries to order an anniversary cake for Daniel, who has been at 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 permission cake-express:cakes:can-order-cake. The Authorization API checks the capability that Bob created and determines that yes, Carla has the cake-express:cake:cake-orderer role and the cake is not a birthday cake, so she is allowed to order a cake.

1.3. Terminology#

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

1.3.1. Guardian admin and Guardian app admin#

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

Note

Technical Note

A guardian admin has the role guardian:builtin:super-admin. This means that in UCS applications that have UDM integration, the user should have the guardianRole attribute include this string, i.e., guardianRole=guardian:builtin:super-admin.

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

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

Note

Technical Note

The role for an app admin comes in the format <app-name>:default:app-admin, with the <app-name> replaced by the unique identifier for the app. In our Cake Express example above, the app admin for Cake express has the role cake-express:default:app-admin. In UCS applications that have UDM integration, the user should have the guardianRole attribute include this string, e.g., guardianRole=cake-express:default:app-admin.

App admins can manage all of the aspects of their respective app:

Note

Even if the permissions granted by the app admin role allow for all aspects of an app to be administrated, permissions and conditions cannot be managed with the Management UI. These types of object are intended to be created and managed by the apps directly during the provisioning process. Within a UCS domain this would usually happen during the join script.

1.3.2. App#

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

In order to use the Guardian, apps first must register themselves using the Management API and a unique identifier. For example, the Cake Express app registered itself with the identifier cake-express. Everything in the Guardian that is used by Cake Express will start with this identifier, such as the role cake-express:cakes:can-order-cake.

1.3.3. Actor#

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

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

The Guardian does not manage actors. It is the responsibility of the app and app infrastructure maintainers to manage actors.

1.3.4. Target#

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

When Carla ordered an anniversary cake from Cake Express, the anniversary cake was the target resource.

The Guardian does not manage targets. It is the responsibility of the app and app infrastructure maintainers to manage targets.

1.3.5. Namespace#

A namespace is a convenient categorization within an app for all aspects of the app, such as roles and permissions.

When Cake Express ran its join script at installation time, it created a 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 is always located.

All objects in the guardian are namespaced. When referencing the cake-express:cakes:cake-orderer role in Cake Express, the namespace is the second field of the role string, cakes.

1.3.6. Role#

A role is a string that you assign to a user, group, or other database object, in order to associate it with a capability, either as an actor or as a target.

In the Cake Express example, Alice 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>.

The Guardian does not assign roles to users or objects. Instead, an app infrastructure maintainer is responsible for assigning role strings to the guardianRole attribute in UDM, or an app developer must assign roles to objects in their own internal database.

1.3.7. Permission#

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

In Cake Express, 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 are recognized by the code in an app, and used to cause something to happen in the app. Some other examples of fictitious 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 an excel spreadsheet.

  • cake-express:users:manage-email-notifications: Allows a user to manage the email notifications that users receive from Cake Express.

Note

The Management UI does not have an interface to manage permissions. This can only be done in the Management API, and as such should only be managed by app developers.

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

A permission is a required component of a capability.

1.3.8. Condition#

A condition is a criterion under which a permission applies.

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

Note

The Management UI does not have an interface to manage conditions. This can only be done in the Management API, and app developers are most likely to manage them.

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

A condition is an optional component of a capability.

1.3.9. Capability#

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

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

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

A more complex capability might include a permission plus a condition. In the Cake Express example, everyone with the cake-express:cakes:cake-orderer role has the permission cake-express:cakes:can-order-cake, provided the condition that the target cake does not have the role cake-express:cakes:birthday-cake.

If there is more than one condition, the conditions are joined by a relation, either AND or OR. With AND, all conditions must apply: the user gets permissions if the target does not have the birthday cake role AND the target cake is not marked as a “top-tier” style cake. With OR, any condition can apply: the user gets permissions if they made the cake order OR the cake is an anniversary cake.

1.3.10. Context#

A context is an additional tag that can be applied to a role, to make it only apply in certain circumstances.

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

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