Red Hat Enterprise Linux 9

Using IdM API

Using IdM API with Python scripts

Last Updated: 2023-11-08

Red Hat Enterprise Linux 9 Using IdM API
Using IdM API with Python scripts
Legal Notice
Copyright © 2023 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift,
Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States
and other countries.

Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.

Java ® is a registered trademark of Oracle and/or its affiliates.

XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.

MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.

Node.js ® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the
official Joyent Node.js open source or commercial project.

The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other
countries and are used with the OpenStack Foundation's permission. We are not affiliated with,
endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Abstract
The IdM API contains examples for using various types of request. Administrators and developers
can use the IdM API to write custom scripts in Python to integrate IdM with third-party applications.
 Table of Contents

Table of Contents
. . . . . . . . . .OPEN
MAKING . . . . . . SOURCE
. . . . . . . . . .MORE
. . . . . . .INCLUSIVE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . . . . . . . . .

. . . . . . . . . . . . . FEEDBACK
PROVIDING . . . . . . . . . . . . ON
. . . .RED
. . . . .HAT
. . . . .DOCUMENTATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . .

. . . . . . . . . . . 1.. .INTRODUCTION
CHAPTER . . . . . . . . . . . . . . . . . TO
. . . .IDM
. . . . API
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . . . .

.CHAPTER
. . . . . . . . . . 2.
. . BASICS
. . . . . . . . .OF
. . . IDM
. . . . .API
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. . . . . . . . . . . . .
2.1. INITIALIZING IDM API 6
2.2. RUNNING IDM API COMMANDS 6
2.3. IDM API COMMANDS OUTPUT STRUCTURE 7
2.4. LISTING THE IDM API COMMANDS AND PARAMETERS 8
2.5. USING BATCHES FOR EXECUTING IDM API COMMANDS 9
2.6. IDM API CONTEXT 10

. . . . . . . . . . . 3.
CHAPTER . . IDM
. . . . .API
. . . .AND
. . . . . IDM
. . . . .CLI
. . . .COMMANDS
. . . . . . . . . . . . . COMPARISON
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11. . . . . . . . . . . . .

.CHAPTER
. . . . . . . . . . 4.
. . .IDM
. . . . API
. . . . EXAMPLE
. . . . . . . . . . .SCENARIOS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
..............
4.1. MANAGING USERS WITH IDM API COMMANDS 12
4.2. MANAGING GROUPS WITH IDM API COMMANDS 13
4.3. MANAGING ACCESS CONTROL WITH IDM API COMMANDS 15

1
Red Hat Enterprise Linux 9 Using IdM API

2
 MAKING OPEN SOURCE MORE INCLUSIVE

MAKING OPEN SOURCE MORE INCLUSIVE

Red Hat is committed to replacing problematic language in our code, documentation, and web
properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the
enormity of this endeavor, these changes will be implemented gradually over several upcoming releases.
For more details, see our CTO Chris Wright’s message .

3
Red Hat Enterprise Linux 9 Using IdM API

PROVIDING FEEDBACK ON RED HAT DOCUMENTATION

We appreciate your feedback on our documentation. Let us know how we can improve it.

Submitting feedback through Jira (account required)

1. Log in to the Jira website.

2. Click Create in the top navigation bar

3. Enter a descriptive title in the Summary field.

4. Enter your suggestion for improvement in the Description field. Include links to the relevant
parts of the documentation.

5. Click Create at the bottom of the dialogue.

4
 CHAPTER 1. INTRODUCTION TO IDM API

CHAPTER 1. INTRODUCTION TO IDM API

You can access the services of the Red Hat Identity Management with command-line and web-based
interfaces. With the Identity Management API, you can interact with Identity Management services
through the third-party applications and scripts that are written in Python.

The Identity Management API has the JavaScript Object Notation Remote Procedure Call (JSON-RPC)
interface. To use the automation for various important parts, access the Identity Management API
through Python. For example, you can retrieve metadata from the server with all available commands.

5
Red Hat Enterprise Linux 9 Using IdM API

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

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()

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()

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

IdM API context

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:

6
 CHAPTER 2. BASICS OF IDM API

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.Command commands, 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 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")

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": ["[email protected]"],

7
Red Hat Enterprise Linux 9 Using IdM API

"krbprincipalname": [ipapython.kerberos.Principal("[email protected]")],
"loginshell": ["/bin/sh"],
"initials": ["ab"],
"uid": ["test"],
"uidnumber": ["1445000004"],
"sn": ["b"],
"krbcanonicalname": [ipapython.kerberos.Principal("[email protected]")],
"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

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

api.Command.command_show("user_add")

The result for this command is as follows:

{
"result": {
"name": "user_add",
"version": "1",

8
 CHAPTER 2. BASICS OF IDM API

"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,
}

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")

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

9
Red Hat Enterprise Linux 9 Using IdM API

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.

10
 CHAPTER 3. IDM API AND IDM CLI COMMANDS COMPARISON

CHAPTER 3. IDM API AND IDM CLI COMMANDS COMPARISON

You can use the IdM API commands in the Python interactive console. The IdM API commands are
different from the ipa tool commands.

IdM CLI and IdM API commands difference

Command naming structure

The ipa CLI commands use the hyphen, as in user-add, but IdM API commands use the underscore
instead, as in user_add.
Parameter naming
The parameters are different for IdM CLI commands and IdM API commands. For example, the IdM
CLI user-add command has a parameter first but the IdM API user_add command has a parameter
givenname.
Date format
The following date formats are available for IdM CLI:

%Y%m%d%H%M%SZ

%Y-%m-%dT%H:%M:%SZ

%Y-%m-%dT%H:%MZ

%Y-%m-%dZ

%Y-%m-%d %H:%M:%SZ

%Y-%m-%d %H:%MZ
Additionally, the IdM API can use the Python built-in class datetime.

Useful CLI tools

The console starts an interactive Python console, which you can use to run IdM API commands.

The help command shows description of the topics and the commands and includes various
examples.

The show-mapping command shows the mapping between CLI parameter names and LDAP
attributes.

11
Red Hat Enterprise Linux 9 Using IdM API

CHAPTER 4. IDM API EXAMPLE SCENARIOS

The following examples provide you with the common scenarios of using IdM API commands.

4.1. MANAGING USERS WITH IDM API COMMANDS

The examples below show common scenarios of how you can manage IdM users with the IdM API
commands.

Examples of managing IdM users with IdM API commands

Creating an IdM user

In this example, you create an IdM user with the username exampleuser and the supported user
one-time password (OTP) authentication.

api.Command.user_add("exampleuser", givenname="Example", sn="User",

ipauserauthtype="otp")

Showing an IdM user information

In this example, you display all available information about the IdM user exampleuser.

api.Command.user_show("exampleuser", all=True)

Modifying an IdM user

In this example, you change the e-mail address for the IdM user exampleuser.

api.Command.user_mod("exampleuser", mail="[email protected]")

Searching for an IdM user

In this example, you search for all IdM users that match exampleuser in the IdM group admins.

api.Command.user_find(criteria="exampleuser", in_group="admins")

Deleting an IdM user

In this example, you delete the IdM user exampleuser.

api.Command.user_del("exampleuser")

To restore the user in future, use the preserve option. If you use this option, you can restore the user
with the user_undel command.

Adding and removing a certificate for an IdM user

You can add or remove Base64 encoded certificate for a user with the user_add_cert and
user_remove_cert commands. In this example, you add a certificate for a user exampleuser.

args = ["exampleuser"]
kw = {
"usercertificate": """

MIICYzCCAcygAwIBAgIBADANBgkqhkiG9w0BAQUFADAuMQswCQYDVQQGEwJVUzEMMAoGA

12
 CHAPTER 4. IDM API EXAMPLE SCENARIOS

1UEC

hMDSUJNMREwDwYDVQQLEwhMb2NhbCBDQTAeFw05OTEyMjIwNTAwMDBaFw0wMDEyMjM
wNDU5NT

laMC4xCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNJQk0xETAPBgNVBAsTCExvY2FsIENBMIGf
MA0

GCSqGSIb3DQEBATOPA4GNADCBiQKBgQD2bZEo7xGaX2/0GHkrNFZvlxBou9v1Jmt/PDiTMPve

8r9FeJAQ0QdvFST/0JPQYD20rH0bimdDLgNdNynmyRoS2S/IInfpmf69iyc2G0TPyRvmHIiOZ

bdCd+YBHQi1adkj17NDcWj6S14tVurFX73zx0sNoMS79q3tuXKrDsxeuwIDAQABo4GQMIGNME

sGCVUdDwGG+EIBDQQ+EzxHZW5lcmF0ZWQgYnkgdGhlIFNlY3VyZVdheSBTZWN1cml0eSBTZ
XJ

2ZXIgZm9yIE9TLzM5MCAoUkFDRikwDgYDVR0PAQH/BAQDAgAGMA8GA1UdEwEB/wQFMAMB
Af8w

HQYDVR0OBBYEFJ3+ocRyCTJw067dLSwr/nalx6YMMA0GCSqGSIb3DQEBBQUAA4GBAMaQzt
+za
j1GU77yzlr8iiMBXgdQrwsZZWJo5exnAucJAEYQZmOfyLiMD6oYq+ZnfvM0n8G/Y79q8nhwvu
xpYOnRSAXFp6xSkrIOeZtJMY1h00LKp/JX3Ng1svZ2agE126JHsQ0bhzN5TKsYfbwfTwfjdWA
Gy6Vf1nYi/rO+ryMO
"""
}

api.Command.user_add_cert(*args, **kw)

Enabling and disabling an IdM user

You can enable or disable an IdM user with the user_enable and user_disable commands. In this
example, you disable the IdM user exampleuser.

api.Command.user_disable("exampleuser")

4.2. MANAGING GROUPS WITH IDM API COMMANDS

The examples below show common scenarios of how you can manage IdM groups with the IdM API
commands.

Examples of managing IdM users with IdM API commands

Creating an IdM group

In this example, you create an IdM group developers, with a specified Group ID number.

api.Command.group_add("developers", gidnumber=500, description="Developers")

Adding a user as a member to an IdM group

In this example, you add the admin user to the developers group.

api.Command.group_add_member("developers", user="admin")

13
Red Hat Enterprise Linux 9 Using IdM API

Adding a service as a member to an IdM group

In this example, you add the HTTP/server.ipa.test service to the developers group.

api.Command.group_add_member("developers", service="HTTP/server.ipa.test")

Adding a group as a subgroup to an IdM group

In this example, you add another group, admins, to the developers group.

api.Command.group_add_member("developers", group="admins")

Adding IdM group managers

In this example, you add the bob user as a group manager for the developers group.

api.Command.group_add_member_manager("developers", user="bob")

Finding an IdM group

You can search for an IdM group using various parameters. In this example, you find all groups that
the user bob is managing.

api.Command.group_find(membermanager_user="bob")

Displaying IdM group information

In this example, you display group information about the developers group, without the members
list.

api.Command.group_show("developers", no_members=True)

Modifying an IdM group

In this example, you convert a non-POSIX group testgroup to a POSIX group.

api.Command.group_mod("testgroup", posix=True)

Removing members from an IdM group

In this example, you remove the admin user from the developers group.

api.Command.group_remove_member("developers", user="admin")

Removing IdM group managers

In this example, you remove the user bob as a manager from the developers group.

api.Command.group_remove_member_manager("developers", user="bob")

Removing an IdM group

In this example, you remove the developers group.

api.Command.group_del("developers")

14
 CHAPTER 4. IDM API EXAMPLE SCENARIOS

4.3. MANAGING ACCESS CONTROL WITH IDM API COMMANDS

The examples below show common scenarios of how you can manage access control with the IdM API
commands.

Examples of managing access control with IdM API commands

Adding a permission for creating users

In this example, you add a permission for creating users.

api.Command.permission_add("Create users", ipapermright='add', type='user')

Adding a permission for managing group membership

In this example, you add a permission for adding users to groups.

api.Command.permission_add("Manage group membership", ipapermright='write', type='group',

attrs="member")

Adding a privilege for the user creation process

In this example, you add a privilege for creating users, adding them to groups, and managing user
certificates.

api.Command.permission_add("Create users", ipapermright='add', type='user')

api.Command.permission_add("Manage group membership", ipapermright='write', type='group',
attrs="member")
api.Command.permission_add("Manage User certificates", ipapermright='write', type='user',
attrs='usercertificate')

api.Command.privilege_add("User creation")
api.Command.privilege_add_permission("User creation", permission="Create users")
api.Command.privilege_add_permission("User creation", permission="Manage group
membership")
api.Command.privilege_add_permission("User creation", permission="Manage User certificates")

Adding a role using a privilege

In this example, you add a role using the privilege created in the previous example.

api.Command.role_add("usermanager", description="Users manager")

api.Command.role_add_privilege("usermanager", privilege="User creation")

Assigning a role to a user

In this example, you assign the usermanager role to the user bob.

api.Command.role_add_member("usermanager", user="bob")

Assigning a role to a group

In this example, you assign the usermanager role to the managers group.

api.Command.role_add_member("usermanager", group="managers")

15
Red Hat Enterprise Linux 9 Using IdM API

16