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

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="exampleuser@example.org")

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

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

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

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

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

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

Creating a sudo command

In this example, you create the date sudo command.

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

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

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

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

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

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

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

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

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

Enabling a sudo rule

In this example, you enable the timechange sudo rule.

api.Command.sudorule_enable("timechange")

Disabling a sudo rule

In this example, you disable the timechange sudo rule.

api.Command.sudorule_disable("timechange")

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

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

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

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

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

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

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

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

Enabling an HBAC rule

In this example, you enable the sshd_rule HBAC rule.

api.Command.hbacrule_enable("sshd_rule")

Disabling an HBAC rule

In this example, you disable the sshd_rule HBAC rule.

api.Command.hbacrule_disable("sshd_rule")