diff --git a/doc/api/group_management.md b/doc/api/group_management.md new file mode 100644 index 000000000..38fe54ff0 --- /dev/null +++ b/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") +``` \ No newline at end of file diff --git a/doc/api/guides.rst b/doc/api/guides.rst index 8c0a3be4b..f474f3f99 100644 --- a/doc/api/guides.rst +++ b/doc/api/guides.rst @@ -4,4 +4,7 @@ IPA API Guides :maxdepth: 1 basic_usage.md - user_management.md \ No newline at end of file + user_management.md + group_management.md + hbac_guide.md + sudorule_management.md \ No newline at end of file diff --git a/doc/api/hbac_guide.md b/doc/api/hbac_guide.md new file mode 100644 index 000000000..6d25ec536 --- /dev/null +++ b/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") +``` \ No newline at end of file diff --git a/doc/api/sudorule_management.md b/doc/api/sudorule_management.md new file mode 100644 index 000000000..2d7312c6d --- /dev/null +++ b/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") +``` \ No newline at end of file