Skip to main content

Introduction

fusiondirectory-api is a Python3 wrapper for the RPC API of LDAP manager FusionDirectory. You need to enable the plugin webservice in FusionDirectory to be able to use the API.

This wrapper supports the RPC based API in versions of FusionDirectory up to 1.3. This API may be deprecated in version 1.4 as a change to a REST based API is planned.

As FusionDirectory manages data in LDAP, the database can also be updated directly in LDAP. However, using the API has the following advantages:

  • Access for the API user is controlled by access control lists created in the FusionDirectory GUI. No need to configure access on the LDAP server.
  • Objects can be created from templates maintained in the FusionDirectory GUI.
  • LDAP data can be accessed via HTTP/HTTPS on ports 80/443 instead of through the LDAP ports 389/636.
  • Users can be locked/unlocked (Prefix encrypted password with !) without giving the API user access to the ldap field userPassword.

Installation

Install with pip: pip3 install fusiondirectory-api

Overview

A description of key concepts when working with the FusionDirectory API

Databases

FusionDirectory can handle more than a single database. In the GUI, the database to use can be selcted from a drop down. When the using the API, the name of the database to use, must be supplied when logging in.

Objects

FusionDirectory organizes data in objects. There are different types of object. One type of object is USER. In general, the object type needs to be specified along with the object's DN when manipulating objects with the API.

The object types supported by an installation of FusionDirectory, depends on which plugins are enabled. The list of objects in an installation can be retrieved by calling get_object_types().

These are the objects in the FusionDirectory installation of the author of this project:

  • CONFIGURATION
  • OGROUP
  • PRINTER
  • ROLE
  • WORKSTATION
  • SAMBADOMAIN
  • USER
  • TERMINAL
  • SERVER
  • MOBILEPHONE
  • COUNTRY
  • ACLASSIGNMENT
  • ACLROLE
  • COMPONENT
  • GROUP
  • DCOBJECT
  • DEPARTMENT
  • DOMAIN
  • LOCALITY
  • ORGANIZATION
  • PHONE

Tabs

The data for an object, is organized in tabs. The tabs available for an object type, depends on the activated plugins. The tabs available for an object type can be retrieved by calling get_tabs(OBJECT_TYPE). By default, tabs are inactive. The following dictionary shows the avaiable tabs for the object type USER in the author's installation. The outher keys are the values which should be used when refering to a tab when using the API. The name is the name for the tab in the webinterface GUI.

{
  'user': {'name': 'User', 'active': True},
  'posixAccount': {'name': 'Unix', 'active': False},
  'personalInfo': {'name': 'Personal', 'active': False},
  'mailAccount': {'name': 'Mail', 'active': False},
  'sambaAccount': {'name': 'Samba', 'active': False},
  'userRoles': {'name': 'Groups and roles', 'active': False},
  'sshAccount': {'name': 'SSH', 'active': False},
  'userCertificates': {'name': 'Certificates', 'active': False},
  'reference': {'name': 'References', 'active': True},
  'ldapDump': {'name': 'LDAP', 'active': True}
}

Templates

Objects can be created from templates. The templates can not be created from the API. They need to be created manually in the GUI. The DN of the template is needed when creating an object from a template.

Examples

This section contains som examples showing how to use the API.

Logging in

Log in, and show available object types.

# Import the library
from fusiondirectory_api import FusionDirectoryAPI

# Log in to the FusionDirectory server
api = FusionDirectoryAPI(
  host = "https://ldap.example.org",
  user = "user-name",
  password = "secret-password",
  database = "my-ldap",
  )

# Get the object types available
object_types = api.get_object_types()

# Print the object types
print(object_types)

Creating a new user

Let's create a new object of type USER. Its assumed you have created the object api as shown in the example above. Note, that the password is a list, because the inner workings are based on the GUI, where the user has to type the password twice (To confirm). The 1st entry in the list should be the empty string, the 2nd and 3rd entries must be the password to be used. That is the 2nd and 3rd entry must be identical.

# The data for the new user
values = {
  "user": {
    "uid": "bj",
    "sn": "Jacobsen",
    "givenName": "Bent",
    "userPassword": ["", "secretpassword", "secretpassword"],
  }
}

# Create the new user
new_user_dn = api.create_object("USER", values)

# Print the DN of the new user
print(f"Created new user: {new_user_dn}")

Updating a user

Add an email address to the user we created above.

# The data to add to the user
values = {
  "mailAccount": {
    "mail": "bj@example.org"
  }
}

# Update the user
updated_user_dn = api.update_object("USER", new_user_dn, values)

# Print to confirm the change
print(f"Updated data for user: {updated_user_dn}")

Deleting a user

Delete the user from the examples above.

# Delete the user
result = api.delete_object("USER", new_user_dn)

# Print to confirm (True)
print(f"Deleted user: {result}")

Retrieving user data

Get data from objects using the method get_objects(object_type, attributes=None, ou=None, filter=""). Set attributes to a dictionary with LDAP attributes as keys, and one of the following as value:

  • 1 : Get a single attribute
  • * : Get attribute(s) as list
  • raw : Untouched LDAP value
  • b64 : Base64 encoded data. Usefull for binary data
# Get the _cn_ and a list of _objectClass_ for all _USER_ objects in the database.
r = api.get_objects("USER", attributes={"cn": "1", "objectClass": "*"})

# Print the result.
print(r)

Class documentation

Technical documentation. For a description of each medthod, look at doc strings in source code.

Constructor

  • FusionDirectoryAPI(host, user, password, database, login=True)

Methods

  • create_object(object_type, values, template_dn=None)
  • delete_tab(object_type, object_dn, tab)
  • delete_object(object_type, object_dn)
  • get_base()
  • get_fields(object_type, object_dn=None, tab=None) (USELESS?)
  • get_number_of_objects(object_type, ou=None, filter="")
  • get_session_id()
  • get_objects(object_type, attributes={"objectType" = "*"}, ou=None, filter=None)
  • get_object(object_type, dn, attributes={"objectType" = "*"})
  • get_object_type_info(object_type)
  • get_object_types()
  • get_databases()
  • get_tabs(object_type, object_dn=None)
  • get_recovery_token(email)
  • get_template(object_type, template_dn) (USELESS?)
  • user_is_locked(user_dn)
  • lock_user(user_dn)
  • unlock_user(user_dn)
  • login(user, password, database, verify_cert=True, login=True, enforce_encryption=True, client_id="python_api_wrapper")
  • logout()
  • set_password(uid, password, token) (TOKEN ALWAYS INVALID?)
  • update_object(object_type, object_dn, values)

Testing

Run tests from project root. You need a running instance of FusionDirectory. Set up environment variables (Assuming Linux).

  • export FD_USER = "user-name"
  • export FD_PASSWORD = "secret-password"
  • export FD_HOST = "https://fd.example.org"
  • export FD_DATABASE = "my-ldap-database"
py.test tests.py

Metadata

Release files for fusiondirectory-api 0.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fusiondirectory-api 0.0.8
File Size Uploaded Provenance Actions
fusiondirectory-api-0.0.8.tar.gz 23.9 kB Without provenance Details for fusiondirectory-api-0.0.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fusiondirectory-api 0.0.8
File Interpreter ABI Platform Actions
fusiondirectory_api-0.0.8-py3-none-any.whl Python 3 none any Details for fusiondirectory_api-0.0.8-py3-none-any.whl

Total release size: 45.0 kB

Release files / fusiondirectory-api-0.0.8.tar.gz

Download URL fusiondirectory-api-0.0.8.tar.gz
Size 23.9 kB
Tags Source
SHA-256 checksum
How to use checksums
07ef711f2d8b38e4cdb3e16dd2eefbcfb28df2107a0700f312ef1ddcc25dc44e
BLAKE2b-256 checksum
How to use checksums
f3541593f085524de73b1612857fbc7441fb642c1460f235893c93febf997cb4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.6

Release files / fusiondirectory_api-0.0.8-py3-none-any.whl

Download URL fusiondirectory_api-0.0.8-py3-none-any.whl
Size 21.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d71cb5a9f43d837044fb4d0c7f4adc032ebf0367b5e078868b8b1ca066438fa2
BLAKE2b-256 checksum
How to use checksums
a78bfe807df8c257d6ed7237759c6719fbe250a6b6f61a9ac011986beabc669c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.6

Security for fusiondirectory-api 0.0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page