Class AccessControlList

public class AccessControlList : IEnumerable<KeyValuePair<string, AccessControlEntry>>, IEnumerable, IReadOnly<AccessControlList>, IEditableSecurityDescriptor, IReadOnly, ISecurityDescriptor, IXmlSerializable, IModifiedTrackable, IEquatable<AccessControlList>

Remarks

ACL holds the Access Control List for a PageData object. Since PageData has the attribute Property which is a PropertyDataCollection, ACL effectively controls access to the Web page. Keep in mind that the Access Control List applies to all of the PageData object and its attributes. It is not possible to have different access permissions for different properties.

The Access Control List is comprised of an Access Control Entry, ACE, array and is accessed by calling the method ACL.ToRawACEArray.

Examples

  The code example below demonstrates the usage of AccessControlList, RawACE and AccessControlEntry.
  The example below sets up access rights on a &quot;personal&quot; start page. Administrators gets full access, 
  the creator gets everything except for administer and any other user/group that 
  has at least read access on the team start page gets read access rights.
  The argument &quot;page&quot; is the page to update the access rights on.

        private void SetAccessRights(PageData page)
{
PageData teamStart = Locate.ContentRepository().Get<PageData>(page.ParentLink);

AccessControlList aclClone = page.ACL.CreateWritableClone();
aclClone.IsInherited = false;
aclClone.ClearEntries();

foreach (RawACE ace in teamStart.ACL.ToRawACEArray())
{
    if ((ace.Access & AccessLevel.Read) == AccessLevel.Read && ace.Name != PrincipalInfo.Current.Name && ace.Name != "Administrators")
    {
        aclClone.Add(new AccessControlEntry(ace.Name, AccessLevel.Read, ace.AutomaticEntryType));

    }
}
aclClone.Add(new AccessControlEntry("Administrators", AccessLevel.FullAccess, SecurityEntityType.Role));
aclClone.Add(new AccessControlEntry(PrincipalInfo.Current.Name, AccessLevel.FullAccess & ~AccessLevel.Administer, SecurityEntityType.User));
aclClone.Save(SecuritySaveType.Replace);
}

        The following code example demonstrates the usage of <strong>ToRawACEArray</strong> to enumerate the 
        Access Control Entries. The example enumerates the <strong>EPiServer.Security.RawAce</strong> objects, 
        which together form the Access Control List and check if one of them is the Create permission.

            foreach (EPiServer.Security.RawACE Ace in CurrentPage.ACL.ToRawACEArray())
{
    if ((Ace.Access & EPiServer.Security.AccessLevel.Create) ==
    EPiServer.Security.AccessLevel.Create)
    {
        // Do Something
    }
}

        The following code example demonstrates the usage of <strong>QueryDistinctAccess</strong> to check specific 
        access for the current user.

            if (CurrentPage.ACL.QueryDistinctAccess(EPiServer.Security.AccessLevel.Create))
{
    // Checks whether the currently logged-on user has
    // Create permission for the current page.
}

Constructors

AccessControlList()

Initializes a new instance of the AccessControlList class without any entries.

Declaration

public AccessControlList()

AccessControlList(AccessControlList)

Initializes a new instance of the AccessControlList class that has the same entries as the provided list.

Declaration

public AccessControlList(AccessControlList accessControlList)

Parameters

Type	Name	Description
AccessControlList	accessControlList	The list whose entries should be replicated in the new instance.

AccessControlList(RawACE[])

Initializes a new instance of the AccessControlList class with values from the provided RawACE array.

Declaration

public AccessControlList(RawACE[] accessControlEntries)

Parameters

Type	Name	Description
RawACE[]	accessControlEntries	The array of entries to populate the instance with.

Properties

AccessLevelValues

Gets a list of all the distinct AccessLevel available.

Declaration

public static IEnumerable<AccessLevel> AccessLevelValues { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<AccessLevel>

ChangedBy

Gets or sets what last changed the access control list. This property is only intended for internal use.

Declaration

public AccessControlChangedBy ChangedBy { get; set; }

Property Value

Type	Description
AccessControlChangedBy

Count

Gets the number of AccessControlEntry in the current instance.

Declaration

public int Count { get; }

Property Value

Type	Description
System.Int32

Remarks

This property does not take inherited entries into account.

Creator

Gets or sets the creator of the object that the ACL is attached to.

Declaration

public virtual string Creator { get; set; }

Property Value

Type	Description
System.String

Remarks

This is used to determine special access rights for the virtual 'CreatorRole'.

Entries

Gets all the access control entries in this security descriptor instance.

Declaration

public virtual IEnumerable<AccessControlEntry> Entries { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<AccessControlEntry>

Remarks

If this descriptor is inherited and the parent implements the IEditableSecurityDescriptor interface, the inherited entries will be returned.

InheritedSecurityDescriptor

Gets the parent security descriptor this instance would inherit should it be set to inherited.

Declaration

protected ISecurityDescriptor InheritedSecurityDescriptor { get; }

Property Value

Type	Description
ISecurityDescriptor

IsDirty

Indicates if unsaved modifications has been made to the list

Declaration

[Obsolete("Use IModifiedTracking instead, You are not able to set Dirty flag without changing of some properties", true)]
public bool IsDirty { get; set; }

Property Value

Type	Description
System.Boolean

IsInherited

Gets or sets a value that indicates if this ACL is inherited from a parent.

Declaration

public virtual bool IsInherited { get; set; }

Property Value

Type	Description
System.Boolean

IsModified

Gets a value indicating whether this instance has been modified after loading.

Declaration

public bool IsModified { get; protected set; }

Property Value

Type	Description
System.Boolean	`true` if this instance has been modified; otherwise, `false`.

IsReadOnly

Gets or sets a value indicating whether the current instance is read only.

Declaration

public bool IsReadOnly { get; protected set; }

Property Value

Type	Description
System.Boolean	`true` if it is read only; otherwise, `false`.

Item[String]

Gets or sets the AccessControlEntry with the specified security entity name.

Declaration

public virtual AccessControlEntry this[string securityEntityName] { get; set; }

Parameters

Type	Name	Description
System.String	securityEntityName	The name of the security entity entry.

Property Value

Type	Description
AccessControlEntry	An AccessControlEntry instance.

Remarks

AccessControlList does not accept null as name and will overwrite any previously added elements with the same name.

Exceptions

Type	Condition
System.ArgumentException	Thrown if trying to add an entry with a different name that the one provided.

Keys

Gets the ACL keys.

Declaration

public ICollection Keys { get; }

Property Value

Type	Description
System.Collections.ICollection

Remarks

This property does not take inherited entries into account.

SupportsInheritance

Returns true if the access control class supports inherited ACLs

Declaration

public virtual bool SupportsInheritance { get; }

Property Value

Type	Description
System.Boolean

Methods

Add(AccessControlEntry)

Adds an entry to the access control list. If an entry with the same name already exists, an exception will be thrown.

Declaration

public virtual void Add(AccessControlEntry accessControlEntry)

Parameters

Type	Name	Description
AccessControlEntry	accessControlEntry	The AccessControlEntry to add

AddEntry(AccessControlEntry)

Adds the provided access control entry to this security descriptor instance.

Declaration

public virtual void AddEntry(AccessControlEntry accessControlEntry)

Parameters

Type	Name	Description
AccessControlEntry	accessControlEntry	The access control entry to add.

Clear()

Clears the Creator property an all entries from this security descriptor instance.

Declaration

public virtual void Clear()

ClearEntries()

Clears all entries from this security descriptor instance.

Declaration

public virtual void ClearEntries()

Contains(String)

Determines if the list contains an entry with the specified security entity name.

Declaration

public virtual bool Contains(string securityEntityName)

Parameters

Type	Name	Description
System.String	securityEntityName	The name of the security entity entry.

Returns

Type	Description
System.Boolean	`True` if a matching entry exists, otherwise `false`.

Contains(String, AccessLevel, SecurityEntityType)

Determines if the list contains an entry with the specified name, access level and security entity type.

Declaration

public virtual bool Contains(string securityEntityName, AccessLevel access, SecurityEntityType entityType)

Parameters

Type	Name	Description
System.String	securityEntityName	The name of the security entity entry.
AccessLevel	access	The access level.
SecurityEntityType	entityType	The security entity type.

Returns

Type	Description
System.Boolean	`True` if a matching entry exists, otherwise `false`.

Copy()

Creates a copy of the current instance.

Declaration

public virtual AccessControlList Copy()

Returns

Type	Description
AccessControlList	A new AccessControlList instance.

CreateWritableClone()

Creates a writable clone of the current AccessControlList instance.

Declaration

public AccessControlList CreateWritableClone()

Returns

Type	Description
AccessControlList	A writable copy of the current instance.

EntriesEquals(AccessControlList)

Determines whether the specified AccessControlList has the same entries as the current instance.

Declaration

public virtual bool EntriesEquals(AccessControlList other)

Parameters

Type	Name	Description
AccessControlList	other	The ACL to compare entries with.

Returns

Type	Description
System.Boolean	`true` if the specified AccessControlList has equal entries; otherwise, `false`.

Equals(AccessControlList)

Indicates whether the current AccessControlList instance is equal to another AccessControlList instance.

Declaration

public virtual bool Equals(AccessControlList other)

Parameters

Type	Name	Description
AccessControlList	other	An AccessControlList to compare with this instance.

Returns

Type	Description
System.Boolean	true if the current instance is equal to the `other` parameter; otherwise, false.

Exists(String)

Checks if the specified security entity exists in this list

Declaration

[Obsolete("Method name has been changed to Contains to follow conventions and more clearly describe it's behaviour.")]
public virtual bool Exists(string securityEntity)

Parameters

Type	Name	Description
System.String	securityEntity	The security entity.

Returns

Type	Description
System.Boolean	`True` if a matching entry exists, otherwise `false`.

Exists(String, AccessLevel, SecurityEntityType)

Declaration

[Obsolete("Method name has been changed to Contains to follow conventions and more clearly describe it's behaviour.")]
public virtual bool Exists(string name, AccessLevel access, SecurityEntityType entityType)

Parameters

Type	Name	Description
System.String	name
AccessLevel	access
SecurityEntityType	entityType

Returns

Type	Description
System.Boolean

GetAccessLevel(IPrincipal)

Retreives the access level for the specified principal.

Declaration

public AccessLevel GetAccessLevel(IPrincipal principal)

Parameters

Type	Name	Description
System.Security.Principal.IPrincipal	principal	The principal get access rights for.

Returns

Type	Description
AccessLevel	The access level that the specified principal has.

Remarks

Use this method when you want to get the union of all access types granted to this principal. This is most likely only used for display purposes in the user interface. Code that checks access and performs different actions depending on the type of access granted should use the HasAccess method, since it does what you want and has the potential for being much faster.

If the current ISecurityDescriptor is inherited, this method checks the inherited access rights.

GetEnumerator()

Returns an enumerator that iterates through all entries in the collection.

Declaration

public IEnumerator<KeyValuePair<string, AccessControlEntry>> GetEnumerator()

Returns

Type	Description
System.Collections.Generic.IEnumerator<System.Collections.Generic.KeyValuePair<System.String, AccessControlEntry>>	A System.Collections.Generic.IEnumerator<T> that can be used to iterate through all entries in the collection.

Remarks

This method will not return any inherited entries.

GetParentSecurityDescriptor()

Retrieves the security descriptor that this instance would inherited should it be set to inherited.

Declaration

protected virtual ISecurityDescriptor GetParentSecurityDescriptor()

Returns

Type	Description
ISecurityDescriptor	The security descriptor that the current instance can inherit from.

Remarks

Implementors of this method should have their own caching in place, this method may be called a lot and does not store the results in a local variable.

HasAccess(IPrincipal, AccessLevel)

Determines whether the specified principal has the requested access.

Declaration

public bool HasAccess(IPrincipal principal, AccessLevel access)

Parameters

Type	Name	Description
System.Security.Principal.IPrincipal	principal	The principal to authorize.
AccessLevel	access	The requested access level.

Returns

Type	Description
System.Boolean	`true` if the specified principal has access; otherwise, `false`.

Remarks

Note that the access level is a bitmask, i.e. we simply check that all specified access types are granted to the principal.

If the current ISecurityDescriptor is inherited, this method will check the inherited access rights.

IsEqual(AccessControlList)

Determines whether the specified acl is equal as current instance. With equal means they contain the same entries.

Declaration

[Obsolete("Method name has been changed to EntriesEquals to more clearly describe it's behaviour and to distinguish it from Equals.")]
public bool IsEqual(AccessControlList acl)

Parameters

Type	Name	Description
AccessControlList	acl	The acl.

Returns

Type	Description
System.Boolean	`true` if the specified acl is equal; otherwise, `false`.

LocalizationKey(AccessLevel)

Returns a string that can be used as a key when requesting a localized representation of the access level.

Declaration

public static string LocalizationKey(AccessLevel accessLevel)

Parameters

Type	Name	Description
AccessLevel	accessLevel	The access level to translate.

Returns

Type	Description
System.String

MakeReadOnly()

Locks current instance for changes.

Declaration

public void MakeReadOnly()

QueryAccess()

Determines the access level that the current user has for this instance.

Declaration

public AccessLevel QueryAccess()

Returns

Type	Description
AccessLevel	The AccessLevel that the current user has.

QueryAccess(AccessLevel)

Determines the access level that the current user has for this instance limited to the maximum access level provided.

Declaration

public AccessLevel QueryAccess(AccessLevel maxAccess)

Parameters

Type	Name	Description
AccessLevel	maxAccess	The maximum access required to check.

Returns

Type	Description
AccessLevel	The AccessLevel that the principal has, at most the maximum access provided.

QueryAccess(IPrincipal)

Determines the access level that the provided principal has for this instance.

Declaration

public AccessLevel QueryAccess(IPrincipal principal)

Parameters

Type	Name	Description
System.Security.Principal.IPrincipal	principal	The principal.

Returns

Type	Description
AccessLevel	The AccessLevel that the provided principal has.

QueryAccess(IPrincipal, AccessLevel)

Determines the access level that the provided principal has been given.

Declaration

public virtual AccessLevel QueryAccess(IPrincipal principal, AccessLevel maxAccess)

Parameters

Type	Name	Description
System.Security.Principal.IPrincipal	principal	The principal whose access should be queried.
AccessLevel	maxAccess	The maximum access required to check.

Returns

Type	Description
AccessLevel	The AccessLevel that the principal has, at most the maximum access provided.

QueryAccess(String)

Determine the access level for the user.

Declaration

[Obsolete("This method has been obsoleted as it has limited usage and had a different behaviour that the other QueryAccess methods.")]
public AccessLevel QueryAccess(string user)

Parameters

Type	Name	Description
System.String	user	The name of the user.

Returns

Type	Description
AccessLevel	An AccessLevel with the relevant information set.

Remarks

This method will NOT look up group information for the user. It will simply return the access level set for this user.

This method will NOT check inherited rights. It this instance is inherited it will return AccessLevel.NoAccess.

QueryDistinctAccess(AccessLevel)

Verifies that the specific access levels are set for the current user.

Declaration

public bool QueryDistinctAccess(AccessLevel access)

Parameters

Type	Name	Description
AccessLevel	access	The requested access level

Returns

Type	Description
System.Boolean	True if the combined access level of all entries that apply to the current user in this ACL has at least the requested access level

Remarks

This is the fastet way to query for access, and is thus the preferred mechanism.

QueryDistinctAccess(IPrincipal, AccessLevel)

Verify that the specific access levels are set for the specified principal.

Declaration

public bool QueryDistinctAccess(IPrincipal principal, AccessLevel access)

Parameters

Type	Name	Description
System.Security.Principal.IPrincipal	principal	The principal for the user to check access against.
AccessLevel	access	The requested access level

Returns

Type	Description
System.Boolean	True if the combined access level of all entries that apply to the given principal in this ACL has at least the requested access level

Remarks

This is the fastet way to query for access, and is thus the preferred mechanism.

ReadXml(XmlReader)

Implementation of IXmlSerializable.ReadXml. Generates an object from its XML representation.

Declaration

protected virtual void ReadXml(XmlReader reader)

Parameters

Type	Name	Description
System.Xml.XmlReader	reader	The System.Xml.XmlReader stream from which the object is deserialized.

Remove(String)

Removes the specified security entity from this list.

Declaration

public virtual bool Remove(string securityEntityName)

Parameters

Type	Name	Description
System.String	securityEntityName	The name of the security entity to remove.

Returns

Type	Description
System.Boolean	True if an entry with the provided name was found and removed;if no entry with that name was found false is returned.

RemoveEntry(AccessControlEntry)

Removes the provided access control entry from this security descriptor instance.

Declaration

public virtual void RemoveEntry(AccessControlEntry accessControlEntry)

Parameters

Type	Name	Description
AccessControlEntry	accessControlEntry	The access control entry to remove.

ResetModified()

Resets the modified flag on all the data contained on the instance.

Declaration

public void ResetModified()

Save()

Saves this instance.

Declaration

public virtual void Save()

Save(SecuritySaveType)

Saves the specified type.

Declaration

public virtual void Save(SecuritySaveType type)

Parameters

Type	Name	Description
SecuritySaveType	type	The type.

SetModified(Boolean)

Sets the IsModified flag indicating whether this instance has been modified after loading.

Declaration

[Obsolete("Use protected accessor to IsModified property instead.")]
protected virtual void SetModified(bool modified)

Parameters

Type	Name	Description
System.Boolean	modified	if set to `true` this instance will be set to modified.

ThrowIfInherited()

Throws an System.InvalidOperationException if current instance is set as inherited.

Declaration

protected void ThrowIfInherited()

ThrowIfReadOnly()

Throws an exception if the current instance is set to read-only.

Declaration

protected void ThrowIfReadOnly()

ToRawACEArray()

Creates an array of RawACE objects that represents all entries in the Access Control List.

Declaration

public RawACE[] ToRawACEArray()

Returns

Type	Description
RawACE[]	An array of RawACE objects.

Remarks

See AccessControlList for code example.

TranslatableString(AccessLevel)

Returns a string that can be used in calls to Translate to get a language-specific representation of the access level.

Declaration

[Obsolete("This method has been renamed to LocalizationKey.")]
public static string TranslatableString(AccessLevel accessLevel)

Parameters

Type	Name	Description
AccessLevel	accessLevel	The access level to translate.

Returns

Type	Description
System.String

WriteXml(XmlWriter)

Implementation of IXmlSerializable.WriteXml. Converts an object into its XML representation.

Declaration

protected virtual void WriteXml(XmlWriter writer)

Parameters

Type	Name	Description
System.Xml.XmlWriter	writer	The System.Xml.XmlWriter stream to which the object is serialized.

Explicit Interface Implementations

IReadOnly.CreateWritableClone()

Creates writable clone of this object.

Declaration

object IReadOnly.CreateWritableClone()

Returns

Type	Description
System.Object	Writable clone object.

IEnumerable.GetEnumerator()

Declaration

IEnumerator IEnumerable.GetEnumerator()

Returns

Type	Description
System.Collections.IEnumerator

Implements

System.Collections.Generic.IEnumerable<T>

System.Collections.IEnumerable

IReadOnly<T>

IEditableSecurityDescriptor

IReadOnly

ISecurityDescriptor

System.Xml.Serialization.IXmlSerializable

IModifiedTrackable

System.IEquatable<T>

Extension Methods

IdentityObjectExtensions.GetIdentity(Object)

IdentityObjectExtensions.SetIdentity(Object, Identity)

PropertyBagObjectsExtensions.ToPropertyBag(Object)

PropertyBagObjectsExtensions.ToPropertyBag(Object, IEnumerable<String>)

RuntimeModelExtensions.GetOriginalType(Object)