Chat now with support
Chat with Support

Active Roles 8.1.3 - Administration Guide

Introduction Getting started with Active Roles Configuring rule-based administrative views Configuring role-based administration Rule-based autoprovisioning and deprovisioning
Provisioning Policy Objects Deprovisioning Policy Objects How Policy Objects work Policy Object management tasks Policy configuration tasks
Property Generation and Validation User Logon Name Generation Group Membership AutoProvisioning Exchange Mailbox AutoProvisioning AutoProvisioning in SaaS products OneDrive Provisioning Home Folder AutoProvisioning Script Execution Microsoft 365 and Azure Tenant Selection E-mail Alias Generation User Account Deprovisioning Office 365 Licenses Retention Group Membership Removal Exchange Mailbox Deprovisioning Home Folder Deprovisioning User Account Relocation User Account Permanent Deletion Group Object Deprovisioning Group Object Relocation Group Object Permanent Deletion Notification Distribution Report Distribution
Deployment considerations Checking for policy compliance Deprovisioning users or groups Restoring deprovisioned users or groups Container Deletion Prevention policy Picture management rules Policy extensions
Using rule-based and role-based tools for granular administration Workflows
Key workflow features and definitions About workflow processes Workflow processing overview Workflow activities overview Configuring a workflow
Creating a workflow definition for a workflow Configuring workflow start conditions Configuring workflow parameters Adding activities to a workflow Configuring an Approval activity Configuring a Notification activity Configuring a Script activity Configuring an If-Else activity Configuring a Stop/Break activity Configuring an Add Report Section activity Configuring a Search activity Configuring CRUD activities Configuring a Save Object Properties activity Configuring a Modify Requested Changes activity Enabling or disabling an activity Enabling or disabling a workflow Using the initialization script
Approval workflow Email-based approval Automation workflow Activity extensions
Temporal Group Memberships Group Family Dynamic groups Active Roles Reporting Management History Entitlement profile Recycle Bin AD LDS data management One Identity Starling Join and configuration through Active Roles Managing One Identity Starling Connect Configuring linked mailboxes with Exchange Resource Forest Management Configuring remote mailboxes for on-premises users Migrating Active Roles configuration with the Configuration Transfer Wizard Managing Skype for Business Server with Active Roles
About Skype for Business Server User Management Active Directory topologies supported by Skype for Business Server User Management User Management policy for Skype for Business Server User Management Master Account Management policy for Skype for Business Server User Management Access Templates for Skype for Business Server Configuring the Skype for Business Server User Management feature Managing Skype for Business Server users
Exchanging provisioning information with Active Roles SPML Provider Monitoring Active Roles with Management Pack for SCOM Configuring Active Roles for AWS Managed Microsoft AD Azure AD, Microsoft 365, and Exchange Online Management
Configuring Active Roles to manage Hybrid AD objects Unified provisioning policy for Azure M365 Tenant Selection, Microsoft 365 License Selection, Microsoft 365 Roles Selection, and OneDrive provisioning Changes to Active Roles policies for cloud-only Azure objects
Managing the configuration of Active Roles
Connecting to the Administration Service Managed domains Using unmanaged domains Evaluating product usage Creating and using virtual attributes Examining client sessions Monitoring performance Customizing the Console Using Configuration Center Changing the Active Roles Admin account Enabling or disabling diagnostic logs Active Roles Log Viewer
SQL Server replication Using regular expressions Administrative Template Configuring federated authentication Communication ports Active Roles and supported Azure environments Integrating Active Roles with other products and services Active Roles Language Pack Active Roles Diagnostic Tools Active Roles Add-on Manager

SPML Provider capability samples

The following tables list all search, password and suspend capability examples included in the Capability samples.

Search Capability samples
Table 103: Search Capability samples

Operation

Description

Perform one-level search

This example illustrates how to obtain a list of the child objects (direct descendants) of the Active Directory container object. In proxy mode, you can use this example to list the domains that are registered with Active Roles (managed domains).

To do this, SPML Provider performs the search operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <searchRequest> element asks SPML Provider to perform a search and return the identifiers of the objects found.

  • The <query> element determines that SPML Provider is to perform a one-level search (that is, to search only direct descendants of the object specified by <basePsoID>).

  • The <basePsoID> element specifies the distinguished name of the container object to search.

The response contains the identifiers (distinguished names) of the objects residing in the container object specified by the <basePsoID> element.

Perform subtree search

This example illustrates how to obtain a list of objects that reside below the Active Directory object in the directory tree. You can use this example to list the objects that reside in a given domain.

To do this, SPML Provider performs the search operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <searchRequest> element asks SPML Provider to perform a search and return the identifiers of the objects found.

  • The <query> element determines that SPML Provider is to perform a subtree search (that is, to search any direct or indirect descendant of the object specified by <basePsoID>).

  • The <basePsoID> element specifies the distinguished name of the container object to search. For instance, this could be the distinguished name of a domain that is registered with Active Roles (managed domain).

The response contains the identifiers (distinguished names) of the objects that reside in the directory tree below the container object specified by the <basePsoID> element.

Perform base search

This example illustrates how to obtain an XML representation of the specific object.

To do this, SPML Provider performs the search operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <searchRequest> element asks SPML Provider to perform a search and return the XML representation of the object found.

  • The <query> element determines that SPML Provider is to perform a base search (that is, to search only the object identified by <basePsoID>).

  • The <basePsoID> element specifies the distinguished name of the object to search. For instance, this could be the distinguished name of a user account.

The response contains the identifier of the object and the XML representation of the object (as defined in the schema of the target).

Iterate search results

This example illustrates how to obtain the next set of objects from the result set that SPML Provider selected for a search operation.

In this case, SPML Provider performs the iterate operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <iterateRequest> element asks SPML Provider to return additional objects that matched a previous search request but that the Provider has not yet returned to the client.

  • The <iterator> element supplies the iterator ID found either in the original search response or in a subsequent iterate response.

Stop iterating search results

This example illustrates how to tell SPML Provider that the client has no further need for the search results that a specific iterator represents.

In this case, SPML Provider performs the closeIterator operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <closeIteratorRequest> element tells SPML Provider that the client no longer intends to iterate search results.

  • The <iterator> element specifies the ID of the iterator to close. This could be the iterator ID found in the original search response or in a subsequent iterate response.

Find inactive users

This example illustrates how to get a list of inactive (disabled or deprovisioned) user accounts found within a specified container.

To do this, SPML Provider performs the search operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <searchRequest> element asks SPML Provider to perform a search and return the identifiers of the objects found.

  • The <query> element determines SPML Provider is to perform a subtree search.

  • The <basePsoID> element specifies the distinguished name of the container object to search. For instance, this could be the distinguished name of a certain organizational unit.

  • The <filter> element encloses the elements that direct SPML Provider to search for inactive user accounts. Thus, the <equalityMatch> elements are configured so as to limit the search to user accounts; the <isActive> element combined with the <not> element causes SPML Provider to select the user accounts that are inactive.

  • The response contains the identifiers (distinguished names) of the inactive user accounts that exist in the directory tree below the container object specified by the <basePsoID> element.

Perform complex search

This example illustrates how to have SPML Provider find all objects that meet certain search criteria and return the values of certain attributes of the objects found.

In this case, SPML Provider performs the search operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <searchRequest> element asks SPML Provider to perform a search and return the identifiers and attribute values of the objects found.

  • The <query> element determines the scope of the search.

  • The <basePsoID> element specifies the distinguished name of the container object to search. For instance, this could be the distinguished name of a certain Organizational Unit.

  • The <filter> element encloses the elements that specify the search criteria.

  • The <attributes> element specifies the object attributes to be included in the response.

The response contains the identifiers (distinguished names) of the objects found and, for each object, the values of the attributes specified by the <attributes> element in the search request.

Find only security groups

This example illustrates how to obtain a list of security groups found in a specified container.

In this case, SPML Provider performs the search operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <searchRequest> element asks SPML Provider to perform a search and return the identifiers of the objects found.

  • The <query> element determines that SPML Provider is to perform a subtree search.

  • The <basePsoID> element specifies the distinguished name of the container object to search. For instance, this could be the distinguished name of a certain organizational unit.

  • The <filter> element encloses the elements that direct SPML Provider to search for security groups. Thus, the <equalityMatch> elements are configured so as to limit the search to group objects; the <extensibleMatch> element specifies a matching rule that is equivalent to the LDAP filter (groupType:1.2.840.113556.1.4.803:=2147483648) where 2147483648 is the decimal equivalent of the ADS_GROUP_TYPE_SECURITY_ENABLED flag (0x80000000).

The response contains the identifiers (distinguished names) of the security groups that exist in the directory tree below the container object specified by the <basePsoID> element.

Password Capability samples
Table 104: Password capability samples

Operation

Description

Set user password

This example illustrates how to set a new password for the specific user account.

To set a new password, SPML Provider performs the setPassword operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <setPasswordRequest> element asks SPML Provider to change to a specified value the password that is associated with a certain user account.

  • The <psoID> element specifies the distinguished name of the user account.

  • The <password> element specifies the new password to assign to the user account.

Expire user password

This example illustrates how to force a given user to change the password at next logon.

To do this, SPML Provider performs the expirePassword operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <expirePasswordRequest> element asks SPML Provider to mark expired the current password that is associated with a certain user account. The remainingLogins attribute is set to 1 so as to disallow grace logons once the expirePassword operation is completed, forcing the user to change the password at next logon.

  • The <psoID> element specifies the distinguished name of the user account.

Suspend Capability samples
Table 105: Suspend capability samples

Operation

Description

Suspend user account

This example illustrates how to either disable or deprovision a specified user account, depending on the SPML Provider configuration (see the description of the <suspendAction> element in the “Configuring SPML Provider” section earlier in this document).

To do this, SPML Provider performs the suspend operation.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <suspendRequest> element asks SPML Provider to perform the suspend action on a certain user account (either disable or deprovision, depending on the configuration of SPML Provider).

  • The <psoID> element specifies the distinguished name of the user account to suspend.

Resume user account

This example illustrates how to enable a disabled user account. This operation requires that the suspend action be set to disable in the SPML Provider configuration file (see the description of the <suspendAction> element in the “Configuring SPML Provider” section earlier in this document).

In this case, SPML Provider performs the resume operation in order to enable a disabled user account.

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <resumeRequest> element asks SPML Provider to re-enable a user account that has been disabled.

  • The <psoID> element specifies the distinguished name of the user account to re-enable.

Check whether user is active

This example illustrates how to determine whether a specified user account is active, that is, has not been suspended. A user account is considered to be suspended if the suspend action was performed on that account. The suspend action can be either disable or deprovision, depending on the SPML Provider configuration (see the description of the <suspendAction> element in the “Configuring SPML Provider” section earlier in this document).

The request message includes the following XML elements:

  • The <soap:Envelope> and <soap:Body> SOAP elements enclose the SPML payload.

  • The <activeRequest> element asks SPML Provider to check whether the suspend action has been performed on a given user account (either disable or deprovision, depending on the SPML Provider configuration).

  • The <psoID> element specifies the distinguished name of the user account to check.

The <activeResponse> element in the response message has the active attribute that indicates whether the specified user account is suspended. If the user account is suspended, the active attribute is set to false. Otherwise, the active attribute is set to true.

Active Roles SPML Provider terminology

Direct Access Mode

In this mode, SPML Provider directly connects to the specified domain or AD LDS instance.

Capabilities

A set of optional, functionally related operations defined in SPML v2.

Core Operations

The minimum set of operations that a provider must implement to conform to the official SPML v2 specification.

Extensible Markup Language (XML)

A meta-markup language that provides a format for describing structured data. This facilitates more precise declarations of content and more meaningful search results across multiple platforms. In addition, XML enables a new generation of Web-based data viewing and manipulation applications.

Organization for the Advancement of Structured Information Standards (OASIS)

An international consortium that drives the development, convergence, and adoption of e-business and Web service standards.

Provider

See Provisioning Service Provider.

Provisioning Service Object (PSO)

Represents a data entity or an information object on a target.

Provisioning Service Provider (PSP)

A software component that listens for, processes, and returns the results for well-formed SPML requests from a known requestor.

Provisioning Service Target (PST)

Represents a destination or endpoint that a provider makes available for provisioning actions.

Proxy Mode

In proxy mode, SPML Provider accesses directory data using the Active Roles proxy service.

Requesting Authority (RA)

A software component that issues well-formed SPML requests to a Provisioning Service Provider.

Requestor

See Requesting Authority.

Simple Object Access Protocol (SOAP)

An XML/HTTP-based protocol for platform-independent access to objects and services on the Web. SOAP defines a message format in XML that travels over the Internet using HyperText Transfer Protocol (HTTP). By using existing Web protocols (HTTP) and languages (XML), SOAP runs over the existing Internet infrastructure without being tied to any operating system, language, or object model.

SPML

An XML-based framework for exchanging user, resource, and service provisioning information between cooperating organizations.

SPML v2

An OASIS standard that provides a means of representing provisioning requests and responses as SPML documents.

Target

See Provisioning Service Target.

Target Schema

Defines the XML structure of the objects (PSO) that the target may contain.

Troubleshooting SPML Provider

This section briefly discusses some error statements that you may encounter when using SPML Provider.

Cannot remove the specified item because it was not found in the specified Collection

When sending an SPML request to remove a user from a group, the requested operation fails with the following error:

Cannot remove the specified item because it was not found in the specified Collection.
Solution

This error has one of the following causes:

  • The <value> element of the <attr> element specifies a user account that is not a member of the group.

  • The Distinguished Name fields, such as CN or OU, used in the distinguished name of the user account to be removed, have invalid spelling or case. The Distinguished Name fields must be in upper case. For example, using cn=Robert Smith instead of CN=Robert Smith can result in this error.

Verify that the <value> element specifies the distinguished name of the user that is the group member. Make sure that the Distinguished Name fields are in upper case.

The following example illustrates how to create a request to remove user Robert Smith from the Sales group.

<?xml version="1.0"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<modifyRequest xmlns="urn:oasis:names:tc:SPML:2:0" returnData="everything">
<psoID ID="CN=Sales,OU=SPML2,DC=Mycompany,DC=com"/>
<modification modificationMode="delete">
<data>
<attr name="member" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>CN=Robert Smith,OU=Staff,DC=MyCompany,DC=com</value>
</attr>
</data>
</modification>
</modifyRequest>
</soap:Body>
</soap:Envelope>
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating