API doc: add usage guides for groups, HBAC and sudo rules

Include guides with examples for groups, HBAC and sudo rules management.
These cover most of available commands related to these topics.

Signed-off-by: Antonio Torres <antorres@redhat.com>
Reviewed-By: Rob Crittenden <rcritten@redhat.com>

doc/api/group_management.md

@@ -0,0 +1,98 @@
+# Group management examples
+
+This guide provides various examples on how to perform common tasks related to
+group management in a IPA environment making use of the provided API.
+
+- [Group management examples](#group-management-examples)
+  - [Creating a group](#creating-a-group)
+  - [Adding members to a group](#adding-members-to-a-group)
+  - [Adding group managers](#adding-group-managers)
+  - [Finding a group](#finding-a-group)
+  - [Showing group information](#showing-group-information)
+  - [Modifying a group](#modifying-a-group)
+  - [Removing members from a group](#removing-members-from-a-group)
+  - [Removing group managers](#removing-group-managers)
+  - [Removing a group](#removing-a-group)
+
+
+## Creating a group
+
+Create a group for developers, with an specific Group ID number.
+
+```python
+api.Command.group_add("developers", gidnumber=500, description="Developers")
+```
+
+## Adding members to a group
+
+Add the admin user to the `developers` group.
+
+```python
+api.Command.group_add_member("developers", user="admin")
+```
+
+Apart from users, groups can also have services and groups as members:
+
+```python
+api.Command.group_add_member("developers", service="HTTP/server.ipa.test")
+```
+
+```python
+api.Command.group_add_member("developers", group="admins")
+```
+
+## Adding group managers
+
+Add `bob` as the group manager for `developers` group.
+
+```python
+api.Command.group_add_member_manager("developers", user="bob")
+```
+
+## Finding a group
+
+Find all groups managed by `bob`.
+
+```python
+api.Command.group_find(membermanager_user="bob")
+```
+
+## Showing group information
+
+Show information about the `developers` group, excluding the members list.
+
+```python
+api.Command.group_show("developers", no_members=True)
+```
+
+## Modifying a group
+
+Convert a non-POSIX group to POSIX:
+
+```python
+api.Command.group_mod("testgroup", posix=True)
+```
+
+## Removing members from a group
+
+Remove the admin user to the `developers` group.
+
+```python
+api.Command.group_remove_member("developers", user="admin")
+```
+
+## Removing group managers
+
+Remove `bob` as the group manager from `developers` group.
+
+```python
+api.Command.group_remove_member_manager("developers", user="bob")
+```
+
+## Removing a group
+
+Remove the `developers` group.
+
+```python
+api.Command.group_del("developers")
+```

doc/api/guides.rst

@@ -4,4 +4,7 @@ IPA API Guides
    :maxdepth: 1
 
    basic_usage.md
-   user_management.md
+   user_management.md
+   group_management.md
+   hbac_guide.md
+   sudorule_management.md

doc/api/hbac_guide.md

@@ -0,0 +1,89 @@
+# Host-based Access Control (HBAC) Examples
+
+HBAC rules allow to define policies to control how hosts and services are
+accessed based on the user, user's group or host that is attempting to access.
+
+- [Host-based Access Control (HBAC) Examples](#host-based-access-control-hbac-examples)
+  - [Creating an HBAC rule](#creating-an-hbac-rule)
+  - [Managing members of a HBAC rule](#managing-members-of-a-hbac-rule)
+  - [Managing targets of a HBAC rule](#managing-targets-of-a-hbac-rule)
+  - [Testing a HBAC rule](#testing-a-hbac-rule)
+  - [Enabling and disabling HBAC rules](#enabling-and-disabling-hbac-rules)
+
+
+## Creating an HBAC rule
+
+Create a base rule that will handle SSH service access.
+
+```python
+api.Command.hbacrule_add("sshd_rule")
+```
+
+## Managing members of a HBAC rule
+
+Add user `john` to the previously created HBAC rule.
+
+```python
+api.Command.hbacrule_add_user("sshd_rule", user="john")
+```
+
+Additionally, you can set access based on groups:
+
+```python
+api.Command.hbacrule_add_user("sshd_rule", group="developers")
+```
+
+Remove user `john` from the HBAC rule.
+
+```python
+api.Command.hbacrule_remove_user("sshd_rule", user="john")
+```
+
+## Managing targets of a HBAC rule
+
+After we have created the rule and set the members, targets must be registered
+before being added to the rule.
+
+Adding a new HBAC service.
+
+```python
+api.Command.hbacsvc_add("chronyd")
+```
+
+Services must be attached to rules. Attach the sshd service to the previously
+created rule. This service is registered in IPA by default, so there's no need
+to add it with `hbacsvc_add` before.
+
+```python
+api.Command.hbacrule_add_service("sshd_rule", hbacsvc="sshd")
+```
+
+Hosts can be added as targets as well. Allow the SSH service to be accessed only in
+the hosts part of the `workstations` hostgroup.
+
+```python
+api.Command.hbacrule_add_host("sshd_rule", hostgroup="workstations")
+```
+
+## Testing a HBAC rule
+
+Simulate the use of the rule we previously created, against the host
+`workstation.ipa.test`, the service `sshd` coming from the user `john`.
+
+```python
+api.Command.hbactest(user="john", targethost="workstation.ipa.test", service="sshd", rules="sshd_rule")
+```
+
+## Enabling and disabling HBAC rules
+
+Enable a HBAC rule.
+
+```python
+api.Command.hbacrule_enable("sshd_rule")
+```
+
+Disable a HBAC rule.
+
+```python
+api.Command.hbacrule_disable("sshd_rule")
+```

doc/api/sudorule_management.md

@@ -0,0 +1,105 @@
+# Sudo rules management examples
+
+Sudo rules provide the system administrator a way to delegate privileges to
+certain users in order to perform commands either as root or as another user.
+
+- [Sudo rules management examples](#sudo-rules-management-examples)
+  - [Creating a sudo rule](#creating-a-sudo-rule)
+  - [Managing sudo commands](#managing-sudo-commands)
+  - [Adding users and hosts to sudo rules](#adding-users-and-hosts-to-sudo-rules)
+  - [Setting "run as" for sudo rules](#setting-run-as-for-sudo-rules)
+  - [Managing sudo options](#managing-sudo-options)
+  - [Enabling and disabling sudo rule](#enabling-and-disabling-sudo-rule)
+
+
+## Creating a sudo rule
+
+Create a sudo rule that will hold time change commands.
+
+```python
+api.Command.sudorule_add("timechange")
+```
+
+## Managing sudo commands
+
+Sudo rules must be filled with sudo commands. Create one for `date`.
+
+```python
+api.Command.sudocmd_add("/usr/bin/date")
+```
+
+Then, attach the sudo command to the sudo rule.
+
+```python
+api.Command.sudorule_add_allow_command("timechange", sudocmd="/usr/bin/date")
+```
+
+Alternatively, groups of sudo commands can be created and attached to the rule
+in the same manner.
+
+```python
+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")
+```
+
+Commands can be denied as well. Deny the `rm` command to be run as sudo.
+
+```python
+api.Command.sudocmd_add("/usr/bin/rm")
+api.Command.sudorule_add_deny_command("timechange", sudocmd="/usr/bin/rm")
+```
+
+## Adding users and hosts to sudo rules
+
+Add the user `bob` to the previously created rule.
+
+```python
+api.Command.sudorule_add_user("timechange", user="bob")
+```
+
+Restrict the rule to only be available for the `client.ipa.test` host.
+
+```python
+api.Command.sudorule_add_host("timechange", host="client.ipa.test")
+```
+
+## Setting "run as" for sudo rules
+
+While sudo rules are run as root by default, a different "run as" can be
+configured, both for user and group rights.
+
+```python
+api.Command.sudorule_add_runasuser("timechange", user="alice")
+```
+
+```python
+api.Command.sudorule_add_runasgroup("timechange", group="sysadmins")
+```
+
+## Managing sudo options
+
+Set a sudo option for the `timechange` sudo rule.
+
+```python
+api.Command.sudorule_add_option("timechange", ipasudoopt="logfile='/var/log/timechange_log'")
+```
+
+## Enabling and disabling sudo rule
+
+Enable a sudo sule.
+
+```python
+api.Command.sudorule_enable("timechange")
+```
+
+Disable a sudo sule.
+
+```python
+api.Command.sudorule_disable("timechange")
+```