Runbook Permissions
How to grant/deny access to certain runbooks.
Last updated
How to grant/deny access to certain runbooks.
Last updated
This addresses how to grant/deny access to certain runbooks in an Azure tenant. If you are looking for answers regarding which MS Graph API permissions are needed to run a certain action as a runbook, please have a look at our requirements.
"Runbook Permissions" define the visibility of runbooks for certain users. Certain runbooks can also be blocked/hidden globally.
Like the Runbook Customizations, defining these permissions is done by giving a JSON-formatted configuration as an RealmJoin admin in RealmJoin's web portal at https://portal.realmjoin.com/settings/runbooks-permissions .
We will give a short description of the syntax and then build a full example piece by piece. Feel free to directly go to the full sample and start from there.
Runbooks are referenced by their names as seen in the Azure Automation Account, e.g. rjgit-group_general_remove-group.
Wildcards ('*') can be used to match multiple runbooks. Multiple wildcards can be used in the same string, e.g. rjgit-*_security_*. This would all of the following examples:
rjgit-org_security_list-inactive-users
rjgit-device_security_enable-or-disable-device
The prefix rjgit- denotes runbooks that are imported from our piblic GitHub repository. Customer-specific runbooks have no prefix, e.g. user_userinfo_custom-runbook
Entra ID groups will be referenced using their Object ID, like 91688d11-9a34-42cd-8d1e-ce617d6c1234. Currently, only security groups can be used.
We will build a full configuration example piece by piece.
A JSON configuration consists of multiple sections, but all sections are optional and can be omitted.
It is allowed to add comments using the "//" prefix.
This section contains a list of runbooks allowed to be used. If this section is omitted, all runbooks are enabled/allowed by default.
If you define this section, then only runbooks mentioned in this section will be usable by any role / support and admin.
Allow only certain, individual runbooks by giving their full name
rjgit-group_general_remove-group
Allow all device related runbooks from our shared repository
rjgit-device_*
Allow all shared user runbooks
rjgit-user_*
Allow all customer specific (local), user related runbooks
user_*
This implicitely leaves out many group- and all org- based runbooks. Be aware.
A list of runbook that are globally disabled / forbidden. If this section is omitted or empty, all enabled runbooks (given via EnabledRunbookPatterns) are usable.
Entries in this section take priority over entries in EnabledRunbookPatterns - the runbooks will be hidden/not be usable for anyone in this tenant.
We will reuse the EnabledRunbookPatterns section from before.
Disable all shared (rjgit-) runbooks in the security category.
In this section you can assign a list of runbooks to an Entra ID group. This allows to define multiple support/operator roles in your tenant.
If this section is omitted, all RealmJoin support and administrators have access to all runbooks given in the previous sections.
If enabled, all users not belonging to a role will not see any runbooks.
Continuing with what we have, let us create a device-support role DeviceAdmin and a user support role UserAdmin.
We will apply those roles to multiple Entra ID groups and for each role give a list of allowed runbooks. Be aware - this will restrict the user support role to only a small set of runbooks.
Let us add comments ("//") next to the group's object id that help the reader by giving the Entra ID group names.
Now the UserAdmin role can:
assign licenses to all users in your tenant
modify email-addresses of all users in your tenant
The DeviceAdmin role can
wipe any device in your tenant
Perhaps you have some crucial VIP users. It should not be possible for just any support staff to erase a VIP's device or modify a VIP's email address. We can use "targeting" to restrict roles on critical users to dedicated teams.
"Devices" will be targeted by their primary/assigned user but not the device object in Entra ID. This allows to stick to a purely user-based group model.
We assume, Entra ID groups exist that contain critical VIP users. Using this section, we can carefully scope some more critical roles and runbooks for these specific Entra ID groups (targets).
Obviously, if you omit this section, all users/groups/devices in your tenant are treated as equals.
If you define TargetEntityGroups it should not have any impact on any other group not mentioned in the section.
Assume group 0000c0af-c217-41e9-b790-3043788f0000 is our group of VIP users.
We introduce a new Entra ID group 4444c0af-c217-41e9-b790-3043788f4444 containing supporting staff that have been approved to administrate VIP users. These supporting staff should also have all other basic support permissions, so we will add them to the existing roles.
"Restricting" a role will not grant new roles to a supporter.
This section contains a list of runbooks that will be flagged as "schedulable". RealmJoin Port will allow to assign / manage schedules for these runbooks. See Runbook Scheduling.
The following example describes the default behaviour if SchedulingEnabledRunbookPatterns are not defined:
This section contains a list of runbooks that will be blacklisted from being flagged as "schedulable". RealmJoin Port will not allow to assign / manage schedules for these runbooks. See Runbook Scheduling.
A runbook present in both SchedulingEnabledRunbookPatterns and SchedulingDisabledRunbookPatterns will not be schedulable.
By default no runbooks are blacklisted. The following example just demonstrates the syntax: