Command Authorization

Command Authorization

PoshBot includes a simple yet effect Role Based Access Control (RBAC) model that you can apply to your bot commands. While it would be great if everyone could execute everything, many commands in your ChatOps environment may be sensitive in nature or particularly powerful, requiring an extra degree of control over who can execute what.

PoshBot uses the concept of permissions, roles, and groups to optionally control execution of commands. It is the union of these constructs and the user that secures the command.

Permissions

A PoshBot command can have one or more permissions attached to them. A permission is the base unit used for security. Permissions are nothing more than tokens that are applied to commands. These permissions are then collected into roles. Permissions available in a plugin are defined in the PrivateData section of the PowerShell module manifest for the plugin. When specifying the permissions inside the module manifest, an array of strings and/or hashtables can be used. When using a hashtable, a Name key must be used. The Description key is optional but recommended.

MyPlugin.psd1

@{
    # Other properties omitted for brevity
    # ...
    #
    PrivateData = @{
        Permissions = @(
            'command1'
            'command2'
            @{
                Name = 'Read'
                Description = 'Can execute all Get-* commands of the plugin'
            }
            @{
                Name = 'Write'
                Description = 'Can execute all New-*, Set-*, and Remove-* commands of the plugin'
            }
        )
    }
}

When defining permissions within the module manifest, you only need to specify a name like Read. But what if another plugin also has a permission with the name Read?. How will you tell them apart? The answer is that PoshBot namespaces permissions. The plugin (module) above is called MyPlugin. This would make the fully qualified permission name MyPlugin:Read or MyPlugin:Write. This fully qualified name is what is used throughout PoshBot. Another plugin called Network may also include Read and Write permissions but the fully qualified name for these permissions would be Network:Read and Network:Write respectively. With namespaces, plugin authors don't need to worry about naming conflicts between plugins.

Roles

Roles are a collection of permissions. Roles allow the bot administrator to construct a set of permissions from across many plugins that together control access to a set of related commands. Perhaps you have several plugins installed that include commands that you want to grant to a Service Desk user. You can create a role with only the permissions required for their job and nothing more. Roles are not included with plugins. The bot administrator creates roles and they are stored with the bot configuration.

Groups

Groups are used to associate users with one or more roles and therefore, one or permissions to execute commands. When a user is added to a group, that user has authorization to execute any command that has a permission in a role that is part of that group. To put it another way, a user has all the permissions from all the roles added to that group.