Using IdM API

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.

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.

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

Copy to Clipboard Toggle word wrap

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)

Copy to Clipboard Toggle word wrap

Modifying an IdM user

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

api.Command.user_mod("exampleuser", mail="exampleuser@example.org")

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

Deleting an IdM user

In this example, you delete the IdM user exampleuser.

api.Command.user_del("exampleuser")

Copy to Clipboard Toggle word wrap

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": """
      MIICYzCCAcygAwIBAgIBADANBgkqhkiG9w0BAQUFADAuMQswCQYDVQQGEwJVUzEMMAoGA1UEC
      hMDSUJNMREwDwYDVQQLEwhMb2NhbCBDQTAeFw05OTEyMjIwNTAwMDBaFw0wMDEyMjMwNDU5NT
      laMC4xCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNJQk0xETAPBgNVBAsTCExvY2FsIENBMIGfMA0
      GCSqGSIb3DQEBATOPA4GNADCBiQKBgQD2bZEo7xGaX2/0GHkrNFZvlxBou9v1Jmt/PDiTMPve
      8r9FeJAQ0QdvFST/0JPQYD20rH0bimdDLgNdNynmyRoS2S/IInfpmf69iyc2G0TPyRvmHIiOZ
      bdCd+YBHQi1adkj17NDcWj6S14tVurFX73zx0sNoMS79q3tuXKrDsxeuwIDAQABo4GQMIGNME
      sGCVUdDwGG+EIBDQQ+EzxHZW5lcmF0ZWQgYnkgdGhlIFNlY3VyZVdheSBTZWN1cml0eSBTZXJ
      2ZXIgZm9yIE9TLzM5MCAoUkFDRikwDgYDVR0PAQH/BAQDAgAGMA8GA1UdEwEB/wQFMAMBAf8w
      HQYDVR0OBBYEFJ3+ocRyCTJw067dLSwr/nalx6YMMA0GCSqGSIb3DQEBBQUAA4GBAMaQzt+za
      j1GU77yzlr8iiMBXgdQrwsZZWJo5exnAucJAEYQZmOfyLiMD6oYq+ZnfvM0n8G/Y79q8nhwvu
      xpYOnRSAXFp6xSkrIOeZtJMY1h00LKp/JX3Ng1svZ2agE126JHsQ0bhzN5TKsYfbwfTwfjdWA
      Gy6Vf1nYi/rO+ryMO
    """
}

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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)

Copy to Clipboard Toggle word wrap

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)

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

Removing an IdM group

In this example, you remove the developers group.

api.Command.group_del("developers")

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

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

Copy to Clipboard Toggle word wrap

Examples of managing sudo rules with IdM API commands

Creating a sudo rule

In this example, you create a sudo rule that holds time change commands.

api.Command.sudorule_add("timechange")

Copy to Clipboard Toggle word wrap

Creating a sudo command

In this example, you create the date sudo command.

api.Command.sudocmd_add("/usr/bin/date")

Copy to Clipboard Toggle word wrap

Attaching a sudo command to a sudo rule

In this example, you attach the date sudo command to the timechange sudo rule.

api.Command.sudorule_add_allow_command("timechange", sudocmd="/usr/bin/date")

Copy to Clipboard Toggle word wrap

Creating and attaching groups of sudo commands

In this example, you create multiple sudo commands, add them to a newly created timecmds sudo command group, and attach the group to the timechange sudo rule.

api.Command.sudocmd_add("/usr/bin/date")
api.Command.sudocmd_add("/usr/bin/timedatectl")
api.Command.sudocmd_add("/usr/sbin/hwclock")
api.Command.sudocmdgroup_add("timecmds")
api.Command.sudocmdgroup_add_member("timecmds", sudocmd="/usr/bin/date")
api.Command.sudocmdgroup_add_member("timecmds", sudocmd="/usr/bin/timedatectl")
api.Command.sudocmdgroup_add_member("timecmds", sudocmd="/usr/sbin/hwclock")
api.Command.sudorule_add_allow_command("timechange", sudocmdgroup="timecmds")

Copy to Clipboard Toggle word wrap

Denying sudo commands

In this example, you deny the rm command to be run as sudo.

api.Command.sudocmd_add("/usr/bin/rm")
api.Command.sudorule_add_deny_command("timechange", sudocmd="/usr/bin/rm")

Copy to Clipboard Toggle word wrap

Adding a user to a sudo rule

In this example, you add the user bob to the timechange sudo rule.

api.Command.sudorule_add_user("timechange", user="bob")

Copy to Clipboard Toggle word wrap

Making a sudo rule available only for a specified host

In this example, you restrict the timechange rule to be available only for the client.ipa.test host.

api.Command.sudorule_add_host("timechange", host="client.ipa.test")

Copy to Clipboard Toggle word wrap

Setting sudo rules to be run as a different user

By default, sudo rules are run as root. In this example, you set the timechange sudo rule to be run as the alice user instead.

api.Command.sudorule_add_runasuser("timechange", user="alice")

Copy to Clipboard Toggle word wrap

Setting sudo rules to be run as a group

In this example, you set the timechange sudo rule to be run as the sysadmins group.

api.Command.sudorule_add_runasgroup("timechange", group="sysadmins")

Copy to Clipboard Toggle word wrap

Setting a sudo option for a sudo rule

In this example, you set a sudo option for the timechange sudo rule.

api.Command.sudorule_add_option("timechange", ipasudoopt="logfile='/var/log/timechange_log'")

Copy to Clipboard Toggle word wrap

Enabling a sudo rule

In this example, you enable the timechange sudo rule.

api.Command.sudorule_enable("timechange")

Copy to Clipboard Toggle word wrap

Disabling a sudo rule

In this example, you disable the timechange sudo rule.

api.Command.sudorule_disable("timechange")

Copy to Clipboard Toggle word wrap

Examples of managing HBAC with IdM API commands

Creating an HBAC rule

In this example, you create a base rule that will handle SSH service access.

api.Command.hbacrule_add("sshd_rule")

Copy to Clipboard Toggle word wrap

Adding a user to an HBAC rule

In this example, you add the user john to the sshd_rule HBAC rule.

api.Command.hbacrule_add_user("sshd_rule", user="john")

Copy to Clipboard Toggle word wrap

Adding a group to an HBAC rule

In this example, you add the group developers to the sshd_rule HBAC rule.

api.Command.hbacrule_add_user("sshd_rule", group="developers")

Copy to Clipboard Toggle word wrap

Removing a user from an HBAC rule

In this example, you remove the user john from the sshd_rule HBAC rule.

api.Command.hbacrule_remove_user("sshd_rule", user="john")

Copy to Clipboard Toggle word wrap

Registering a new target HBAC service

You must register a target service before you can attach it to an HBAC rule. In this example, you register the chronyd service.

api.Command.hbacsvc_add("chronyd")

Copy to Clipboard Toggle word wrap

Attaching a registered service to an HBAC rule

In this example, you attach the sshd service to the sshd_rule HBAC rule. This service is registered in IPA by default, so there is no need to register it using hbacsvc_add beforehand.

api.Command.hbacrule_add_service("sshd_rule", hbacsvc="sshd")

Copy to Clipboard Toggle word wrap

Adding a host to an HBAC rule

In this example, you add workstations host group to the sshd_rule HBAC rule.

api.Command.hbacrule_add_host("sshd_rule", hostgroup="workstations")

Copy to Clipboard Toggle word wrap

Testing an HBAC rule

In this example, you use the sshd_rule HBAC rule against the workstation.ipa.test host. It targets the service sshd that comes from the user john.

api.Command.hbactest(user="john", targethost="workstation.ipa.test", service="sshd", rules="sshd_rule")

Copy to Clipboard Toggle word wrap

Enabling an HBAC rule

In this example, you enable the sshd_rule HBAC rule.

api.Command.hbacrule_enable("sshd_rule")

Copy to Clipboard Toggle word wrap

Disabling an HBAC rule

In this example, you disable the sshd_rule HBAC rule.

api.Command.hbacrule_disable("sshd_rule")

Copy to Clipboard Toggle word wrap