Using Active Roles Controls (4340886) (2024)

Active Roles supports built-in controls and custom controls. The controls are described below.

The built-in controls are processed by Administration Service in the predefined way described in the following table. In the table, the column 1 lists the control constants (if exist) while the column 2 lists the control IDs. For built-in controls, IDs can be string values or integers.

Constant

Control ID

Details

EDS_CONTROL_FIX

This control can be used only in the request to check policy compliance.

When this control is set, the policy(ies) processing the request can change the object's property values that don't meet the policy.

You can set this control to an array that contains GUIDs of the selected Policy Objects. In this case, only the policies you have specified will be able to change the object's property values that don't meet the policy.

EDS_CONTROL_CHECK_POLICY_COMPLIANCE

This control can be used only in the request to check policy compliance.

When this control is set, the policy(ies) processing the request will validate all properties of the processed object.

You can set this control to an array that contains GUIDs of the selected Policy Objects. In this case, only the policies you have specified will validate all properties of the processed object.

EDS_CONTROL_GC_SERVER_DOMAIN

This control can be used in a request to search Active Directory. Setting this control causes the Administration Service to search the global catalog.

The control sets the distinguished name of the domain used to select the Global Catalog server to search the global catalog.

EDS_CONTROL_BYPASS_DIRECTORY_REQUEST

This control can be used in any request.

When this control is set, the request will be only processed by Administrative Policies. Administration Service will not propagate changes to the underlying directory store or to the Active Roles configuration database.

EDS_CONTROL_SILENT_MODE

This control can be used in any request.

By default, the policy scripts can return the error messages. When a request sets this control to any value, all exceptions raised during the request processing will be disabled.

EDS_CONTROL_TREE_DELETE

This control can be used in a request to delete a directory object.

By default, Active Roles clients cannot delete a container object when it has child objects. If the request to delete the container sets this control to any value, the container and all its children will be deleted.

EDS_CONTROL_OBJECT_DN

This control can be used in a request to create, move, rename, modify or deprovision a directory object. In your policy scripts, this control is available within the onPostCreate, onPostMove, onPostRename, onPostModify, and onPostDeprovision event handlers.

The control contains the distinguished name the directory object has after the appropriate operation results have been committed.

EDS_CONTROL_LDAP_SERVER

This control can be used in any request.

When this control is not set, the domain controller (DC) Active Roles uses to process the request is determined by the Active Roles default settings.

Setting this control to the DC name causes Active Roles to use that DC for the request processing.

EDS_CONTROL_DELETE_LINKS

This control can be used in a request to delete a Policy Object or an Access Template.

By default, Active Roles clients cannot delete Policy Objects or Access Templates that are linked to directory objects.

When this control is set, Active Roles clients can delete any Policy Object or Access Template.

EDS_CONTROL_FULL_EFFECTIVE_POLICY_INFO

This control can be used only in request to get effetive policy information.

For performance reasons, by default, the GetEffectivePolicyInfo request does not return the attributes whose values are normally generated by Active Roles.

To obtain the attributes values, the client must request them from Active Roles by setting the control with an array of ldapName for each attribute whose value(s) is requested.

EDS_CONTROL_GET_HEAVY_ATTRIBUTES

Add this control to a Get request if you want to retrieve so-called "heavy" attributes - the attributes that Active Roles takes long time to calculate. Without this control, a Get request does not retrieve "heavy" attributes for performance reasons.

"Heavy" attributes are marked with the EDS_ATTRIBUTEFLAG_HEAVY_ATTRIBUTE = 0x00000800 flag in the edsaAttributeFlags attribute of the attributeSchema object in the Active Roles directory schema. Some examples of "heavy" attributes are EDSA-Mailbox-Security-Descriptor (edsaMailboxSecurityDescriptor) and EDSVA-MsExch-Shared-Mailbox-Users (edsva-MsExch-SharedMailboxUsers).

You can add this control to a Get request by using a policy script with the following onPreGet event handler function:

function onPreGet($Request)
{ $Request.PutInControl("43",0,0) }

EDS_CONTROL_SOURCE_OBJECT_DN

Contains the DN of the object to copy.

This control is available within the onPreCreate, onPostCreate, onGetEffectivePolicy and onCheckPropertyValues event handlers.

AllowApproval

This control is used in the approval workflow. If the operation does not require approval, this control has no effect, otherwise:

if not set, and the user is an Active Roles Admin, the operation will be executed without approval

if not set, and the user is not an Active Roles Admin, the operation will fail with an error

if the control is set to "Check", the information about the approval will be returned, however, the operation will not be stored or executed

if the control is set to "Confirm", the information about the approval will be returned, and the operation will be stored for subsequent approval by designated approvers.

ApplicationID

Allows to perform an operation on behalf of an edsApplication object.

The control must be set to a string containing a GUID of an existing edsApplication object, such as '12345678-1234-1234-1234-123456789012'.

When this control is set, the specified application is considered as an initiator of the operation, which affects Approval and Change History behavior.

Note that this control can only be specified by an Active Roles Admin.

IndirectMembership-GetData

When set in an ASQ search request for group memberships, this control causes the search result set to include the objects whose membership is because of group nesting.

Can be set to any string value, such as "1".

InheritInitiatorInfo

This control can be used in policy or workflow scripts. Can be set to any string value, such as "1".

When this control is set in a request initiated from a script, the Administration Service treats the request as if it were initiated by the client that requested the operation that caused the script to execute. As a result, the requested changes are properly recorded in the management history trail (change history), and are submitted for approval if this is required by the approval rules that are in effect.

When this control is not set, the Administration Service itself is considered the initiator of the request. The result is that the requested changes do not appear in the management history trail (change history), nor are they submitted for approval.

OperationID

Returned by Administration Service to indicate the current operation ID.

OperationReason

This control can be used in any request to perform an administrative operation.

The control contains any information message a client (such as your custom ADSI script) sends to Administration Service.

If the operation requires approval, the information message will be sent to approver.

After performing the requested operation, the information message is displayed in Change History report for modified objects.

OperationStatus

Returned by Administration Service to indicate the current operation status.

The returned string corresponds to the value of the "status" attribute in the XML operation and can take any of the following values:

"Canceled" - The operation has been canceled.
"Completed" - All tasks were successfully completed.
"Denied" - The operation was denied because one of the approval tasks was Completed-Rejected.
"Failed" -An error occurred when executing the operation.
"InProgress" - The operation is in progress (this status does not include a post-policy processing)
"Pending" - The operation is waiting for a task completion.

PreventHomeFolderPermissionsChange

This control determines the behavior of the Administration Service upon processing a request to set home folder on a user account in Active Directory.

Setting this control to any value, such as "1", ensures that the Administration Service does not attempt to modify security settings on the home folder.
If this control is not set, the behavior of the Administration Service depends on whether the user is affected by the Home Folder Autoprovisioning Policy. For more information, refer to "Home Folder AutoProvisioning" in the Active Roles Administrator Guide.

PrimaryGroup-GetData

When set in an ASQ search request for group memberships, this control causes the search result set to include the objects whose membership is because of primary group setting.

Can be set to any string value, such as "1".

ReturnXmlOperation

When set, this control instructs the Administration Service to return the information about the performed operation in the XmlOperation output control.

Can be set to any string value, such as "1".

ScheduledOperation-SetTime

In a request to perform a particular operation, specifies the date and time when the operation is to occur. This control must conform to the GeneralizedTime syntax.

For example, if in the request to add an object to a group you set this control to specific time, the object will be actually added to the group members list only at the scheduled time.

Note Setting the ScheduledOperation-SetTime control to "Now" causes Active Roles to immediately add object to a group. However, this operation does not change the time when object will be removed from the group.

Setting the ScheduledOperation-SetTime control to "Never" cancels the scheduled removing of object from the group. However, this operation does not change the time when object will be added to the group.

ScheduledLink-GetStartEndTime

When set in an ASQ search request against a linked attribute, this control causes objects returned by the search to contain information about when creation or deletion of the link for each of those objects is scheduled to occur.

ScheduledLink-GetPending

When set in an ASQ search request against a linked attribute, this control causes the search result set to include the objects for which creation of the link is scheduled to occur in the future.

ShowDeletedObjectsContainer

This control is available only within the onPreSearch event handler.

Set this control to any value when performing a one-level search on the Active Directory node if you want the search results to include the Deleted Objects container.

ShowRecycledObjects

This control is available only within the onPreSearch event handler.

Set this control to any value to specify that the search results should include recycled objects. When searching the Deleted Objects container, a client has to add this control to the Search request in order for the server to return both the deleted and recycled objects that match the search filter. Without this control, the server returns only deleted objects.

XmlOperation

Returned by the Administration Service if the ReturnXmlOperation control was specified.

Contains information about the performed operation in XML format.

FunctiontoDeclareParameters

This control is used to a request for parameter definitions in order to pass the name of the function that is used to declare parameters in the script module.

If not set, the parameters are declared using the onInit function.

All built-in controls are InControls, except the EDS_CONTROL_OBJECT_DN, OperationID, OperationStatus and XmlOperation controls. All built-in controls must have values of the CaseIgnoreString type.

Custom Controls

You can create your own custom controls that can be sent to the Administration Service and then processed by your custom policy scripts. Depending on the custom control value, the policy scripts can affect the way the request is processed by Administration Service.

Getting and Setting Active Roles Controls

You can get/set values of the custom or built-in Active Roles controls in one of the following ways:

For the Active Roles clients, such as your custom scripts, use the Control property provided by the IEDM interface.

For Policy scripts, use the GetInControl, GetOutControl/PutInControl, PutOutControl methods of the IEDsRequestParameters interface.

Examples

To clarify how you can use Active Roles controls, consider the following examples.

Sample Policy Script

The following policy script illustrates how you can set the value of the built-in control EDS_CONTROL_TREE_DELETE.

[VBScript]

Sub onPreDelete(Request)

Request.PutInControl EDS_CONTROL_TREE_DELETE, ADSTYPE_CASE_IGNORE_STRING, Array("any")

End Sub

[PowerShell]

function onPreDelete($Request)

{

$Request.PutInControl($Constants.EDS_CONTROL_TREE_DELETE,$Constants.ADSTYPE_CASE_IGNORE_STRING, "Any")

)

If you apply the Policy Object that includes this script policy to a container object, such as an Organizational Unit, you will be able to delete the container, even if that container has child objects. Note that you may set the control EDS_CONTROL_TREE_DELETE to any string value ("any" in this example).

Sample Custom Script

The following sample code illustrates how you can set the Active Roles built-in control in your custom script.

[VBScript]

const EDS_CONTROL_LDAP_SERVER = 13

' Create User object in the specified OU

Set cont = GetObject("EDMS://OU=Sales,DC=Mycompany,DC=com")

Set usr = cont.Create("user", "CN=John MCDuglas")

' Set the User properties

usr.Put "samAccountName", "JMCDuglas"

usr.Put "edsaAccountIsDisabled", FALSE

' Set the InControl value

usr.Control(EDS_CONTROL_LDAP_SERVER)="FirstDC.Mycompany.com"

' Commit changes

usr.SetInfo

[PowerShell]

$EDS_CONTROL_LDAP_SERVER = 13

# Create User object in the specified OU

$cont = [ADSI]"EDMS://OU=Sales,DC=Mycompany,DC=com"

$usr = $cont.Create("user", "CN=John MCDuglas")

# Set the User properties

$usr.Put("samAccountName", "JMCDuglas")

$usr.Put("edsaAccountIsDisabled", $false)

# Set the InControl value

$usr.Control($EDS_CONTROL_LDAP_SERVER) = "FirstDC.Mycompany.com"

# Commit changes

$usr.SetInfo()

This script creates the new user John MCDuglas and sets the built-in control EDS_CONTROL_LDAP_SERVER to the name of the domain controller FirstDC.Mycompany.com. When the Administration Service receives that control, the request to create the user will be processed by the specified DC.