Nubus for Kubernetes - Customization and Modification Manual 1.x

UDM HTTP REST API

2.2. UDM HTTP REST API#

This section describes how to use the UDM HTTP REST API in Nubus. It addresses software developers and DevOps engineers. It covers the deployments for Kubernetes and the UCS appliance.

The UDM HTTP REST API provides a REST API to interact with directory objects through the Directory Manager in Nubus. It’s the only component in Nubus that allows packaged integrations and third-party applications to write to the directory service. The API provides create, read, update, and delete operations for directory objects, so-called CRUD operations. It’s accessible to Nubus components and third-party applications on the same cluster network. Nubus for Kubernetes uses the API during its installation to load initial data to the directory service. Packaged integrations use the UDM data loader to load additional data to the directory service.

As software developer you can use the UDM HTTP REST API, for example, to write a plugin for your application for CRUD operations towards Nubus.

Important

By default, the UDM HTTP REST API is accessible from inside and outside the cluster if not deactivated. The UDM HTTP REST API has no measures for brute force detection or multi-factor authentication.

In Nubus for Kubernetes, to deactivate API access for services outside the Kubernetes cluster, set the nubusUdmRestApi.ingress.enabled value in the Helm values file from the default value true to false.

See also

Directory Manager

in Univention Nubus for Kubernetes - Architecture Manual [1] for information about the architecture of the Directory Manager.

2.2.1. API location#

The UDM HTTP REST API provides an API endpoint for requests, an OpenAPI schema definition, and an interactive OpenAPI schema. Table 2.1 shows the endpoints for the UDM HTTP REST API.

Table 2.1 API endpoints#

Endpoint

Interactive OpenAPI schema

OpenAPI schema definition

/univention/udm/

/univention/udm/schema/

/univention/udm/openapi.json

The hostname depends on your deployment of Nubus: Nubus for Kubernetes or Nubus for UCS Appliance.

The value of global.domain in your values file defines the domain of your cluster. Table 2.2 shows the URL schema to the API endpoints in Nubus for Kubernetes. Replace $(domain) with your value in global.domain.

Table 2.2 URLs to API endpoints for Nubus for Kubernetes#

Endpoint

Interactive OpenAPI schema

https://portal.$(domain)/univention/udm/

https://portal.$(domain)/univention/udm/schema/

To download the OpenAPI schema, use https://portal.$(domain)/univention/udm/openapi.json.

Examples

https://portal.example.com/univention/udm/ https://portal.example.com/univention/udm/schema/ https://portal.example.com/univention/udm/openapi.json

In this example, the hostname is portal.example.com.

The UCS Primary Directory Node has the UDM HTTP REST API installed. You need to use its hostname as FQDN for the following URL schema. Table 2.3 shows the URL schema to the API endpoints in Nubus in the UCS appliance.

Table 2.3 URLs to API endpoints in the UCS appliance#

Endpoint

Interactive OpenAPI schema

https://$(FQDN)/univention/udm/

https://$(FQDN)/univention/udm/schema/

To download the OpenAPI schema, use https://$(FQDN)/univention/udm/openapi.json.

Examples

https://primary.example.com/univention/udm/ https://primary.example.com/univention/udm/schema/ https://primary.example.com/univention/udm/openapi.json

In this example, the hostname is primary.example.com.

2.2.2. Authentication#

To use the UDM HTTP REST API you need to authenticate with a user account that’s a member of Authorization groups. By default, one of these user accounts is Administrator. The UDM HTTP REST API provides authentication with user credentials through HTTP basic authentication.

Important

In JSON requests to the UDM HTTP REST API, you always need to ensure to provide the additional header Accept: application/json.

2.2.3. Authorization groups#

The UDM HTTP REST API uses user groups for authorization control and calls them authorization groups. Any user account that’s a member of an authorization group can authenticate to the UDM HTTP REST API.

Important

Adding the group for access to the UDM HTTP REST API only grants permission to access the API and the download of the OpenAPI schema. The API works with the authorized user on the directory service. If this user doesn’t have sufficient read or write permissions on the directory service, you need to add access control lists (ACLs) to grant the required permission.

For information about modifying LDAP ACLs, see LDAP ACLs.

Nubus defines the following authorization groups by default, depending on the deployment.

Pre-defined authorization groups in Nubus for Kubernetes:

Domain Admins

The group contains user accounts with domain administration privileges, such as the Administrator user account.

Domain Service Users

The group contains domain service users. For example, when a service needs to access the API, you can put the service’s user account into that group.

New in version 1.7.0.

When you lookup the defined authorization groups, you can also find definitions for the groups DC Backup Hosts and DC Slave Hosts. Although Nubus has the groups defined, they have no relevance in Nubus for Kubernetes. They come from the implementation for UCS appliance deployment.

Pre-defined authorization groups in Nubus for the UCS appliance:

Domain Admins

The group contains user accounts with domain administration privileges, such as the Administrator user account.

DC Backup Hosts

The group contains user accounts that represent systems in the system role Backup Directory Node. This group is only relevant for the UCS appliance.

DC Slave Hosts

The group contains user accounts that represent systems in the system role Replica Directory Node. This group is only relevant for the UCS appliance.

If you need additional user accounts with access to the UDM HTTP REST API, you can add them to the Domain Admins user group, for example through the Users module in the Management UI.

Caution

User accounts in the Domain Admins group have extensive administration rights. If you want to grant user accounts access to the UDM HTTP REST API without extensive administration rights, you need to add an authorization group.

Creating a dedicated user group and using it as authorization group for the UDM HTTP REST API is helpful, if you want to give the user accounts in that group just these rights for the API. Use one of the following sections depending on your deployment:

2.2.3.1. Add authorization group in Nubus for Kubernetes#

This section describes how to add an authorization group for the UDM HTTP REST API in Nubus for Kubernetes.

  1. In the Management UI of Nubus, create the user group, for example udm-rest-api-users.

  2. Add user accounts as members to the user group.

  3. Add the group’s LDAP DN to your custom_values.yaml values file using the following steps:

    1. Add the global.configUcr section.

    2. Add the UCR variable directory/manager/rest/authorized-groups/group-name.

      Replace group-name with the name of your group.

      Set the value to the LDAP DN of your group. The default schema is cn=group-name,cn=groups,global.ldap.baseDn. Replace global.ldap.baseDn with the value of global.ldap.baseDn that you find in your custom_values.yaml values file.

    The parts look like the example in Listing 2.6:

    Listing 2.6 Example for adding an authorization group for UDM HTTP REST API to values file#
    global:
  configUcr:
    directory:
      manager:
         rest:
            authorized-groups:
               udm-rest-api-users: cn=udm-rest-users,cn=groups,dc=example,dc=com
    Where can I find the LDAP DN for the group?

    You can ask Nubus for the LDAP DN of your group with the following steps.

    For the interactive request, open the interactive OpenAPI schema of the UDM HTTP REST API. For the URL, see API location.

    1. Navigate to the groups/group section.

    2. Open the GET request section and click Try it out.

    3. Enter cn=group-name into the field filter. Replace group-name with the name of your group. Click Execute.

    4. In the Reponses ‣ Response body field look for a line that includes name and an LDAP DN as value. Use the value for the UCR variable in your values file.

    5. For the response, see Listing 2.8.

    Listing 2.7 shows the command for the search request. For the initialization of the used environment variables, see Listing 2.18.

    Listing 2.7 Example for command to search for group group-name#
    $ curl \
    --user ${USER}:${PASSWORD} \
    --request GET \
    --header "Accept: application/json" \
    "https://${HOSTNAME}/univention/udm/groups/group/?filter=cn%3Dgroup-name
    Response

    Listing 2.8 shows an example for the response.

    Listing 2.8 Example for excerpt from a search result for a group object#
    "_embedded": {
  "udm:object": [
    {
      "dn": "cn=group-name,cn=groups,dc=example,dc=com",
      "objectType": "groups/group",
      "id": "group-name",
      "position": "cn=groups,dc=example,dc=com",
      "properties": {
        "name": "group-name",
        "gidNumber": 5009,
        "sambaRID": 11019,
        "sambaGroupType": "2",
        "sambaPrivileges": [],
        "adGroupType": "-2147483646",
        "description": null,
        "users": [],
        "hosts": [],
        "mailAddress": null,
        "memberOf": [],
        "nestedGroup": [],
        "allowedEmailUsers": [],
        "allowedEmailGroups": [],
        "univentionObjectIdentifier": null,
        "univentionSourceIAM": null,
        "guardianMemberRoles": [],
        "objectFlag": []
      },

  4. You need to announce the group to the UDM HTTP REST API through the Helm Chart. This action updates the configuration map that includes the UCR variable.

    Run the command in Listing 2.9. For the environment variable values, see Install Univention Nubus on a Kubernetes cluster in Univention Nubus for Kubernetes - Operation Manual [2].

    Listing 2.9 Apply changes from the values file to Nubus for Kubernetes#
    $ helm upgrade \
   --namespace="$NAMESPACE_FOR_NUBUS" \
   --values custom_values.yaml \
   --version "$VERSION" \
   --timeout 10m \
   "$RELEASE_NAME" \
   oci://artifacts.software-univention.de/nubus/charts/nubus

  5. Finally, you need to restart the Kubernetes pod for the UDM HTTP REST API to apply the changes to the UCR variables. If you scaled up the UDM HTTP REST API, you need to restart every pod. Run the commands in Listing 2.10.

    Listing 2.10 Restart pod for UDM HTTP REST API to apply UCR variable changes#
    $ kubectl --namespace "$NAMESPACE_FOR_NUBUS" get pods | grep "udm-rest-api"
$ export NAME_OF_PODS="Name of each pod in the output of the previous command."
$ kubectl --namespace "$NAMESPACE_FOR_NUBUS" delete pod "$NAME_OF_PODS"
How to lookup authorization groups in Nubus for Kubernetes?

To lookup the authorization groups in Nubus for Kubernetes you can either ask your Nubus for Kubernetes installation, or read the rendered Helm Chart template.

To lookup the authorization groups in your Nubus for Kubernetes installation, use the command in Listing 2.11. For the environment variable values, see Install Univention Nubus on a Kubernetes cluster in Univention Nubus for Kubernetes - Operation Manual [2].

Listing 2.11 Lookup authorization groups in Nubus for Kubernetes installation#
$ kubectl --namespace "$YOUR_NAMESPACE" \
   describe configmaps \
   "$RELEASE_NAME-stack-data-ums-ucr" \
   | grep authorized-groups
directory/manager/rest/authorized-groups/dc-backup: cn=DC Backup Hosts,cn=groups,...
directory/manager/rest/authorized-groups/dc-slaves: cn=DC Slave Hosts,cn=groups,...
directory/manager/rest/authorized-groups/domain-admins: cn=Domain Admins,cn=groups,...

By default, Domain Admins is one authorization group for the UDM HTTP REST API. The other groups DC Backup Hosts and DC Slave Hosts aren’t relevant in the Nubus for Kubernetes context. They come from the implementation for UCS appliance deployment. See Authorization groups.

To render the Helm Chart template and lookup the authorization groups in Nubus for Kubernetes, use the following commands:

  1. Set the version of the Helm Chart in the variable VERSION as in Download example configuration values for deployment in Univention Nubus for Kubernetes - Operation Manual [2].

  2. Render the template and save the result for later use. Use the command in Listing 2.12.

    Listing 2.12 Render Helm Chart template for lookup of authorization groups#
    $ helm template \
   --values custom_values.yaml \
   --version "$VERSION" \
   oci://artifacts.software-univention.de/nubus/charts/nubus > rendered_template.yaml

  3. Open the YAML file rendered_template.yaml in your favorite text editor and look for the ConfigMap that contains stack-data-ums-ucr in metadata.name.

2.2.3.2. Add authorization group in Nubus for UCS appliance#

This section describes how to add an authorization group for the UDM HTTP REST API in Nubus for the UCS appliance.

  1. In the Management UI, create the user group, for example udm-rest-api-users. Alternatively, you can use the terminal on the Primary Directory Node to create the user group, as shown in Listing 2.13. The example uses udm-rest-api-users as group name. You can specify your own group name.

    Listing 2.13 Add user group through UDM on the terminal#
    $ udm groups/group create \
   --position="cn=groups,$(ucr get ldap/base)" \
   --set name="udm-rest-api-users"

  2. Add user accounts as members to the user group.

  3. Create the UCR variable on the Primary Directory Node that points to the group as shown in Listing 2.14.

    Listing 2.14 Create UCR variable pointing to the created authorization group#
    $ ucr set \
   directory/manager/rest/authorized-groups/udm-rest-api-users=\
   "cn=udm-rest-api-users,cn=groups,$(ucr get ldap/base)"

  4. Restart the UDM HTTP REST API service on the Primary Directory Node to activate the changes. Run the command in Listing 2.15.

    Listing 2.15 Restart the UDM HTTP REST API service#
    $ systemctl restart univention-directory-manager-rest
How to lookup authorization groups in Nubus for UCS appliance?

To lookup the available authorization groups in Nubus for UCS appliance, access the Primary Directory Node through a terminal and use the command in Listing 2.16.

Listing 2.16 Lookup authorization groups in UCR through a terminal#
$ ucr search directory/manager/rest/authorized-groups
directory/manager/rest/authorized-groups/.*: <empty>
directory/manager/rest/authorized-groups/dc-backup: cn=DC Backup Hosts,cn=groups,...
directory/manager/rest/authorized-groups/dc-slaves: cn=DC Slave Hosts,cn=groups,...
directory/manager/rest/authorized-groups/domain-admins: cn=Domain Admins,cn=groups,...

2.2.4. API methods#

You can interact with the API by sending HTTP requests to the appropriate API resources. Depending on the resource, different HTTP methods are available. Table 2.4 lists the HTTP methods. For the parameters, see the OpenAPI interactive schema. For a description of how to use the schema, see API location.

Table 2.4 HTTP methods for UDM HTTP REST API#

Method

Description

GET

To search, list, or get UDM objects.

Example: Search for a user object.

POST

To create a UDM object.

Example: Create a user object.

DELETE

To remove a UDM object.

Example: Delete a user object.

PUT

To modify the properties of a UDM object, or move the object into a different container.

See Object modification with PATCH and PUT.

Example: Modify a user object.

PATCH

To modify the properties of a UDM object.

See Object modification with PATCH and PUT.

Example: Modify a user object.

For information about the differences between PATCH and PUT, see Object modification with PATCH and PUT. To ensure that the UDM HTTP REST API works on the same object from your initial request, see Conditional requests with entity tags.

The UDM HTTP REST API is merely a wrapper around UDM modules. UDM modules define the business logic and the properties of the objects.
The general URL schema to address a UDM module is /univention/udm/<module>/<object>/.
Examples

  • /univention/udm/users/user/

  • /univention/udm/groups/group/

  • /univention/udm/portals/entry/

Important

You need to manually restart the UDM HTTP REST API service, if you use the API to create, modify, or delete the following endpoints:

  • settings/extended_attribute

  • settings/udm_hook

  • settings/udm_module

  • settings/udm_syntax

  • settings/syntax

For Nubus for Kubernetes, run the commands as shown in Listing 2.10.

For Nubus for UCS appliance, run the commands as shown in Listing 2.15.

Note

To get a full list of resources and their available methods and parameters, browse the OpenAPI interactive schema. It’s available in any running Nubus installation. See API location. Listing all resources would exceed the document’s scope.

See also

Internal functions

in Univention Nubus for Kubernetes - Architecture Manual [1] for more information about the Directory Manager.

2.2.4.1. Object modification with PATCH and PUT#

For object modification, the UDM HTTP REST API offers the HTTP methods PATCH and PUT:

PATCH

With the PATCH HTTP method you can modify object properties, except the object’s distinguished name (DN). Use PATCH, if you want to only change object properties.

PUT

With the PUT HTTP method you modify and replace the whole object and move it to a different position in the directory service tree that changes the object’s distinguished name (DN). Use PUT, if you want to modify the object’s position, of if you want to replace the object.

See also

For more information about the differences of these HTTP methods, see the following web pages:

PATCH - HTTP | MDN

The PATCH HTTP method applies partial modifications to a resource.

PUT - HTTP | MDN

The PUT HTTP method creates a new resource or replaces a representation of the target resource with the request content.

2.2.4.2. Conditional requests with entity tags#

The UDM HTTP REST API supports entity tags (etags) and allows conditional requests through the If-Match header. It’s recommended to use entity tags in requests to the API to ensure that a third party hasn’t modified the object of interest in the time between requests to the same object.

Before you can modify a user object, you must know the object’s distinguished name (DN) and you need to retrieve the current state. If you retrieve the entity tag and send it along as If-Match header when modifying the object, the UDM HTTP REST API can ensure that the object didn’t change in the meantime. You find the entity tag in the response header in the field etag.

Important

You need to specify the distinguished name (DN) of the object as URL encoded string. Listing 2.17 shows one way to convert the DN to a URL encoded string.

Listing 2.17 Create URL encoded string from distinguished name with Python#
echo "uid=...,cn=users,dc=example,dc=com" \
   | python3 -c 'import urllib.parse, sys; \
     print(urllib.parse.quote(sys.stdin.buffer.read()));'

See also

If-Match - HTTP | MDN

for more information about the HTTP If-Match request header.

2.2.5. API response codes#

Table 2.5 shows a non-exhaustive list of HTTP response codes that the UDM HTTP REST API uses to respond to requests.

Table 2.5 HTTP response codes for the UDM HTTP REST API#

Code

Name

Example case

400

Bad Request

The API doesn’t understand the format of the request. The payload is most likely not in the format expected by the UDM HTTP REST API.

401

Unauthorized

The request provides no or wrong credentials for authorization, or the Directory Service isn’t available.

403

Forbidden

User isn’t part of any of the Authorization groups.

404

Not Found

The requested resource doesn’t exist.

406

Not Acceptable

The header field Accept doesn’t specify a known MIME media type or the header field Accept-Language doesn’t specify a known language.

When you use JSON requests and expect JSON responses, you need to set the Accept header to Accept: application/json, instead of Accept: */*.

412

Precondition Failed

The header If-Match doesn’t match the entity tag or the header If-Unmodified-Since doesn’t match the header Last-Modified.

413

Payload Too Large

The request payload contains a field that exceeds its size limit.

416

Range Not Satisfiable

In the request, the field If-Match doesn’t match the entity tag and the request has the field Range set.

422

Unprocessable Content

The validation of input parameters failed.

500

Internal Server Error

Generic error code for internal server errors. In Nubus for Kubernetes, the UDM HTTP REST API pod’s log may contain more information.

503

Service Unavailable

The server for the service isn’t available.

2.2.6. Usage examples#

This section shows examples for how to create, modify, search, and delete a user through the UDM HTTP REST API.

To follow along with the examples, define environment variables as shown in Listing 2.18. The HOSTNAME depends on your deployment. For the respective value, see API location.

Listing 2.18 Set proper variables for examples#
$ export HOSTNAME="<hostname to api>"
$ export USER="<username to userobject in authorization group>"
$ export PASSWORD="<password for the user>"
$ export MODULE="<UDM module to address>"

Note

When you go through the examples, you see the _links and _embedded properties in the responses. HAL, the Hypertext Application Language, defines theses properties and the API uses them. The properties contain links for traversal through the API. For more information on HAL, refer to JSON Hypertext Application Language.

For example, the _links property of the response to a paginated query contains the next property pointing to the next page.

2.2.6.1. Templates for UDM modules#

The UDM modules in the UDM HTTP REST API provide templates in JSON format that help you to fill out the expected properties for requests. This section introduces templates for UDM modules, describes how you can retrieve them, and how to condense them for proper editing.

Generic command

Listing 2.19 shows the generic command to retrieve a template. For the initialization of the used environment variables, see Listing 2.18.

Listing 2.19 Schema to retrieve template for UDM module#
$ curl \
   --user ${USER}:${PASSWORD} \
   --request GET \
   --header "Accept: application/json" \
   https://${HOSTNAME}/univention/udm/${MODULE}/add
Template for users/user UDM module

To retrieve the template for the users/user UDM module, use the commands in Listing 2.20.

Listing 2.20 Retrieve template for users/user UDM module#
$ export MODULES="users/user"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request GET \
   --header "Accept: application/json" \
   https://${HOSTNAME}/univention/udm/${MODULE}/add
Human-readable template

To make the template more readable and save it into a file, you can use Python as shown with the commands in Listing 2.21. The result is a file with more than 160 lines in properly formatted JSON.

Listing 2.21 Use Python to properly format the template for users/user UDM module#
$ export MODULES="users/user"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request GET \
   --header "Accept: application/json" \
   https://${HOSTNAME}/univention/udm/${MODULE}/add \
   | python3 -m json.tool > user_template.json
Condensed template without metadata

The JSON file contains metadata information in the keys that start with _. The metadata information isn’t necessary to create a user object. To filter out the metadata, use the command in Listing 2.22. The condensed template file has only more than 110 lines.

Listing 2.22 Condensed template for users/user UDM module without metadata properties#
$ export MODULES="users/user"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request GET \
   --header "Accept: application/json" \
   https://${HOSTNAME}/univention/udm/${MODULE}/add \
   | python3 -c 'import sys, json; \
      template = json.load(sys.stdin); \
      template = {key:value for key, value in template.items() if not key.startswith("_")}; \
      json.dump(template, sys.stdout, indent=4)' > user_template.json

2.2.6.2. Create a user object#

This example shows how to create a user object with a POST request to the UDM HTTP REST API.

  1. Before you continue, download the UDM template for the users/user module as shown in Listing 2.22, and save the template in the user_template.json file.

  2. Copy the template file to the user.json file and edit the properties to suitably describe the user object that you want to create.

  3. To send the POST request and use the user.json as input for the user account properties, run the commands in Listing 2.23. For the initialization of the used environment variables, see Listing 2.18.

    Listing 2.23 Create user through a POST request#
    $ export MODULES="users/user"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request POST \
   --header "Accept: application/json" \
   --header "Content-Type: application/json" \
   --data @user.json \
   https://${HOSTNAME}/univention/udm/${MODULE}/

2.2.6.3. Search for a user object#

This example shows a request to search for a user object, whose username property starts with "Admi". Listing 2.24 shows the commands for the search request. For the initialization of the used environment variables, see Listing 2.18.

Listing 2.24 Search a user object through a GET request#
$ export MODULES="users/user"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request GET \
   --header "Accept: application/json" \
   "https://${HOSTNAME}/univention/udm/${MODULE}/?query\[username\]=Admi*"
Search result example

The result looks similar to Listing 2.25. It only shows the _embedded section for brevity. The omitted section is _links.

Listing 2.25 Excerpt from a search result for a user object#
"_embedded": {
    "udm:object": [
        {
            "dn": "uid=Administrator,cn=users,dc=example,dc=com",
            "objectType": "users/user",
            "id": "Administrator",
            "position": "cn=users,dc=example,dc=com",
            "properties": {
                "username": "Administrator",
                "uidNumber": 2001,
                "gidNumber": 5000,
                "firstname": "Admin",
                "lastname": "Administrator",
                "gecos": "Admin Administrator",
                "displayName": "Admin Administrator",
                "title": null,
                "initials": null,
                "preferredDeliveryMethod": null,
                "sambaPrivileges": [],
                "description": null,
                "organisation": null,
                "userexpiry": null,
                "passwordexpiry": null,
                "pwdChangeNextLogin": false,
                "preferredLanguage": null,
                "disabled": false,
                "accountActivationDate": {
                    "activation-date": null,
                    "activation-time": null,
                    "activation-timezone": "Etc/UTC"
                },
                "locked": false,
                "lockedTime": "0",
                "unlock": false,
                "unlockTime": "",
                "password": null,
                "street": null,
                "e-mail": [],
                "postcode": null,
                "postOfficeBox": [],
                "city": null,
                "country": null,
                "state": null,
                "phone": [],
                "employeeNumber": null,
                "roomNumber": [],
                "secretary": [],
                "departmentNumber": [],
                "employeeType": null,
                "homePostalAddress": [],
                "physicalDeliveryOfficeName": null,
                "homeTelephoneNumber": [],
                "mobileTelephoneNumber": [],
                "pagerTelephoneNumber": [],
                "birthday": null,
                "unixhome": "/home/Administrator",
                "shell": "/bin/bash",
                "sambahome": null,
                "scriptpath": null,
                "profilepath": null,
                "homedrive": null,
                "sambaRID": 500,
                "groups": [
                    "cn=Domain Admins,cn=groups,dc=example,dc=com",
                    "cn=Domain Users,cn=groups,dc=example,dc=com"
                ],
                "primaryGroup": "cn=Domain Admins,cn=groups,dc=example,dc=com",
                "mailHomeServer": null,
                "mailPrimaryAddress": "administrator@example.com",
                "mailAlternativeAddress": [],
                "mailForwardAddress": [],
                "mailForwardCopyToSelf": "0",
                "overridePWHistory": null,
                "overridePWLength": null,
                "homeShare": null,
                "homeSharePath": "Administrator",
                "sambaUserWorkstations": [],
                "sambaLogonHours": null,
                "jpegPhoto": null,
                "umcProperty": {},
                "univentionObjectIdentifier": null,
                "univentionSourceIAM": null,
                "guardianRoles": [
                    "guardian:builtin:super-admin"
                ],
                "guardianInheritedRoles": [],
                "PasswordRecoveryEmail": null,
                "PasswordRecoveryMobile": null,
                "PasswordRecoveryEmailVerified": null,
                "RegisteredThroughSelfService": null,
                "DeregisteredThroughSelfService": null,
                "DeregistrationTimestamp": null,
                "objectFlag": []
            },
            "options": {
                "pki": false
            },
            "policies": {
                "policies/umc": [],
                "policies/pwhistory": [],
                "policies/desktop": []
            },
            "uuid": "3c1a22f8-83e4-103f-8df6-e102f7f2195d",
            "uri": "https://portal.example.com/univention/udm/users/user/uid%3DAdministrator%2Ccn%3Dusers%2Cdc%3Dexample%2Cdc%3Dcom",
            "_links": {
                "self": [
                    {
                        "name": "uid=Administrator,cn=users,dc=example,dc=com",
                        "title": "Administrator",
                        "href": "https://portal.example.com/univention/udm/users/user/uid%3DAdministrator%2Ccn%3Dusers%2Cdc%3Dexample%2Cdc%3Dcom"
                    }
                ]
            }
        }
    ]
},
"results": 1

2.2.6.4. Modify a user object#

This example shows the necessary steps to modify a user object. Take the following notes into account:

To modify a user object, use the following steps:

  1. To retrieve the user object and the entity tag, run the commands in Listing 2.26. The curl command stores the headers in the user.headers file, and the user properties in the user.json file. For the initialization of the used environment variables, see Listing 2.18.

    Listing 2.26 Retrieve current state of user object and its entity tag#
    $ export MODULES="users/user"
$ export DN="<URL encoded string for object DN>"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request GET \
   --header "Accept: application/json" \
   --dump-header user.headers \
   "https://${HOSTNAME}/univention/udm/${MODULE}/${DN}" \
   | python3 -m json.tool > user.json

  2. Edit the properties of the user object in the user.json file that you want to modify for the user object.

  3. Send the modified user object properties through a PUT request with the command in Listing 2.27.

    The user.headers file contains the entity tag header in the etag field. To avoid modification conflicts, the UDM HTTP REST API requires that you send the value of the entity tag header as value for the If-Match header.

    Listing 2.27 Modify a user object with a PUT request#
    $ export MODULES="users/user"
$ export DN="<URL encoded string for object DN>"
$ export ETAG="<value from etag header>"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request PUT \
   --header "Accept: application/json" \
   --header "Content-Type: application/json" \
   --header "If-Match: ${ETAG}" \
   --data @user.json
   "https://${HOSTNAME}/univention/udm/${MODULE}/${DN}"

2.2.6.5. Delete a user object#

This example shows the steps to delete a user object through a DELETE request. Before you can begin, you need the user object’s distinguished name. To ensure conditional deletion, use the entity tag in the If-Match header. Take the following notes into account:

Important

You need to specify the distinguished name (DN) of an object as URL encoded string. Listing 2.17 shows an example for one way to convert the DN to a URL encoded string.

To delete a user object, use the following steps:

  1. Optional: To retrieve the user object and the entity tag for the If-Match header, run the commands in Listing 2.26.

  2. To delete the object, run the commands in Listing 2.28.

    Listing 2.28 Delete a use object with a DELETE request#
    $ export MODULES="users/user"
$ export DN="<URL encoded string for object DN>"
$ export ETAG="<value from etag header>"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request DELETE \
   --header "Accept: application/json" \
   --header "If-Match: $ETAG" \
   "https://${HOSTNAME}/univention/udm/${MODULE}/${DN}"
On this page