Skip to content

Managing Security Roles

This article describes how to create, modify, and assign Security Roles using PowerShell and C#. The code samples included in this article can be used in stand-alone scripts and applications as well as in PowerShell scripts executed by Business Rules, Custom Commands, and Scheduled Tasks.

Creating a role

To create a Security Role, first you have to bind to the container where you want to create it. All container objects support the IADsContainer interface, which provides methods and properties that manage the creation, deletion, and enumeration of child objects. To create a new Security Role, you need to call the Create method of the interface and pass “adm-Role” as the first parameter of the method and the relative distinguished name (RDN) of the role as the second parameter. The object returned by the IADsContainer::Create method will support the IAdmRole interface, using which you can specify the properties of the new Security Role. To save the role, you need to call IADs::SetInfo.

The following code sample creates a Security Role called My Role in the root container for Security Roles.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

# Bind to the 'Security Roles' container
$securityRolesPath = $admService.Backend.GetConfigurationContainerPath(`
    "AccessControlRoles")
$securityRolesContainer = $admService.OpenObject($securityRolesPath,
     $NULL, $NULL, 0)

# Create a new Security Role
$role = $securityRolesContainer.Create("adm-Role", "CN=My Role")

$role.Description = "My description"
$role.Disabled = $False

# Save the role
$role.SetInfo()
using System;
using Interop.Adsi;
using Interop.Adsi.AccessControl;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the 'Security Roles' container
        String securityRolesPath = admService.Backend.GetConfigurationContainerPath(
            "AccessControlRoles");
        IADsContainer securityRolesContainer = (IADsContainer)admService.OpenObject(
            securityRolesPath, null, null, 0);

        // Create a new Security Role
        IAdmRole role = (IAdmRole)securityRolesContainer.Create(
            "adm-Role", "CN=My Role");

        role.Description = "My description";
        role.Disabled = false;

        // Save the role
        role.SetInfo();
    }
}

If your script is executed by a Business Rule, Scheduled Task or Custom Command, you can use a predefined PowerShell variable $Context to get the ADS path of the Security Roles container. The type of the $Context variable is ExecuteScriptContext.

# Bind to the 'Security Roles' container
$securityRolesPath = $Context.GetWellKnownContainerPath("AccessControlRoles")
$securityRolesContainer = $Context.BindToObject($securityRolesPath)

# Create a new Security Role
$role = $securityRolesContainer.Create("adm-Role", "CN=My Role")

$role.Description = "My description"
$role.Disabled = $False

# Save the role
$role.SetInfo()
How to create a Security Role in a specific container

The following code sample creates a Security Role in the container called My Container.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

# Bind to the 'Security Roles' container
$securityRolesPath = $admService.Backend.GetConfigurationContainerPath(`
    "AccessControlRoles")
# Build the ADS path of the child container 'My Container'
$securityRolesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath"`
    $securityRolesPath
$myContainerAdsPath = $securityRolesPathObj.CreateChildPath("CN=My Container")

$myContainer = $admService.OpenObject($myContainerAdsPath,
    $NULL, $NULL, 0)

# Create a new Security Role
$role = $myContainer.Create("adm-Role", "CN=My Role")

$role.SetInfo()
using System;
using Interop.Adsi;
using Interop.Adsi.AccessControl;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the 'Security Roles' container
        String securityRolesPath = admService.Backend.GetConfigurationContainerPath(
                "AccessControlRoles");
        // Build the ADS path of the child container 'My Container'
        AdsPath securityRolesPathObj = new AdsPath(securityRolesPath);
        AdsPath myContainerAdsPath = securityRolesPathObj.CreateChildPath(
                "CN=My Container");

        IADsContainer myContainer = (IADsContainer)admService.OpenObject(
                myContainerAdsPath.ToString(), null, null, 0);

        // Create a new Security Role
        IAdmRole role = (IAdmRole)myContainer.Create("adm-Role", "CN=My Role");

        role.SetInfo();
    }
}

Tip

On how to create containers for Security Roles, see Creating Security Role containers.

Defining role permissions

To access the permissions of a Security Role, you need to use the Permissions property of the IAdmRole interface. The property supports the IAdmCollection interface. To create a new permission entry, call the IAdmCollection::Create method. Permission entries support the IAdmRolePermissionEntry interface, using which you can define what operation is allowed or denied by the permission entry.

  1. Use the IAdmRolePermissionEntry::AccessMask property to set the mask that specifies the access right. The ADS_RIGHTS_ENUM enumeration specifies the access rights you can set.
  2. Use the IAdmRolePermissionEntry::AccessType property to specify whether to allow or deny the access rights set by the AccessMask property. The ADM_PERMISSION_TYPE_ENUM enumeration specifies the access types you can set.
  3. Set the IAdmRolePermissionEntry::ObjectType property to specify a string containing the GUID of the object class (for the ADS_RIGHT_DS_CREATE_CHILD, ADS_RIGHT_DS_DELETE_CHILD, and ADS_RIGHT_DS_MOVE_TO rights), property, property set or extended right that the permission entry applies to. The GUID must be a string of hexadecimal numbers with the following format: “{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}”.
  4. Set the IAdmRolePermissionEntry::InheritedObjectType property to specify a string that contains the GUID of the inherited object class that the permission entry applies to. The GUID must be a string of hexadecimal numbers with the following format: “{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}”.

Before adding a newly created permission entry to a Security Role, you need to save the entry using the IADs::SetInfo method. To add a permission entry to a Security Role, call the IAdmCollection::Add method.

Example 1: Allow creation of user accounts

# Allow: Create User Objects
$entry = $role.Permissions.Create()

$userClassGuid = # the GUID of the User object class
    "{bf967aba-0de6-11d0-a285-00aa003049e2}"

$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"
$entry.AccessMask = "ADS_RIGHT_DS_CREATE_CHILD"
$entry.ObjectType = $userClassGuid
$entry.InheritedObjectType = [System.Guid]::Empty.ToString()

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role
// Allow: Create User Objects
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();

const String userClassGuid = // the GUID of the User object class
    "{bf967aba-0de6-11d0-a285-00aa003049e2}";

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW;
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_CREATE_CHILD;
entry.ObjectType = userClassGuid;
entry.InheritedObjectType = Guid.Empty.ToString();

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role

Example 2: Allow deletion of all types of objects and deny deletion of groups

# Allow: Delete All Child Objects
$entry = $role.Permissions.Create()

$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"
$entry.AccessMask = "ADS_RIGHT_DS_DELETE_CHILD"
$entry.ObjectType = [System.Guid]::Empty.ToString()
$entry.InheritedObjectType = [System.Guid]::Empty.ToString()

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role

# Deny: Delete Group Objects
$entry = $role.Permissions.Create()

$groupClassGuid = # the GUID of the Group object class
    "{bf967a9c-0de6-11d0-a285-00aa003049e2}"

$entry.AccessType = "ADM_PERMISSION_TYPE_DENY"
$entry.AccessMask = "ADS_RIGHT_DS_DELETE_CHILD"
$entry.ObjectType = $groupClassGuid
$entry.InheritedObjectType = [System.Guid]::Empty.ToString()

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role
// Allow: Delete All Child Objects
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW;
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_DELETE_CHILD;
entry.ObjectType = Guid.Empty.ToString();
entry.InheritedObjectType = Guid.Empty.ToString();

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role

// Deny: Delete Group Objects
entry = (IAdmRolePermissionEntry)role.Permissions.Create();

const String groupClassGuid = // the GUID of the Group object class
    "{bf967a9c-0de6-11d0-a285-00aa003049e2}";

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_DENY;
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_DELETE_CHILD;
entry.ObjectType = groupClassGuid;
entry.InheritedObjectType = Guid.Empty.ToString();

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role

Example 3: Allow viewing computer objects

# Allow: Read -> Computer
$entry = $role.Permissions.Create()

$computerClassGuid = # the GUID of the Computer object class
    "{bf967a86-0de6-11d0-a285-00aa003049e2}"

$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"
$entry.AccessMask = "ADS_RIGHT_GENERIC_READ"
$entry.ObjectType = [System.Guid]::Empty.ToString()
$entry.InheritedObjectType = $computerClassGuid

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role
// Allow: Read -> Computer
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();

const String computerClassGuid = // the GUID of the Computer object class
    "{bf967a86-0de6-11d0-a285-00aa003049e2}";

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW;
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_GENERIC_READ;
entry.ObjectType = Guid.Empty.ToString();
entry.InheritedObjectType = computerClassGuid;

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role

Example 4: Allow reading and writing the Member property of group objects and deny writing the Description property of all objects types

# Allow: Read 'Member' Property -> Group
# Allow: Write 'Member' Property -> Group
$entry = $role.Permissions.Create()

$groupClassGuid = # the GUID of the Group object class
    "{bf967a9c-0de6-11d0-a285-00aa003049e2}"
$memberPropGuid = # the GUID of the Member property
    "{bf9679c0-0de6-11d0-a285-00aa003049e2}"

$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"
$entry.AccessMask =
    "ADS_RIGHT_DS_WRITE_PROP, ADS_RIGHT_DS_READ_PROP"
$entry.ObjectType = $memberPropGuid
$entry.InheritedObjectType = $groupClassGuid

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role


# Deny: Write 'Description' Property -> All Object Types
$entry = $role.Permissions.Create()

$descriptionPropGuid = # the GUID of the Description property
    "{bf967950-0de6-11d0-a285-00aa003049e2}"

$entry.AccessType = "ADM_PERMISSION_TYPE_DENY"
$entry.AccessMask = "ADS_RIGHT_DS_WRITE_PROP"
$entry.ObjectType = $descriptionPropGuid
$entry.InheritedObjectType = [System.Guid]::Empty.ToString()

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role
// Allow: Read 'Member' Property -> Group
// Allow: Write 'Member' Property -> Group
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();

const String groupClassGuid = // the GUID of the Group object class
    "{bf967a9c-0de6-11d0-a285-00aa003049e2}";
const String memberPropGuid = // the GUID of the Member property
    "{bf9679c0-0de6-11d0-a285-00aa003049e2}";

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW;
entry.AccessMask =
    ADS_RIGHTS_ENUM.ADS_RIGHT_DS_WRITE_PROP |
    ADS_RIGHTS_ENUM.ADS_RIGHT_DS_READ_PROP;
entry.ObjectType = memberPropGuid;
entry.InheritedObjectType = groupClassGuid;

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role


// Deny: Write 'Description' Property -> All Object Types
entry = (IAdmRolePermissionEntry)role.Permissions.Create();

const String descriptionPropGuid = // the GUID of the Description property
    "{bf967950-0de6-11d0-a285-00aa003049e2}";

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_DENY;
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_WRITE_PROP;
entry.ObjectType = descriptionPropGuid;
entry.InheritedObjectType = Guid.Empty.ToString();

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role

Example 5: Allow resetting passwords of user accounts

# Allow: Reset Password -> User
$entry = $role.Permissions.Create()

$userClassGuid = # the GUID of the User object class
    "{bf967aba-0de6-11d0-a285-00aa003049e2}"

$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"
$entry.AccessMask = "ADS_RIGHT_DS_CONTROL_ACCESS"
$entry.ObjectType =
    [Softerra.Adaxes.Ldap.ExtendedRights]::UserForceChangePassword
$entry.InheritedObjectType = $userClassGuid

$entry.SetInfo() # save the permission entry
$role.Permissions.Add($entry) # add the permission to the role
// Allow: Reset Password -> User
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();

const String userClassGuid = // the GUID of the User object class
    "{bf967aba-0de6-11d0-a285-00aa003049e2}";

entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW;
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_CONTROL_ACCESS;
entry.ObjectType = ExtendedRights.UserForceChangePassword;
entry.InheritedObjectType = userClassGuid;

entry.SetInfo(); // save the permission entry
role.Permissions.Add(entry); // add the permission to the role

Note

Reset Password is an extended right. To view a list of all extended rights supported by Adaxes, see the ExtendedRights class.

Assigning a role

To manage assignments of a Security Role, you need to use the Assignments property of the IAdmRole interface. The property supports the IAdmCollection interface. To create a new assignment, call the IAdmCollection::Create method. The method returns an instance of the IAdmRoleAssignment interface that represents a Security Role assignment.

  1. Use the IAdmRoleAssignment::Trustee property to specify the user or group you want to assign the role to. The property gets a string that contains either the trustee’s SID in the SDDL format (e.g. S-1-5-1-123-456-789), or the user’s logon name (e.g. DOMAIN\username, username@domain.com), or the group name (pre-Windows 2000).
  2. Use the IAdmRoleAssignment::TrusteeDomain property to provide the name of the domain the trustee belongs to. This property must be used only if the trustee’s SID doesn’t contain information about the domain. For example, if you assign a Security Role to a built-in Active Directory group, such as BUILTIN\Users. The property must be assigned a string that contains either the DNS name of the domain or the domain’s SID in the SDDL format.
  3. Use the IAdmRoleAssignment::ActivityScopeItems property to specify the scope of the role assignment. The scope determines where in Active Directory the trustee will be able to apply the permissions of the role. For example, if you want the trustee to be able perform the actions allowed by the role in a specific Organizational Unit, you need to include the Organizational Unit to the scope of the role assignment for the trustee.

    The IAdmRoleAssignment::ActivityScopeItems property exposes the IAdmCollection interface. To create a new activity scope item, call the IAdmCollection::Create method. The method will return an instance of the IAdmActivityScopeItem interface.

    • Use the IAdmActivityScopeItem::Type property to specify whether you want the scope to include a specific object, objects located in an Organizational Unit or container, members of a group or Business Unit, all objects in all managed AD domains, etc. The ADM_SCOPEBASEOBJECTTYPE_ENUM enumeration specifies the scope types you can use.
    • Use the IAdmActivityScopeItem::Exclude property to specify whether you want the scope item to be included or excluded from the scope of the role assignment.
    • Use the IAdmActivityScopeItem::BaseObject property to specify the object defining the scope. For example, if you want to include all objects located in a specific Organizational Unit to the activity scope, set that OU as the base object. If you want to include all members of a group to the activity scope, set that group as the base object.
    • The meaning of the IAdmActivityScopeItem::Inheritance property depends on the scope type that is specified in the IAdmActivityScopeItem.Type property. For example, if the Type property is set to ADM_SCOPEBASEOBJECTTYPE_GROUP, meaning that the scope will include members of a group, the Inheritance property will define whether only direct members or all members (including the members of the nested groups) will be included to the activity scope. Or, if the Type property is set to ADM_SCOPEBASEOBJECTTYPE_CONTAINER, meaning that the scope will include objects located under an Organizational Unit, the Inheritance property will define whether only direct children or all descendants of the Organizational Unit will be included to the activity scope. The ADS_SCOPEENUM enumeration specifies the inheritance types you can use.

    The following table shows which values must be set for the properties of the IAdmActivityScopeItem interface for different scopes of activity.

    Activity Scope Type Inheritance BaseObject
    All objects ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY ADS_SCOPE_SUBTREE NULL
    All objects in a domain ADM_SCOPEBASEOBJECTTYPE_CONTAINER ADS_SCOPE_SUBTREE An ADSI object representing the domain partition.
    How to bind to the domain partition
    All descendants of an OU ADM_SCOPEBASEOBJECTTYPE_CONTAINER ADS_SCOPE_SUBTREE An ADSI object representing the OU.
    Immediate children of an OU ADM_SCOPEBASEOBJECTTYPE_CONTAINER ADS_SCOPE_ONELEVEL An ADSI object representing the OU.
    All members of a group (including nested members) ADM_SCOPEBASEOBJECTTYPE_GROUP ADS_SCOPE_SUBTREE An ADSI object representing the group.
    Direct members of a group ADM_SCOPEBASEOBJECTTYPE_GROUP ADS_SCOPE_ONELEVEL An ADSI object representing the group.
    Members of a Business Unit ADM_SCOPEBASEOBJECTTYPE_BUSINESSUNIT ADS_SCOPE_SUBTREE An ADSI object representing the Business Unit.
    How to bind to Adaxes-specific objects
    Specific object ADM_SCOPEBASEOBJECTTYPE_CONTAINER ADS_SCOPE_BASE An ADSI object representing the specific object.
    Adaxes Configuration Objects ADM_SCOPEBASEOBJECTTYPE_CONFIGURATION ADS_SCOPE_SUBTREE NULL

Example 1: Assign a role to user Administrator over All Objects

$assignment = $role.Assignments.Create()
$assignment.Trustee = "EXAMPLE\Administrator"
$assignment.SetInfo()
$role.Assignments.Add($assignment)

$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $NULL
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $False
$scopeItem.SetInfo()

$assignment.ActivityScopeItems.Add($scopeItem)
IAdmRoleAssignment assignment =
    (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\Administrator";
assignment.SetInfo();
role.Assignments.Add(assignment);

IAdmActivityScopeItem scopeItem =
    (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = null;
scopeItem.Type =
    ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = false;
scopeItem.SetInfo();

assignment.ActivityScopeItems.Add(scopeItem);

Example 2: Assign a role to user John Smith over all objects in a domain and exclude members of a group from the assignment scope

$assignment = $role.Assignments.Create()
$assignment.Trustee = "EXAMPLE\jsmith"
$assignment.SetInfo()
$role.Assignments.Add($assignment)

# Include all objects in the domain 'example.com'

# Bind to the domain object
$domain = "example.com"
$domainObj = $admService.OpenObject("Adaxes://$domain", $NULL, $NULL, 0)

$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $domainObj
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $False
$scopeItem.SetInfo()
$assignment.ActivityScopeItems.Add($scopeItem)

# Exclude members of the group 'IT Staff'

# Bind to the group object
$groupDN = "CN=IT Staff,DC=example,DC=com"
$groupObj = $admService.OpenObject("Adaxes://$groupDN", $NULL, $NULL, 0)

$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $groupObj
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_GROUP"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $True
$scopeItem.SetInfo()
$assignment.ActivityScopeItems.Add($scopeItem)
IAdmRoleAssignment assignment =
    (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\jsmith";
assignment.SetInfo();
role.Assignments.Add(assignment);

// Include all objects in the domain 'example.com'

// Bind to the domain object
const String domain = "example.com";
IAdmTop domainObj = (IAdmTop)admService.OpenObject("Adaxes://" + domain,
    null, null, 0);

IAdmActivityScopeItem scopeItem =
    (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = domainObj;
scopeItem.Type =
    ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = false;
scopeItem.SetInfo();
assignment.ActivityScopeItems.Add(scopeItem);

// Exclude members of the group 'IT Staff'

// Bind to the group object
const String groupDN = "CN=IT Staff,DC=example,DC=com";
IAdmTop groupObj = (IAdmTop)admService.OpenObject("Adaxes://" + groupDN,
    null, null, 0);
scopeItem = (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = groupObj;
scopeItem.Type =
    ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_GROUP;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = true;
scopeItem.SetInfo();
assignment.ActivityScopeItems.Add(scopeItem);

Example 3: Assign a role to group Help Desk over objects located in the Organizational Unit named Sales

$assignment = $role.Assignments.Create()
$assignment.Trustee = "EXAMPLE\Help Desk"
$assignment.SetInfo()
$role.Assignments.Add($assignment)

# Bind to the Organizational Unit object
$ouDN = "OU=Sales,DC=example,DC=com"
$ouObj = $admService.OpenObject("Adaxes://$ouDN", $NULL, $NULL, 0)

$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $ouObj
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $False
$scopeItem.SetInfo()
$assignment.ActivityScopeItems.Add($scopeItem)
IAdmRoleAssignment assignment =
    (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\Help Desk";
assignment.SetInfo();
role.Assignments.Add(assignment);

// Bind to the Organizational Unit object
const String ouDN = "OU=Sales,DC=example,DC=com";
IAdmTop ouObj = (IAdmTop)admService.OpenObject("Adaxes://" + ouDN,
    null, null, 0);

IAdmActivityScopeItem scopeItem =
    (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = ouObj;
scopeItem.Type =
    ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = false;
scopeItem.SetInfo();
assignment.ActivityScopeItems.Add(scopeItem);

Example 4: Assign a role to a user over a specific group object (not members of the group)

$assignment = $role.Assignments.Create()
$assignment.Trustee = "EXAMPLE\Administrator"
$assignment.SetInfo()
$role.Assignments.Add($assignment)

# Bind to the group object
$groupDN = "CN=My Group,DC=example,DC=com"
$groupObj = $admService.OpenObject("Adaxes://$groupDN" ,$NULL, $NULL, 0)
$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $groupObj
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_BASE"
$scopeItem.Exclude = $False
$scopeItem.SetInfo()
$assignment.ActivityScopeItems.Add($scopeItem)
IAdmRoleAssignment assignment =
    (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\Administrator";
assignment.SetInfo();
role.Assignments.Add(assignment);

// Bind to the group object
const String groupDN = "CN=My Group,DC=example,DC=com";
IAdmTop groupObj = (IAdmTop)admService.OpenObject("Adaxes://" + groupDN,
    null, null, 0);
IAdmActivityScopeItem scopeItem =
    (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = groupObj;
scopeItem.Type =
    ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_BASE;
scopeItem.Exclude = false;
scopeItem.SetInfo();
assignment.ActivityScopeItems.Add(scopeItem);

For more samples, see Assigning Security Roles

Modifying a role

To modify an existing Security Role, first you need to bind to the role object. For more information on how to bind to Adaxes-specific objects, see Binding to Adaxes-specific objects.

After you’ve bound to a Security Role, you can use ADSI interfaces like IADMROLE and IADS to modify the role. To save the changes, you have to call IADs::SetInfo.

The following code sample updates the description and disables the Security Role named My Role.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$rolesPath = $admService.Backend.GetConfigurationContainerPath(
    "AccessControlRoles")
$rolesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" `
    $rolesPath
$rolePath = $rolesPathObj.CreateChildPath("CN=My Role")
$role = $admService.OpenObject($rolePath.ToString(), $NULL, $NULL, 0)

$role.Description = "My description"
$role.Disabled = $True

# Save the changes
$role.SetInfo()
using System;
using Interop.Adsi.AccessControl;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        String rolesPath = admService.Backend.GetConfigurationContainerPath(
            "AccessControlRoles");
        AdsPath rolesPathObj = new AdsPath(rolesPath);
        AdsPath rolePath = rolesPathObj.CreateChildPath("CN=My Role");
        IAdmRole role =
            (IAdmRole)admService.OpenObject(rolePath.ToString(), null, null, 0);

        role.Description = "My description";
        role.Disabled = true;

        // Save the changes
        role.SetInfo();
    }
}

If your script is executed by a Business Rule, Scheduled Task or Custom Command, you can use a predefined PowerShell variable $Context to get the ADS path of the Security Roles container and bind to the role.

$rolesPath = $Context.GetWellKnownContainerPath("AccessControlRoles")
$rolesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $rolesPath
$rolePath = $rolesPathObj.CreateChildPath("CN=My Role")
$role = $Context.BindToObject($rolePath)

$role.Description = "My description"
$role.Disabled = $True

# Save the changes
$role.SetInfo()

The following code sample deletes all permission entries and assignments of a specific Security Role located in the container named My Container.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service
$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$rolesPath = $admService.Backend.GetConfigurationContainerPath(
    "AccessControlRoles")
$rolesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $rolesPath
$containerPathObj = $rolesPathObj.CreateChildPath("CN=My Container")
$rolePath = $containerPathObj.CreateChildPath("CN=My Role")
$role = $admService.OpenObject($rolePath.ToString(), $NULL, $NULL, 0)

$role.Permissions.Clear()
$role.Assignments.Clear()
using System;
using Interop.Adsi.AccessControl;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        String rolesPath = admService.Backend.GetConfigurationContainerPath(
            "AccessControlRoles");
        AdsPath rolesPathObj = new AdsPath(rolesPath);
        AdsPath containerPathObj = rolesPathObj.CreateChildPath("CN=My Container");
        AdsPath rolePath = containerPathObj.CreateChildPath("CN=My Role");
        IAdmRole role =
            (IAdmRole)admService.OpenObject(rolePath.ToString(), null, null, 0);

        role.Permissions.Clear();
        role.Assignments.Clear();
    }
}

See also