Managing security roles

Security roles can be created, assigned, edited, and deleted programmatically via the dedicated ADSI interfaces. You can apply the principles outlined in this article to write standalone scripts and programs or build custom integrations with third-party software. PowerShell scripts that manage security roles can also be executed from within Adaxes, for instance, from business rules, custom commands, and scheduled tasks.

Creating a security role

The following code sample creates a security role named My Role.

PowerShell

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

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

# Bind to the security roles container.
$containerPath = $service.Backend.GetConfigurationContainerPath("AccessControlRoles")
$container = $service.OpenObject($containerPath, $null, $null, 0)

# Create a security role.
$role = $container.Create("adm-Role", "CN=My Role")

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

# Save the role.
$role.SetInfo()

C#

using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.AccessControl;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the security roles container.
        string securityRolesPath = service.Backend.GetConfigurationContainerPath("AccessControlRoles");
        IADsContainer securityRolesContainer = (IADsContainer)service.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();
    }
}

Details

To create a security role, you need to connect to your Adaxes service and bind to the container where you want to create the role – for example, the root container for security roles also known as the AccessControlRoles container.

If your script will be executed inside Adaxes, it becomes even simpler. You don't have to explicitly connect to your Adaxes service. Instead, you can use a predefined PowerShell variable $Context to get the ADS path of the AccessControlRoles container and bind to it.

# Bind to the security roles container.
$containerPath = $Context.GetWellKnownContainerPath("AccessControlRoles")
$container = $Context.BindToObject($containerPath)

How to create a security role in a different container

To create a security role in a specific container, you need to build the ADS path of that container and bind to it just like you would bind to the AccessControlRoles container. The AdsPath class contains methods that simplify manipulating ADS paths.

The following code sample creates a security role in the container named My Container.

PowerShell

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

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

# Bind to the security roles container.
$containerPath = $service.Backend.GetConfigurationContainerPath("AccessControlRoles")

# Build the ADS path of the nested container 'My Container' and bind to it.
$securityRolesPath = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$myContainerPath = $securityRolesPath.CreateChildPath("CN=My Container")
$myContainer = $service.OpenObject($myContainerPath, $null, $null, 0)

# Create a security role and save it.
$role = $myContainer.Create("adm-Role", "CN=My Role")
$role.SetInfo()

C#

using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.AccessControl;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the security roles container.
        string containerPath = service.Backend.GetConfigurationContainerPath("AccessControlRoles");

        // Build the ADS path of the nested container 'My Container' and bind to it.
        AdsPath securityRolesPath = new AdsPath(containerPath);
        AdsPath myContainerPath = securityRolesPath.CreateChildPath("CN=My Container");

        IADsContainer myContainer = (IADsContainer)service.OpenObject(
                myContainerPath.ToString(), null, null, 0);

        // Create a security role and save it.
        IAdmRole role = (IAdmRole)myContainer.Create("adm-Role", "CN=My Role");
        role.SetInfo();
    }
}

For details about how to create containers for security roles, see Creating security role containers.

After binding to the container, call the Create method of the IADsContainer interface supported by all containers.

The method takes two parameters. The first one is the object type, "adm-Role" in our case. The second one is a relative distinguished name of the new role.

Optional properties

The object returned by Create implements the IAdmRole interface. You can use it to specify optional security role properties before saving the role.

Description – the role description.
Disabled – if set to true, the security role will be created in a disabled state.

Finally, save the security role save by calling SetInfo.

Defining role permissions

To define the permissions of a security role, use the Permissions property of the IAdmRole interface. The property represents a collection of permission entries and implements the IAdmCollection interface.

Call IAdmCollection::Create to create a new permission entry. Permission entries implement the IAdmRolePermissionEntry interface. Use its properties to specify what the permission entry allows/denies.

AccessMask – a flag or a set of flags that specify the access rights. The ADS_RIGHTS_ENUM enumeration lists all the available access rights.
ObjectType – the GUID that identifies what object type, property, property set, or extended right to apply the access rights to.
- The GUID must refer to a property when ADS_RIGHT_DS_READ_PROP and ADS_RIGHT_DS_WRITE_PROP access masks are used. If left empty, the access right will be applied to all properties (permission to Read or Write all properties respectively).
- The GUID must specify an object type when ADS_RIGHT_DS_CREATE_CHILD and ADS_RIGHT_DS_DELETE_CHILD access masks are used. If left empty, the access right will be applied to all child object types (permission to Create or Delete all child objects respectively).
- The GUID must specify an extended right when ADS_RIGHT_DS_CONTROL_ACCESS access mask is used. To obtain the GUID of a particular extended right use the ExtendedRights class.
InheritedObjectType – the GUID that identifies an object type that will inherit the access right(s). For instance, if you specify the GUID of the group object type, whatever rights you specified in AccessMask and ObjectType will apply only to groups.
AccessType – determines whether the permission is allowed or denied. The ADM_PERMISSION_TYPE_ENUM enumeration lists the available access types.

Before adding a permission entry to a security role, you need to save this entry by calling SetInfo. Once saved, add it to the collection of permissions of a role using IAdmCollection::Add.

Examples

Example 1 – Allow creating user accounts in all container types

The following code sample creates a permission that allows creating user accounts in containers of any type (organizational unit, container, etc.).

PowerShell

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

# Create a permission entry.
# The $role variable refers to a security role.
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW" # Allow
$entry.AccessMask = "ADS_RIGHT_DS_CREATE_CHILD" # Create child objects
$entry.ObjectType = $userClassGuid              # Specifically, users
$entry.InheritedObjectType = $null              # in containers of any type

# Save the permission entry and add it to the role.
$entry.SetInfo()
$role.Permissions.Add($entry)

C#

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

// Create a permission entry.
// The role variable refers to a security role.
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW; // Allow
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_CREATE_CHILD;          // Create child objects
entry.ObjectType = userClassGuid;                                      // Specifically, users
entry.InheritedObjectType = null;                                      // in containers of any type

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

Example 2 – Allow deleting all types of objects but deny deleting groups

The following code sample creates two permissions. One allows deleting all objects and another denies deleting groups.

PowerShell

# Create a permission entry - Allow Delete All Child Objects.
# The $role variable refers to a security role.
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW" # Allow
$entry.AccessMask = "ADS_RIGHT_DS_DELETE_CHILD" # Delete child objects
$entry.ObjectType = $null                       # Any child objects
$entry.InheritedObjectType = $null              # From containers of any type

# Save the permission entry and add it to the role.
$entry.SetInfo() 
$role.Permissions.Add($entry)

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

# Create a permission entry - Deny Delete Group Objects
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_DENY"  # Deny
$entry.AccessMask = "ADS_RIGHT_DS_DELETE_CHILD" # Delete child objects
$entry.ObjectType = $groupClassGuid             # Specifically, groups
$entry.InheritedObjectType = $null              # From containers of any type

# Save the permission entry and add it to the role.
$entry.SetInfo()
$role.Permissions.Add($entry)

C#

// Create a permission entry - Allow Delete All Child Objects.
// The role variable refers to a security role.
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW; // Allow
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_DELETE_CHILD;          // Delete child objects
entry.ObjectType = null;                                               // Any child objects       
entry.InheritedObjectType = null;                                      // From containers of any type

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

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

// Create a permission entry - Deny Delete Group Objects.
entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_DENY; // Deny
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_DELETE_CHILD;         // Delete child objects
entry.ObjectType = groupClassGuid;                                    // Specifically, groups
entry.InheritedObjectType = null;                                     // From containers of any type

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

Example 3 – Allow viewing computer objects

The following code sample creates a permission that allows viewing computers.

PowerShell

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

# Create a permission entry.
# The $role variable refers to a security role.
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW" # Allow
$entry.AccessMask = "ADS_RIGHT_GENERIC_READ"    # Read
$entry.InheritedObjectType = $computerClassGuid # Computers
$entry.ObjectType = $null

# Save the permission entry and add it to the role.
$entry.SetInfo()
$role.Permissions.Add($entry)

C#

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

// Create a permission entry.
// The role variable refers to a security role.
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW; // Allow
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_GENERIC_READ;             // Read
entry.InheritedObjectType = computerClassGuid;                         // Computers
entry.ObjectType = null;

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

Example 4 – Allow adding members to groups

The following code sample creates a permission that allows reading and writing the Member property of group objects.

PowerShell

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

# Create a permission entry.
# The $role variable refers to a security role.
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"                       # Allow
$entry.AccessMask = "ADS_RIGHT_DS_READ_PROP, ADS_RIGHT_DS_WRITE_PROP" # Read and Write
$entry.ObjectType = $memberPropGuid                                   # Member property
$entry.InheritedObjectType = $groupClassGuid                          # of Group objects

# Save the permission entry and add it to the role.
$entry.SetInfo()
$role.Permissions.Add($entry)

C#

// The GUIDs of the Group object class and the Member property.
const string groupClassGuid = "{bf967a9c-0de6-11d0-a285-00aa003049e2}";
const string memberPropGuid = "{bf9679c0-0de6-11d0-a285-00aa003049e2}";

// Create a permission entry.
// The role variable refers to a security role.
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW; // Allow
entry.AccessMask =                                                     //
    ADS_RIGHTS_ENUM.ADS_RIGHT_DS_READ_PROP |                           // Read and
    ADS_RIGHTS_ENUM.ADS_RIGHT_DS_WRITE_PROP;                           // Write
entry.ObjectType = memberPropGuid;                                     // Member property
entry.InheritedObjectType = groupClassGuid;                            // of Group objects

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

Example 5 – Allow resetting passwords of user accounts

The following code sample creates a permission that allows resetting passwords of user accounts.

PowerShell

# The GUIDs of the User object class and the Reset Password extended right.
$userClassGuid = "{bf967aba-0de6-11d0-a285-00aa003049e2}"
$resetPasswordRight = [Softerra.Adaxes.Ldap.ExtendedRights]::UserForceChangePassword

# Create a permission entry.
# The $role variable refers to a security role.
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_ALLOW"   # Allow
$entry.AccessMask = "ADS_RIGHT_DS_CONTROL_ACCESS" # Extended right
$entry.ObjectType = $resetPasswordRight           # of type Reset Password
$entry.InheritedObjectType = $userClassGuid       # for User objects

# Save the permission entry and add it to the role.
$entry.SetInfo()
$role.Permissions.Add($entry)

C#

// The GUIDs of the User object class and the Reset Password extended right.
const string userClassGuid = "{bf967aba-0de6-11d0-a285-00aa003049e2}";
string resetPasswordRight = ExtendedRights.UserForceChangePassword;

// Create a permission entry.
// The role variable refers to a security role.
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_ALLOW; // Allow
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_CONTROL_ACCESS;        // Extended right
entry.ObjectType = resetPasswordRight;                                 // of type Reset Password
entry.InheritedObjectType = userClassGuid;                             // for User objects

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

Example 6 – Deny viewing security sensitive reports

The following code sample creates a permission that denies viewing the reports from the built-in Security Sensitive category.

PowerShell

# The GUID of the built-in Security Sensitive report category.
$categoryGuid = "{0abe0df3-0621-47d4-8dee-dde6aaaf8099}"

# Create a permission entry.
# The $role variable refers to a security role.
$entry = $role.Permissions.Create()
$entry.AccessType = "ADM_PERMISSION_TYPE_DENY"                            # Deny
$entry.AccessMask = "ADS_RIGHT_DS_CONTROL_ACCESS"                         # Extended right
$entry.ObjectType = [Softerra.Adaxes.Ldap.ExtendedRights]::GenerateReport # of type View reports
$entry.InheritedObjectType = $categoryGuid                                # Security Sensitive

# Save the permission entry and add it to the role.
$entry.SetInfo()
$role.Permissions.Add($entry)

C#

// The GUID of the built-in Security Sensitive report category.
const string categoryGuid = "{0abe0df3-0621-47d4-8dee-dde6aaaf8099}";

// Create a permission entry.
// The role variable refers to a security role.
IAdmRolePermissionEntry entry = (IAdmRolePermissionEntry)role.Permissions.Create();
entry.AccessType = ADM_PERMISSION_TYPE_ENUM.ADM_PERMISSION_TYPE_DENY; // Deny
entry.AccessMask = ADS_RIGHTS_ENUM.ADS_RIGHT_DS_CONTROL_ACCESS;       // Extended right
entry.ObjectType = ExtendedRights.GenerateReport;                     // of type View reports
entry.InheritedObjectType = categoryGuid;                             // Security Sensitive 

// Save the permission entry and add it to the role.
entry.SetInfo();
role.Permissions.Add(entry);

To grant this right over a custom report category, you need to know its identifier. To get it, bind to the Report Categories container and get the CategoryId of the category you need.

Example

$container = $Context.GetWellKnownContainerPath("ReportCategories")
$categories = $container.GetReportCategories()
$myCategory = $categories | Where {$_.CategoryName -eq "My category"}
$guid = $myCategory.CategoryId

Assigning a security role

To add assignments to a security role, use the Assignments property of the IAdmRole interface. The property represents a collection of assignments and implements the IAdmCollection interface.

Call IAdmCollection::Create to create a new assignment. Assignments implement the IAdmRoleAssignment interface. Use its properties to define the assignment details.

Trustee – the user, group, or well-known security principal you want to assign the role to. Accepts a string with either of those:
- The trustee's SID in the SDDL format (e.g. S-1-5-1-123-456-789)
- The user's logon name (e.g. DOMAIN\username, username@domain.com)
- The group name
TrusteeDomain – 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 the trustee is a built-in group, such as BUILTIN\Users. The property accepts a string that contains either the DNS name of the domain or the domain SID in the SDDL format.
ActivityScopeItems – the scope of the role assignment. The scope determines where in your directory the trustee will be able to exercise their permissions. This property represents a collection of scope items and implements the IAdmCollection interface.

Call IAdmCollection::Create to create a new scope item. Scope items implement the IAdmActivityScopeItem interface. Use its properties to specify the scope item details.
- Type – the scope item type. The ADM_SCOPEBASEOBJECTTYPE_ENUM enumeration lists the available scope types.
- Inheritance – depends on the scope item type. For example, if Type is set to ADM_SCOPEBASEOBJECTTYPE_GROUP, the value of Ineritance controls whether all group members or only direct members will be included to the activity scope. The ADS_SCOPEENUM enumeration lists the available inheritance types.
- BaseObject – the base object of the scope. For example, if you want to include all objects located in a specific organizational unit, set that OU as the base object. If you want to include all members of a group, set that group as the base object.
- Exclude – specify false to include the scope item into the role scope or specify true to exclude it.

The following table contains all the possible property combinations for different activity scope items.

Activity scope item property combinations

Activity scope
Type, Inheritance, and 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 objects in an OU, including nested objects
- ADM_SCOPEBASEOBJECTTYPE_CONTAINER
- ADS_SCOPE_SUBTREE
- An ADSI object representing the OU.
Objects located directly in 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.
Adaxes Configuration Objects
- ADM_SCOPEBASEOBJECTTYPE_CONFIGURATION
- ADS_SCOPE_SUBTREE
- null

Before adding a scope item to a security role, you need to save this item by calling SetInfo. Once saved, add it to the collection of scope items using IAdmCollection::Add.

Examples

Example 1 – Assign a role to a user over All Objects

The following code sample assigns a security role to the user named Administrator over all objects.

PowerShell

# The $role variable refers to a security role.

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

# Create an activity scope item.
$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $null
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $false
$scopeItem.SetInfo()

# Add assignment to the role.
$assignment.ActivityScopeItems.Add($scopeItem)
$role.Assignments.Add($assignment)

C#

// The role variable refers to a security role.

// Create an assignment.
IAdmRoleAssignment assignment = (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\Administrator";
assignment.SetInfo();

// Create an activity scope item.
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();

// Add assignment to the role.
assignment.ActivityScopeItems.Add(scopeItem);
role.Assignments.Add(assignment);

Example 2 – Assign a role to a user over all objects in a domain

The following code sample assigns a security role to the user named John Smith over all objects in the example.com domain.

PowerShell

# The $role variable refers to a security role.

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

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

# Create an activity scope item.
$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $domainObj
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $false
$scopeItem.SetInfo()

# Add assignment to the role.
$assignment.ActivityScopeItems.Add($scopeItem)
$role.Assignments.Add($assignment)

C#

// The role variable refers to a security role.

// Create an assignment.
IAdmRoleAssignment assignment = (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\jsmith";
assignment.SetInfo();

// Bind to the domain object
const string domain = "example.com";
IAdmTop domainObj = (IAdmTop)service.OpenObject($"Adaxes://{domain}", null, null, 0);

// Create an activity scope item.
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();

// Add assignment to the role.
assignment.ActivityScopeItems.Add(scopeItem);
role.Assignments.Add(assignment);

Example 3 – Assign a role to a group over another group (not group members)

The following code sample assigns a security role to the group named Help Desk over the group named Sales, but not over the members of that group.

PowerShell

# The $role variable refers to a security role.

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

# Bind to the Sales group.
$groupDN = "CN=Sales,DC=example,DC=com"
$group = $service.OpenObject("Adaxes://$groupDN", $null, $null, 0)

# Create an activity scope item.
$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $group
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_BASE"
$scopeItem.Exclude = $false
$scopeItem.SetInfo()

# Add assignment to the role.
$assignment.ActivityScopeItems.Add($scopeItem)
$role.Assignments.Add($assignment)

C#

// The role variable refers to a security role.

// Create an assignment.
IAdmRoleAssignment assignment = (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "EXAMPLE\\Help Desk";
assignment.SetInfo();

// Bind to the Sales group.
const string groupDN = "CN=Sales,DC=example,DC=com";
IAdmTop group = (IAdmTop)service.OpenObject($"Adaxes://{groupDN}", null, null, 0);

// Create an activity scope item.
IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = group;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_BASE;
scopeItem.Exclude = false;
scopeItem.SetInfo();

// Add assignment to the role.
assignment.ActivityScopeItems.Add(scopeItem);
role.Assignments.Add(assignment);

Example 4 – Assign a role to managers over their subordinates in an OU

The following code sample assigns a security role to the Manager well-known security principal over all objects located directly in the organizational unit named Employees.

PowerShell

# The $role variable refers to a security role.

# Create an assignment.
$assignment = $role.Assignments.Create()
$assignment.Trustee = "S-1-9-2" # Well-known SID of 'Manager'
$assignment.SetInfo()

# Bind to the organizational unit.
$ouDN = "OU=Employees,DC=example,DC=com"
$ou = $service.OpenObject("Adaxes://$ouDN" ,$null, $null, 0)

# Create an activity scope item.
$scopeItem = $assignment.ActivityScopeItems.Create()
$scopeItem.BaseObject = $ou
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_ONELEVEL"
$scopeItem.Exclude = $false
$scopeItem.SetInfo()

# Add assignment to the role.
$assignment.ActivityScopeItems.Add($scopeItem)
$role.Assignments.Add($assignment)

C#

// The role variable refers to a security role.

// Create an assignment.
IAdmRoleAssignment assignment = (IAdmRoleAssignment)role.Assignments.Create();
assignment.Trustee = "S-1-9-2"; // Well-known SID of 'Manager'
assignment.SetInfo();

// Bind to the organizational unit.
const string ouDN = "OU=Employees,DC=example,DC=com";
IAdmTop ou = (IAdmTop)service.OpenObject($"Adaxes://{ouDN}", null, null, 0);

// Create an activity scope item.
IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)assignment.ActivityScopeItems.Create();
scopeItem.BaseObject = ou;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_ONELEVEL;
scopeItem.Exclude = false;
scopeItem.SetInfo();

// Add assignment to the role.
assignment.ActivityScopeItems.Add(scopeItem);
role.Assignments.Add(assignment);

For more examples, see Assigning security roles

Modifying a role

To modify an existing security role, you need to connect to your Adaxes service and bind to the directory object representing the role.

If your script will be executed inside Adaxes, it is even simpler. You don't have to explicitly connect to your Adaxes service. Instead, you can get the ADS path of the AccessControlRoles container and bind to a rule using a predefined PowerShell variable $Context.

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

After binding to the role, you can use the IAdmRole and IADs interfaces to modify the rule. To save the changes, call SetInfo.

Examples

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

PowerShell

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

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

# Bind to the role.
$rolesPath = $service.Backend.GetConfigurationContainerPath("AccessControlRoles")
$rolesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $rolesPath
$rolePath = $rolesPathObj.CreateChildPath("CN=My Role")
$role = $service.OpenObject($rolePath.ToString(), $null, $null, 0)

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

# Save the changes.
$role.SetInfo()

C#

using System;
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 ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the role.
        string rolesPath = service.Backend.GetConfigurationContainerPath("AccessControlRoles");
        AdsPath rolesPathObj = new AdsPath(rolesPath);
        AdsPath rolePath = rolesPathObj.CreateChildPath("CN=My Role");
        IAdmRole role = (IAdmRole)service.OpenObject(rolePath.ToString(), null, null, 0);

        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.

PowerShell

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

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

# Bind to the role.
$rolesPath = $service.Backend.GetConfigurationContainerPath("AccessControlRoles")
$rolesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $rolesPath
$containerPathObj = $rolesPathObj.CreateChildPath("CN=My Container")
$rolePath = $containerPathObj.CreateChildPath("CN=My Role")
$role = $service.OpenObject($rolePath.ToString(), $null, $null, 0)

# Make the changes.
$role.Permissions.Clear()
$role.Assignments.Clear()

C#

using System;
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 ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the role.
        string rolesPath = service.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)service.OpenObject(rolePath.ToString(), null, null, 0);

        /// Make the changes.
        role.Permissions.Clear();
        role.Assignments.Clear();
    }
}

Managing security roles

Creating a security role

Details

Optional properties

Defining role permissions

Examples

Assigning a security role

Activity scope

Type, Inheritance, and BaseObject

Examples

Modifying a role

Examples

See also