Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 2. Basics of IdM API

You can use the IdM API to automate access to your IdM environment with custom scripts. This reduces manual effort and ensures consistent identity management across your infrastructure.

2.1. Initializing IdM API
Link kopieren

To use the IdM API, first initialize it in your environment. Proper initialization establishes the connection to IdM services and enables your scripts to execute API commands.

Prerequisites

  • The IdM server or IdM client package is installed.
  • A valid Kerberos ticket is issued.

Procedure

  1. 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()
    Copy to Clipboard Toggle word wrap

  2. 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()
    Copy to Clipboard Toggle word wrap
    • 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.

2.2. Running IdM API commands
Link kopieren

You can run IdM API commands within your script to automate identity management tasks. Use the api.Command structure to execute commands and retrieve information about users, groups, and other IdM objects.

Prerequisites

Procedure

  • To list the information about a user, include the following code in your script: 

    api.Command.user_show("user_name", no_members=True, all=True)
    Copy to Clipboard Toggle word wrap

    In this example, you also pass arguments and options to the command user_show.

2.3. IdM API commands output structure
Link kopieren

Each IdM API command returns output in four sections. Understanding this structure helps you parse command results and handle responses in your automation scripts.

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 ipa tool 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")
Copy to Clipboard Toggle word wrap

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"',
}
Copy to Clipboard Toggle word wrap

2.4. Listing the IdM API commands and parameters
Link kopieren

You can list information about IdM API commands and their parameters by using command_show and param_show. This helps you discover available commands and understand the required inputs for your scripts.

Prerequisites

Procedure

  1. To display information about user_add command, execute the following code: 

    api.Command.command_show("user_add")
    Copy to Clipboard Toggle word wrap

    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,
}
    Copy to Clipboard Toggle word wrap

  2. To display information about the givenname parameter for the user_add command, execute the following code: 

    api.Command.param_show("user_add", name="givenname")
    Copy to Clipboard Toggle word wrap

    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,
}
    Copy to Clipboard Toggle word wrap

2.5. Using batches for executing IdM API commands
Link kopieren

You can execute multiple IdM API commands with a single call by using the batch command. Batching improves performance and reduces network overhead when performing bulk operations such as creating multiple users.

Prerequisites

Procedure

  • To create 100 IdM users in one batch, include the following code in 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)
    Copy to Clipboard Toggle word wrap

2.6. IdM API context
Link kopieren

IdM API context determines which plug-ins the API uses. Selecting the correct context ensures your scripts use the appropriate validation and execution methods for your environment.

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.
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red HatNach oben