Chapter 2. Basics of IdM API
You can use the IdM API to automate the access to IdM environment with your custom scripts.
2.1. Initializing IdM API
To use the IdM API, first initialize it in your environment.
Prerequisites
- The IdM server or IdM client package is installed.
- A valid Kerberos ticket is issued.
Procedure
To initialize the IdM API, include the following code in the beginning of your script:
from ipalib import api api.bootstrap(context="server") api.finalize()
To establish a connection with the LDAP server, add the following logic to your script after API initialization:
if api.env.in_server: api.Backend.ldap2.connect() else: api.Backend.rpcclient.connect()- If you run your script on the IdM server, this logic allows your script to connect directly to LDAP server.
- If you run your script on the IdM client, the script uses the Remote Procedure Call (RPC) client.
Additional resources
2.2. Running IdM API commands
You can run IdM API commands within your script. To run an IdM API command, use the api.Command structure in your script.
Prerequisites
- The IdM API is initialized. For more information, see Initializing IdM API.
Procedure
For example, to list the information about user, include the following code in your script:
api.Command.user_show("user_name", no_members=True, all=True)In this example, you also pass arguments and options to the command
user_show.
Additional resources
-
For the full list of the
api.Commandcommands, see IPA API Commands web source.
2.3. IdM API commands output structure
Each IdM API command has four sections for its output. These sections contain various information about the command execution.
IdM API output structure
result- This section provides the result of the command. It contains various details about the command operation, such as options and arguments which were passed to the command.
values- This section indicates the argument for the command.
messages-
This section shows various information which
ipatool provides after the execution of the command. summary- This section shows the summary for the operation.
In this example, your script executes the add_user command:
api.Command.user_add("test", givenname="a", sn="b")The output structure of that command is below:
{
"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"',
}2.4. Listing the IdM API commands and parameters
You can list information about the IdM API command and its parameters by using the commands command_show and param_show.
Prerequisites
- The IdM API is initialized. For more information, see Initializing IdM API.
Procedure
To display information about
user_addcommand, execute the following code:api.Command.command_show("user_add")The result for this command is as follows:
{ "result": { "name": "user_add", "version": "1", "full_name": "user_add/1", "doc": "Add a new user.", "topic_topic": "user/1", "obj_class": "user/1", "attr_name": "add", }, "value": "user_add", "messages": [ { "type": "warning", "name": "VersionMissing", "message": "API Version number was not sent, forward compatibility not guaranteed. Assuming server's API version, 2.251", "code": 13001, "data": {"server_version": "2.251"}, } ], "summary": None, }To display information about the
givennameparameter for theuser_addcommand, execute the following code:api.Command.param_show("user_add", name="givenname")The result for this command is as follows:
{ "result": { "name": "givenname", "type": "str", "positional": False, "cli_name": "first", "label": "First name", }, "value": "givenname", "messages": [ { "type": "warning", "name": "VersionMissing", "message": "API Version number was not sent, forward compatibility not guaranteed. Assuming server's API version, 2.251", "code": 13001, "data": {"server_version": "2.251"}, } ], "summary": None, }
2.5. Using batches for executing IdM API commands
You can execute multiple IdM API commands with a single call by using the batch command. The following example shows how to create multiple IdM users.
Prerequisites
- The IdM API is initialized. For more information, see Initializing IdM API.
Procedure
To create 100 IdM users in one batch, include the following code into your script:
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)
2.6. IdM API context
IdM API context determines which plug-ins the API uses. Specify the context during API initialization. For example on how to use the IdM API context, see Initializing IdM API.
IdM API context
server- Set of plug-ins which validate arguments and options that are passed to IdM API commands for execution.
client- Set of plug-ins which validate arguments and options that are forwarded to the IdM server for execution.
installer- Set of plug-ins which are specific to the installation process.
updates- Set of plug-ins which are specific to the updating process.
