4. Troubleshooting#

4.1. Introduction#

This chapter provides a guide to troubleshooting the Univention Guardian. It assumes that you have a basic understanding of the Guardian and its components, as well as familiarity with command-line tools like Docker.

4.2. Common issues#

Before attempting any other solutions, please follow these steps:

  1. Restart all Guardian services.

  2. Check connectivity between the Guardian components.

Here are some examples of how to do this:

Listing 4.1 Check the connectivity between the Management API and the Authorization API#
 univention-app shell guardian-authorization-api
 apt update; apt install -y curl
 curl $GUARDIAN__MANAGEMENT__ADAPTER__AUTHORIZATION_API_URL/openapi.json -I
 # check for 200 OK

  • Connectivity OPA -> Management API:

Listing 4.2 Check the connectivity between the OPA and the Management API#
 univention-app shell -s opa guardian-authorization-api
 apt update; apt install -y curl
 # check connection to management API
 curl -I $OPA_GUARDIAN_MANAGEMENT_URL/openapi.json # check for 200 OK
 # check if the bundle can be retrieved
 curl -I $OPA_GUARDIAN_MANAGEMENT_URL/$OPA_POLICY_BUNDLE # check for 200 OK

  • Connectivity UI -> Management API: Use the developer tools in your browser to check the network tab for errors.

If any of these steps fail, there could be several reasons:

  1. The Guardian component that you’re trying to reach might not be running or couldn’t start properly. Check the logs of the component and restart it if necessary.

  2. The Guardian component that you’re trying to reach is running but not reachable from the component you’re currently on. This could be due to faulty configuration or connectivity problems. Check the environment variables inside the container with the command env and check the connectivity between the containers with the command ping.

  3. The Guardian component that you’re trying to reach is running and reachable but doesn’t respond to the request. This could be the case if the Management API is indeed running but the OPA bundle is not generated. Check the logs of the component and restart it if necessary.

4.3. First time installation and configuration#

Make sure that you complete all steps of the configuration process. Services might not work properly if the configuration is not complete.

4.4. Management UI#

If the Guardian UI loads but with an error, check the network and console tabs of your browser’s developer tools. There you can see if the UI could connect to the Management API and if the Management API responded with an error. If the Management API responded with an error, check the logs of the Management API.

4.5. Management API#

4.5.1. Not authorized to access the Authorization API#

If in the Management API logs you see the following error: ERROR | Unsuccessful response from the Authorization API: {'Detail': 'Not Authorized'}, then the Management API could not authorize itself to the Authorization API. For more information, check the logs of the Authorization API. This can happen if the client secret is not configured for the Management API or is wrong.

4.6. Debugging OPA decisions#

The OPA decisions can’t be easily debugged at the moment. However, there are some ways to make sure everything is working as expected:

  1. OPA fetches the bundle from the Management API. The bundle contains the policies and the data that OPA needs to make decisions. The bundle is generated by the Management API from its database.

  2. If OPA cannot fetch the bundle, it will show it in its logs. Whenever there’s an update in the Management API, the bundle is regenerated and OPA will fetch it again and log it.

  3. To inspect the contents of the bundle, use the following commands:

    Listing 4.3 Inspect OPA bundle contents#
    univention-app shell guardian-management-api
apt update; apt install -y jq
jq '.' /guardian_service_dir/bundle_server/build/GuardianDataBundle/guardian/mapping/data.json

    There you can see what permissions get assigned to which roles under which conditions.

4.7. Authentication issues#

If you cannot log in to the Guardian UI or to any of the Swagger UIs for the Management API or the Authorization API, make sure that the Keycloak server is reachable. You can check the logs of the Keycloak container with the following command:

Listing 4.4 Check Keycloak logs#
univention-app logs keycloak

The most common issues are invalid redirect URLs and clock issues.

For the redirect URL, make sure that the URL is correct. You can check the configuration of the Keycloak server at the following URL: https://ucs-sso-ng.school.test/admin/master/console/#/ucs/clients. Make sure that the redirect URL matches the URL of the Guardian UI for the guardian-ui client, including the scheme (e.g., https://).

For clock issues, a small difference between the clock of the Keycloak server and the clock of the Management API or the Authorization API can cause authentication issues. If this is the case, you will see it in the logs of the Management API or the Authorization API. Look for: WARNING | Invalid Token: "The token is not yet valid (iat)".