Set-MapiPermission

Description

This cmdlet modifies permissions on a MAPI folder.

Syntax
Note: Parameters in orange are optional.
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-AnonymousSwitchParameter
-RoleMapi.NET.Flags.FolderRoles
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-DefaultSwitchParameter
-RoleMapi.NET.Flags.FolderRoles
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-AnonymousSwitchParameter
-RightsMapi.NET.Flags.FolderRights[]
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-DefaultSwitchParameter
-RightsMapi.NET.Flags.FolderRights[]
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-UserOrGroupAddressesString[]
-RoleMapi.NET.Flags.FolderRoles
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-UserOrGroupAddressesString[]
-RightsMapi.NET.Flags.FolderRights[]
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-UserOrGroupIDsMapi.NET.EntryID[]
-RoleMapi.NET.Flags.FolderRoles
Set-MapiPermission
-FolderMapiObject<Mapi.NET.Folder>
-UserOrGroupIDsMapi.NET.EntryID[]
-RightsMapi.NET.Flags.FolderRights[]
Parameters
FolderA Mapi.NET.Folder object for which to modify permissions.
AnonymousA SwitchParameter which, if present, causes the cmdlet to modify the Anonymous permission on the folder.
DefaultA SwitchParameter which, if present, causes the cmdlet to modify the Default permission on the folder.
UserOrGroupAddressesA list of one or more email addresses representing a mailbox or group for which to modify permissions.
UserOrGroupIDsA list of one or more Mapi.NET.EntryID values representing a mailbox or group for which to modify permissions.
RoleOne of the Mapi.NET.Flags.FolderRoles values, which is a preset combination of Rights, to be applied. The accepted values are, from least to most restrictive:
  • OwnerContact
  • Owner
  • PublishingEditor
  • Editor
  • PublishingAuthor
  • Author
  • NonEditingAuthor
  • Reviewer
  • Contributor
  • None
RightsOne or more of the Mapi.NET.Flags.FolderRights values which are combined and set as the new permission on the folder The possible rights are:
  • NoRights
  • ReadAny
  • Create
  • EditOwned
  • DeleteOwned
  • EditAny
  • DeleteAny
  • CreateFolder
  • FolderOwner
  • Contact
  • Visible
  • FreeBusySimple
  • FreeBusyDetailed
.
Remarks

This cmdlet modifes existing permissions only.  Use Add-MapiPermission to add new permissions to a folder.

Not every folder supports permissions.  For example, a folder from a PST file does not support permissions as there is no central address book from which to source account info.  Exchange mailboxes and Public Folders do support permissions and the permission entries on folders are address book EntryID values.

The table of permissions on a folder have a limit as to the number of unique permissions that can be set.  The limit is a byte-count limit, not a row limit.  Since the EntryID value of each permissions will vary in length (due to the fact that part of the EntryID contains the X500 value of the account), the row count limit is variable and is also dependent upon the version of Microsoft Exchange.  Most calculations show that between 300-400 unique permission rows are possible on a single folder.  Large permission sets on folder should be avoided when possible and mail-enabled security groups should be used in place of large permission lists.

Permissions on folders in Exchange do not inherit in a typical fashion, but instead only inherit a parent's permissions on create.  After a folder is created, modifications to that folder's permissions do not automatically show on subfolders since each folder maintains its own permission set.  Therefore, in order to adjust a folder tree of permissions, each subfolder must be opened and the permissions adjusted in turn.  A combination of Get-MapiTree + Get-MapiFolder + Set-MapiPermissions can be used to walk a subtree and adjust permissions.

As mentioned above, entries in the permissions table for a folder are identified by their Address Book EntryID and a component of this identifier is the X500 address of the user or group.  This value is stored on the Active Directory object in the LegacyExchangeDN attribute.  As such, it is possible for a user or group to lose it's mail-enabled status after it was previously applied as having permission on the folder.  If a mailbox user was given rights to a folder, then later the mailbox attributes for that user were removed (the mailbox essentially deleted, but the user remains), the display name of the entry may appear as 'NT USER:DomainUsername'.  This shows that the user account or group still exists in Active Directory and the best that Exchange was able to show for the object was the Domain and Username of the delegate.  This can also appear this way in some cross-forest scenarios where users in DomainA are explicitly given permission to folders in DomainB.