7. Management API and Authorization API#
Important
This section covers a highly technical topic. It addresses 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 section.
The Management API and Authorization API are the REST APIs for the Guardian. Read the Developer quick start for concrete examples of using the APIs.
7.1. Management API#
The Management API is a general-purpose CRUD interface for managing Guardian objects. When installing an app that integrates with the Guardian, the join script must register the app and create any Guardian elements that it needs, using this API.
After the join script completes, the app has no more need to contact the Management API. However, guardian administrators and guardian app administrators may use this API to modify roles and capabilities.
7.1.1. API documentation#
OpenAPI/Swagger documentation for the API locates at /guardian/management/docs on the server
where you installed the Management API.
The API requires authentication.
Click the Authorize button at the top of the page.
The default client doesn’t require a client_secret.
When signing in, use the credentials of either a guardian administrator or a guardian app administrator.
Important
Only the capabilities have a DELETE endpoint.
For more information, see No object deletion.
7.1.2. Guardian naming conventions#
When creating an object in the Management API,
the name for the object must always use 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 can name the role pet-store-manager.
With the exception of apps and namespaces themselves,
all objects belong to a namespace.
This documentation 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 belongs to the namespace stores for the app inventory-manager,
then the complete representation of the role is inventory-manager:stores:pet-store-manager.
7.1.3. Registering an app#
Before an app can use the Management API,
it needs to register itself at the /guardian/management/apps/register endpoint.
Listing 7.1 shows an example for registration.
$ 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
After registration, an app must at the bare minimum register the permissions that it needs. However, other Guardian objects are optional and a guardian app administrator may manually create them later.
Caution
There is another endpoint, /guardian/management/apps that also creates an app.
However, the register endpoint also does additional setup steps for the app,
such as creating a guardian app administrator role
that you can use to manage the app.
Unless you know what you are doing,
avoid using the /guardian/management/apps endpoint.
7.1.4. Conditions#
When constructing a capability,
the list of available conditions is available
with a GET request to the /guardian/management/conditions endpoint.
Each condition provides a documentation string and a list of parameters it needs.
For more information about the Guardian’s built-in conditions,
refer to Conditions Reference.
If the Guardian doesn’t provide a condition that you need,
you can create it through the /guardian/management/conditions/app-name/namespace-name endpoint.
This action requires the knowledge of Rego.
And you must submit the Rego code in base64 encoding to the Guardian. For
more information, see Registering custom conditions in the Developer quick start.
7.1.5. Contexts#
Contexts are a special feature of the Guardian that allows guardian administrators 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
and populate them 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:
Important
An app must explicitly support contexts and send them as part of requests to the Authorization API to use contexts within a capability. Apps must specify in their documentation whether or not they support contexts.
7.2. Authorization API#
The Authorization API helps an app determine whether an actor is authorized to perform a particular action within the app.
7.2.1. API documentation#
OpenAPI/Swagger documentation for the API locates at /guardian/authorization/docs on the server
where you installed the Authorization API.
The API requires authentication.
Click the Authorize button at the top of the page.
The default client doesn’t require a client_secret.
7.2.2. Endpoint overview#
The Authorization API has the following primary endpoints:
/guardian/authorization/permissions/guardian/authorization/permissions/with-lookup/guardian/authorization/permissions/check/guardian/authorization/permissions/check/with-lookup
The endpoints 1-2 answer the question “What are all the permissions an actor has?”
The endpoints 3-4 answer the question “Does the user have a specific set of permissions?” You must supply a list of permissions that you want to verify.
In both cases, you must specify an actor, and you can optionally specify targets for use in answering these questions.
7.2.2.1. About with-lookup endpoints#
Some apps maintain all their own data in regards to actors and targets. This means that they don’t need access to Univention Directory Manager (UDM) to verify capabilities. All examples in the Developer quick start use endpoints without lookup.
However, endpoints ending in with-lookup search for the actor and targets in UDM
and use the results in checking capabilities.
To use the UDM lookup feature,
supply the LDAP distinguished name dn as the id of the actor and targets.
You don’t need to supply any attributes or roles in the request,
if you use the with-lookup endpoints.
7.2.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.
For an example, see Listing all general permissions in the Developer quick start guide.
Target permissions require one or more targets
to be present in the targets field of the request.
For an example, see Listing all target permissions in the Developer quick start guide.
7.2.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.
If the app doesn’t care about an old and new state of the target,
then the request only requires the old_target.
All built-in conditions evaluate the old_target.
For example, a condition could verify
that the new_target user password isn’t the same as the old_target password.
7.2.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 doesn’t have UDM access, so the app must supply all of its own data for actors and targets.
Important
Don’t use this endpoint, because it isn’t implemented.