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.
Association Permissions with Commands
Once permissions are defined in the module manifest, you can declare what permissions are needed in order to execute your commands.
PoshBot provides a custom attribute called [PoshBot.BotCommand()]
that you can decorate your functions with.
One of the things this attribute defines is the permission(s) needed by the user to execute this command.
[PoshBot.BotCommand()] properties
Property | Type | Description |
---|---|---|
CommandName | string | The name of the bot command. Default is the function name |
TriggerType | string | The type of trigger. Values: Command , Regex , Event |
HideFromHelp | bool | Whether to hide the command when the !help command is used. Default is $false |
Regex | string | A regex string to match the command against. Only valid when TriggerType is Regex |
MessageType | string | Type of message this command is triggered against. Only valid when TriggerType is Event |
MessageSubtype | string | Subtype of message this command is triggered against. Only valid when TriggerType is Event |
Permissions | string[] | String array of permissions to apply to the command. Only users with the given permissions are allow to execute command |
In order to associate one or more permissions with a command, you attach the [PoshBot.BotCommand()]
attribute to the function similarly to the [cmdletbinding()]
attribute.
By specifying the Permissions
property, you are declaring that the user must have one of these permissions in order to execute the command.
When declaring permissions on the function, the fully qualified permission name
<myplugin>:<permissionname>
is not needed. Only the permission name is needed. Internally, PoshBot will store the permission fully qualified.
function New-Thing {
[PoshBot.BotCommand(Permissions = 'create-things')]
[cmdletbinding()]
param(
[string]$Name
)
...
}