6. Management API and Authorization API

Note

This is a highly technical topic, and is primarily geared towards app developers who want to integrate an app with the Guardian. Familiarity with using the command line and working with an HTTP API, is necessary to understand this chapter.

6.1. Introduction

The Management API and Authorization API are the two REST APIs for the Guardian.

Please read the Developer quick start for concrete examples of using the APIs.

6.2. Management API

The Management API is a general-purpose CRUD interface for managing Guardian objects. When installing a new app that integrates with the Guardian, the join script must register the app and create any new Guardian elements that it needs, using this API.

Once the join script is complete, the app has no more need to contact the Management API. However, guardian admins and guardian app admins may use this API to modify roles and capabilities after installing the app.

6.2.1. API documentation

Swagger documentation for the API is located at /guardian/management/docs on the server where the Management API is installed.

The API requires authentication. Click the Authorize button at the top of the page. The default client does not require a client_secret. When logging in, please use the credentials of either a guardian admin or a guardian app admin.

Note

Only the capabilities have a DELETE endpoint. Please see the chapter on Limitations for more information.

6.2.2. Guardian naming conventions

When creating a new object in the Management API, the name for the object should always be lower-case ASCII alphanumeric, with hyphens or underscores to separate words.

For example, if you want to create a role for users who manage a pet store, you might name the role pet-store-manager.

With the exception of apps and namespaces themselves, all objects belong to a namespace. We often represent the full name of an object as a three-part string, with each section separated by colons:

<app-name>:<namespace-name>:<object-name>

For example, if the pet-store-manager role mentioned above belongs to the namespace stores for the app inventory-manager, then the fully namespaced role is inventiory-manager:stores:pet-store-manager.

6.2.3. Registering an app

Before an app can use the Management API, it needs to register itself at the /guardian/management/apps/register endpoint.

Registration looks like:

MANAGEMENT_SERVER="$(hostname).$(ucr get domainname)/guardian/management"

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $keycloak_token" \
    -d '{"name":"my-app", "display_name":"My App"}' \
    $MANAGEMENT_SERVER/apps/register

Note

There is another endpoint, /guardian/management/apps which will also create a new app. However, the register endpoint also does additional setup for the app, such as creating a guardian app admin role that can be used to manage the app.

Unless you know what you are doing, please avoid the /guardian/management/apps endpoint.

After registration, an app must at the bare minimum register the permissions that it needs. However, other Guardian objects are optional and may be manually created by a guardian app admin later.

6.2.4. Conditions

When constructing a capability, the list of available conditions is available with a GET to the /guardian/management/conditions endpoint. Each condition provides a documentation string and a list of parameters it needs.

Please read the chapter on Conditions Reference for more information on Guardian’s built-in conditions.

If the Guardian does not provide a condition that you need, you can create it through the /guardian/management/conditions/{app-name}/{namespace-name} endpoint. This requires a knowledge of Rego, and the code must be base64 encoded when submitting it to the Guardian.

Please see Registering custom conditions in the Developer quick start guide.

6.2.5. Contexts

Contexts are a special feature of the Guardian that allows guardian admins to tell apps about where a role applies.

For example, if Happy Employees installs the Cake Express app, Happy Employees can create a london context and a berlin context, which it includes with the cake-express:cakes:cake-orderer role. Happy Employees can then create a capability where users can only order cakes for people in the same context.

Some of the built-in Guardian conditions explicitly support contexts, such as:

• target_has_same_context

• target_has_role_in_same_context

• target_does_not_have_role_in_same_context

An app must explicitly support contexts and send them as part of requests to the Authorization API. in order to use contexts within a capability. Apps must specify in their documentation whether or not they support contexts.

6.3. Authorization API

The Authorization API helps an app determine whether an actor is authorized to perform a given action within the app.

6.3.1. API documentation

Swagger documentation for the API is located at /guardian/authorization/docs on the server where the Authorization API is installed.

The API requires authentication. Click the Authorize button at the top of the page. The default client does not require a client_secret.

6.3.2. Endpoint overview

There are four primary endpoints in the Authorization API:

• /guardian/authorization/permissions

• /guardian/authorization/permissions/with-lookup

• /guardian/authorization/permissions/check

• /guardian/authorization/permissions/check/with-lookup

The first two endpoints answer the question “What are all the permissions an actor has?”.

The second two endpoints answer the question “Does the user have a specific set of permissions?”. You must supply a list of permissions that you want to check.

In both cases, you must supply an actor, and you may optionally supply targets that are used to answer these questions.

6.3.2.1. About with-lookup endpoints

Some apps maintain all their own data in regards to actors and targets. This means that they do not need access to UDM in order to check capabilities. The examples in the Developer quick start all use endpoints without lookup.

However, endpoints ending in with-lookup will search for the actor and targets in UDM and use the results in checking capabilities. To use the UDM lookup feature, supply the LDAP dn as the id of the actor and targets.

You do not need to supply any attributes or roles in the request, if you use the with-lookup endpoints.

6.3.2.2. General permissions versus target permissions

The Authorization API endpoints allow an app to evaluate permissions for an actor.

A general permission is a permission that exists, regardless of whether there are any targets present in the API request. When listing all permissions, you must set include_general_permissions to true in the request, if you want to see these permissions. See the section on Listing all general permissions in the Developer quick start guide for an example.

Target permissions require one or more targets to be present in the targets field of the request. See the section on Listing all target permissions in the Developer quick start guide for an example.

6.3.2.3. Old target versus new target

When sending targets to the Authorization API, a target consists of an old_target and a new_target. The old_target represents the existing state of the target, and the new_target represents the future state of the target.

For example, a condition could check that the new_target user password is not the same as the old_target password.

If the app doesn’t care about an old and new state of the target, then only the old_target is required.

All built-in conditions check the old_target.

6.3.3. Custom endpoints

The Authorization API has an experimental endpoint, /guardian/authorization/{app-name}/{namespace-name}/{endpoint-name}, that allows an app to define its own custom Rego code to evaluate permissions.

The endpoint does not have UDM access, so the app must supply all of its own data for actors and targets.

This endpoint is not implemented yet, so please do not use it.