5. Management UI#

This chapter is geared towards Guardian administrators who want to manage roles and related objects which can grant permissions to users.

The Guardian Management UI app provides a web interface to manage some of the features of the REST API of the Guardian Management API app. The following sections describe which functions can be performed with the web interface.

You can access the Guardian Management UI under https://[Domainname]/univention/guardian/management-ui for the Domainname where the Guardian Management UI app is installed. When installing the app, a portal entry is created in the Administration category of the default domain portal (cn=domain,cn=portal,cn=portals,cn=univention,$ldap_base). With the default configuration, a user who wants to use the Guardian Management UI as a guardian admin needs the role guardian:builtin:super-admin.

For a detailed explanation on what roles, capabilities, namespaces and contexts are, refer to the section about terminology.

5.1. General remarks#

After you entered the Guardian Management UI, you will see a navigation bar with the entries ROLES, NAMESPACES and CONTEXTS, a search bar with filters and a table.

_images/front_page.png

Fig. 5.1 The front page of the Guardian Management UI.#

There are some differences, but you can view and manage the object types role, namespace, and context by navigating between them with the navigation bar as described in the following sections. The management of capabilities is done while editing a role.

Note

The apps in the App box can only be managed via the REST API provided by the Guardian Management API app. Refer to the developer quick start documentation if you need to integrate an app with the Guardian.

In the search view for one of the object types, you can filter by app and namespace, with the exception of namespaces themselves, which can only be filtered by app.

Note

At the moment it is not possible to include properties of an object, such as its Display Name, in the search criteria.

5.2. Roles#

The Guardian Management UI can be used to manage roles. A role contains capabilities and is defined within the scope of an app and a namespace. From the role and its capabilities, permissions are derived. For more information about the fundamental concepts, refer to the section about terminology.

5.2.1. Create a new role#

To create a new role first open the Guardian Management UI and click on ROLES in the navigation menu.

_images/click_on_roles_button.png

Fig. 5.2 Link to the roles page.#

Then click on the + ADD button to open the page to create a new role.

_images/click_on_add_roles_button.png

Fig. 5.3 Click + ADD to create a new role.#

The page to create a new role looks like this:

_images/create_role_page.png

Fig. 5.4 Page to create a new role.#

Fill out all the necessary fields and click on the CREATE ROLE button to create the role. A pop-up will be shown which confirms the creation by displaying the role name.

Note

The selectable options for the Namespace box depend on the selected app in the App box. You have to select an app first before you can select a namespace. If you selected an app and still don’t see any selectable namespaces that means that there are no namespaces for that app. Refer to the section about creating namespaces.

Note

Capabilities for a role can only be managed on existing roles. To add capabilities to the role you are currently creating first create the role with the CREATE ROLE button and then manage capabilities as described in Capabilities of a role.

5.2.2. Listing and searching roles#

To list existing roles open the “Guardian Management UI” and click on ROLES in the navigation menu.

_images/click_on_role.png

Fig. 5.5 Link to the “Roles” page.#

On this page you can search for existing roles by clicking the SEARCH button. The results will be shown below that button. The search can be narrowed down by selecting a specific app in the App box, and a namespace of the selected app in the Namespace box.

_images/search_and_list_roles.png

Fig. 5.6 Form elements for the search of roles.#

Note

The namespaces for the Namespace box can be managed as described in Namespaces.

5.2.3. Editing existing roles#

To edit a role, follow the steps in Listing and searching roles to list them and then click on the name of the role you want to edit.

_images/click_on_role.png

Fig. 5.7 Edit button for listed roles.#

The role editing is split into two pages.

The first page is to edit the direct properties of the role and is the first page you see when opening a role. This page can be accessed by clicking ROLE in the navigation menu. Here you can edit the fields you want to change and click on SAVE to save the changes.

_images/click_on_save_role.png

Fig. 5.8 View and edit page of an existing role.#

The second page is to manage the capabilities of the current role. This page can be visited by clicking on CAPABILITES in the navigation menu.

_images/list_capabilities.png

Fig. 5.9 Link to the “Capabilities” page of an existing role.#

Here you can list all capabilities of the role you are currently editing and manage them. You can also create new capabilities for that role or delete existing ones. For more details on capabilities see the section: Capabilities of a role.

5.2.4. Deleting roles#

Deleting roles is not possible at the moment. Neither through the web-interface nor the REST API.

5.3. Capabilities of a role#

Capabilities serve as the means to manage the permissions the role will grant to the user it is attached to.

Each capability object can define one ore more permissions it will grant. These permissions can only be selected for a specific app and namespace. If you want to grant permissions for different apps and/or namespaces you have to create multiple capability objects.

Inside an capability object you can also add conditions that influence whether the permissions are actually granted.

The capabilities work on a whitelist principle and do not collide.

Note

Capabilities can only be managed on existing roles.

If you are creating a new role and want to manage its capabilities, first create the role and then edit the role to manage its capabilities.

5.3.1. Create new capability for a role#

To add a capability for a role, first click on CAPABILITES in the navigation menu while editing a role. See Editing existing roles for more details on editing a role.

Then click on the + ADD button to open the page to create a new capability.

_images/click_on_add_capabilities_button.png

Fig. 5.10 Click + ADD to create a new capability.#

The page to create a new capability looks like this:

_images/create_new_capability.png

Fig. 5.11 Page to create a new capability.#

To create the capability fill out all the necessary fields and then click the CREATE CAPABILITY button. A pop-up will be shown which confirms the creation by displaying the capability name.

Three noteworthy fields are the list of Permissions, the list of Conditions and the Relation.

Permissions

In the Permissions list you can edit all permissions the capability will grant if the conditions in the Conditions list are met. The available permissions are based on the selected app in the App box and namespace in the Namespace box. You cannot select any permissions before filling out both of these fields.

Note

If both the App box and Namespace box are filled out, and you still cannot select permissions, this means that no permissions exist for that app and namespace.

Conditions

In the Conditions list you can edit all the conditions that should be checked before the permissions in the Permissions list are granted. Some conditions require additional parameters. You can look up more about these conditions in chapter Conditions Reference. Additional fields will be shown underneath them once selected.

_images/conditions_list.png

Fig. 5.12 Condition with extra parameters.#

Note

See Conditions Reference for an explanation of the pre-existing conditions.

Relation

The value of the Relation box describes how the Guardian Authorization API will check conditions during authorization. AND means all conditions must be met and OR means only 1 condition must be met.

5.3.2. Listing and searching capabilities of a role#

To list capabilities of a role click on CAPABILITES in the navigation menu while editing a role. See Editing existing roles for more details on editing a role.

On this page you can search for capabilities of the role you are currently editing by clicking the SEARCH button. The results will be shown below that button. The search can be narrowed down by selecting a specific app in the App box, and a namespace of the selected app in the Namespace box.

_images/listing_and_searching_capabilities.png

Fig. 5.13 Form elements for the search of capabilities.#

Note

The namespaces for the Namespace box can be managed as described in Namespaces.

5.3.3. Edit a capability of a role#

To edit a capability of a role, follow the steps in Listing and searching capabilities of a role to list them and then click on the name of the capability you want to edit.

_images/click_on_capability.png

Fig. 5.14 Edit button for listed capabilities.#

The page to edit the clicked capability looks like this:

_images/capability_edit_page.png

Fig. 5.15 View and edit page of an existing capability.#

The three noteworthy fields you can edit are the list of Conditions, the Relation and the list of Permissions.

Permissions

In the Permissions list you can edit all permissions the capability will grant if the conditions in the Conditions list are met.

Conditions

In the Conditions list you can edit all the conditions that should be checked before the permissions in the Permissions list are granted. Some conditions require additional parameters. Additional fields will be shown underneath them once selected.

_images/conditions_list.png

Fig. 5.16 Condition with extra parameters.#

Note

See Conditions Reference for an explanation of the pre-existing conditions.

Relation

The value of the Relation box describes in which manner the selected conditions of the Conditions should be checked. AND means all conditions have to be met, OR means only 1 condition has to be met.

5.3.4. Delete capabilities of a role#

To delete capabilities, first click on CAPABILITES in the navigation menu while editing a role. See Editing existing roles for more details on editing a role.

Search and select all the capabilities you want to delete, then click the DELETE button.

_images/delete_capabilities.png

Fig. 5.17 Deletion of capabilities.#

5.4. Namespaces#

A namespace is a means to categorize roles and permissions. With the Guardian Management UI namespaces can be created, edited, searched and viewed. For more information about namespaces refer to the section about Guardian terminology.

5.4.1. Create a new namespace#

To create a new namespace first open the Guardian Management UI and click on NAMESPACES in the navigation menu.

_images/click_on_namespace_button.png

Fig. 5.18 Link to the “Namespaces” page.#

Then click on the + ADD button to open the page to create a new namespace.

_images/click_on_add_namespace_button.png

Fig. 5.19 Click + ADD to create a new namespace.#

The page to create a new namespace looks like this:

_images/create_namespace_page.png

Fig. 5.20 Page to create a new namespace.#

Fill out all the necessary fields and click on the CREATE NAMESPACE button to create the namespace. A pop-up will be shown which confirms the creation by displaying the namespace name.

5.4.2. Listing and searching namespaces#

To list existing namespaces open the Guardian Management UI and click on NAMESPACES in the navigation menu.

_images/click_on_namespace_button.png

Fig. 5.21 Link to the “Namespaces” page.#

On this page you can search for existing namespaces by clicking the SEARCH button. The results will be shown below that button. The search can be narrowed down by selecting a specific app in the App box.

_images/namespace_app_box.png

Fig. 5.22 Form elements for the search of namespaces.#

5.4.3. Editing existing namespaces#

To edit a namespaces, follow the steps in Listing and searching namespaces to list them and then click on the name of the namespace you want to edit.

_images/click_on_namespace.png

Fig. 5.23 Edit button for listed namespaces.#

The page to edit the namespace you clicked looks like this:

_images/namespace_edit_page.png

Fig. 5.24 View and edit page of an existing namespace.#

5.4.4. Deleting namespaces#

Deleting namespaces is not possible at the moment. Neither through the web-interface nor the REST API.

5.5. Contexts#

A context is an additional tag that can be applied to a role, to make it only apply in certain circumstances. With the Guardian Management UI you can create, edit, search and view a context. For more information about contexts refer to the section about Guardian terminology.

5.5.1. Create a new context#

To create a new context first open the Guardian Management UI and click on CONTEXTS in the navigation menu.

_images/click_on_context_button.png

Fig. 5.25 Link to the “Namespaces” page.#

Then click on the ADD button to open the page to create a new context.

_images/click_on_add_context_button.png

Fig. 5.26 Click + ADD to create a new context.#

The page to create a new context looks like this:

_images/create_context_page.png

Fig. 5.27 Page to create a new context.#

Fill out all the necessary fields and click on the CREATE CONTEXT button to create the context. A pop-up will be shown which confirms the creation by displaying the context name.

5.5.2. Listing and searching contexts#

To list existing contexts open the Guardian Management UI and click on CONTEXTS in the navigation menu.

_images/click_on_context_button.png

Fig. 5.28 Link to the “Contexts” page.#

On this page you can search for existing contexts by clicking the SEARCH button. The results will be shown below that button. The search can be narrowed down by selecting a specific app in the App box, and a namespace of the selected app in the Namespace box.

_images/search_filter_context.png

Fig. 5.29 Form elements for the search of contexts.#

Note

The namespaces for the Namespace box can be managed as described in Namespaces.

5.5.3. Editing existing contexts#

To edit a context, follow the steps in Listing and searching contexts to list them and then click on the name of the context you want to edit.

_images/click_on_context.png

Fig. 5.30 Edit button for listed contexts.#

The page to edit the context you clicked looks like this:

_images/context_edit_page.png

Fig. 5.31 View and edit page of an existing context.#

5.5.4. Deleting contexts#

Deleting contexts is not possible at the moment. Neither through the web-interface nor the REST API.