freeipa/doc/api/basic_usage.md

API basic usage guide

• API basic usage guide
  • Introduction
  • Initializing API access
  • Running commands
  • Passing arguments and options
  • Retrieving output
  • Batch operations

Introduction

FreeIPA provides both command line and web based interfaces to interact with its data and perform various operations. While these are enough to access the entire set of features provided by FreeIPA, some users might take advantage of additional ways to interact with it. For this purpose, FreeIPA provides an API that can be accessed through Python, allowing users to interact with FreeIPA programatically and develop custom tools to respond to specific needs not covered by the main interfaces. For users looking to perform stateless operations or manage deployments with statically defined properties, ansible-freeipa is recommended instead.

Initializing API access

We need to run our script in a host that is enrolled to our FreeIPA deployment, either a client or a server. Before running commands, we need a Kerberos ticket:

$ echo $ADMIN_PASSWORD | kinit admin

After this, we can start writing our script. When the API is initialized, we have to set the correct context for the access. Setting the context to server will allow us to access the entire set of backend plugins. This is done with the in_server option.

from ipalib import api

api.bootstrap(context="custom", in_server=True)
api.finalize()

After calling api.finalize(), the initialization is completed and the required plugins are instantiated. Then, we need to create a connection. This depends whether we are accessing from a client or from the server itself, so we can setup logic for it:

if api.env.in_server:
    api.Backend.ldap2.connect()
else:
    api.Backend.rpcclient.connect()

This will connect to LDAP directly if we are running our script in server, or use a RPC client if we are running it from a FreeIPA client.

After we have initialized the API and stablished a connection, we are ready to issue commands.

Running commands

Once the API is initialized, we can find all the available commands under api.Command. You can call them by passing the required parameters.

api.Command.user_show("admin")

Check the API Reference for the full list of commands.

Passing arguments and options

Pass the required arguments as parameters to the command function in the same order as you would on the CLI. To set options, pass them as named parameters after the command arguments.

api.Command.user_show("admin", no_members=True, all=True)

Alternatively, you can use the asterisk operator to pass the set of options as a dictionary:

args = ["admin"]
kw = {
  "no_members" : True,
  "all" : True
}
api.Command.user_show(*args, **kw)

The full list of available arguments and options for each command can be found in the API Reference. Alternatively, it is possible to see the mapping of CLI option to API attribute through ipa show-mappings.

Retrieving output

Command output is returned as a Python dictionary. Example shown is the output of:

api.Command.user_add("test", givenname="a", sn="b")

{
    "result": {
        "displayname": ["a b"],
        "objectclass": [
            "top",
            "person",
            "organizationalperson",
            "inetorgperson",
            "inetuser",
            "posixaccount",
            "krbprincipalaux",
            "krbticketpolicyaux",
            "ipaobject",
            "ipasshuser",
            "ipaSshGroupOfPubKeys",
            "mepOriginEntry",
            "ipantuserattrs",
        ],
        "cn": ["a b"],
        "gidnumber": ["1445000004"],
        "mail": ["test@ipa.test"],
        "krbprincipalname": [ipapython.kerberos.Principal("test@IPA.TEST")],
        "loginshell": ["/bin/sh"],
        "initials": ["ab"],
        "uid": ["test"],
        "uidnumber": ["1445000004"],
        "sn": ["b"],
        "krbcanonicalname": [ipapython.kerberos.Principal("test@IPA.TEST")],
        "homedirectory": ["/home/test"],
        "givenname": ["a"],
        "gecos": ["a b"],
        "ipauniqueid": ["9f9c1df8-5073-11ed-9a56-fa163ea98bb3"],
        "mepmanagedentry": [
            ipapython.dn.DN("cn=test,cn=groups,cn=accounts,dc=ipa,dc=test")
        ],
        "has_password": False,
        "has_keytab": False,
        "memberof_group": ["ipausers"],
        "dn": ipapython.dn.DN("uid=test,cn=users,cn=accounts,dc=ipa,dc=test"),
    },
    "value": "test",
    "messages": [
        {
            "type": "warning",
            "name": "VersionMissing",
            "message": "API Version number was not sent, forward compatibility not guaranteed. Assuming server's API version, 2.248",
            "code": 13001,
            "data": {"server_version": "2.248"},
        }
    ],
    "summary": 'Added user "test"',
}

The output contains four sections:

• result: The actual result of the command. This contains details about the operation, including different options and arguments passed to the command.
• value: The argument the command is applied to. In this example, we created an user called test.
• messages: Different diagnostic information provided by FreeIPA after the operation.
• summary: A summary of the operation.

Batch operations

Batch operations are useful for executing multiple commands at once, as it allows to make multiple calls while just starting one remote procedure call. This might be useful, for example, in scenarios when we want to bulk create entries. Following is the example of bulk creating IPA users using batch operations:

batch_args = []
for i in range(100):
    user_id = "user%i" % i
    args = [user_id]
    kw = {
        'givenname' : user_id,
        'sn' : user_id
    }
    batch_args.append({
        'method' : 'user_add',
        'params' : [args, kw]
    })
ret = api.Command.batch(*batch_args)